skelly/CLAUDE.md

CLAUDE.md

Guidance for Claude Code (claude.ai/code) when working with this repository.

Required Context Files

Before doing anything else, get the following files in context:

• docs/ARCHITECTURE.md - System design, autoloads, architectural patterns
• docs/CODE_OF_CONDUCT.md - Coding standards, naming conventions, best practices
• project.godot - Input actions and autoload definitions

Auto-Generated Machine-Readable Documentation

⚠️ IMPORTANT: Before starting development, generate fresh code maps for current codebase context:

python tools/generate_code_map.py

This generates machine-readable JSON maps optimized for LLM consumption in .llm/ directory (git-ignored).

When to use:

• At the start of every development session
• After major refactoring or adding new files
• When you need current codebase structure/API reference

Core Development Rules

• Use TDD methodology for development
• Use static data types in all GDScript code
• Keep documentation up to date when making changes
• Always run tests: ./tools/run_development.py --yaml --silent

Code Maps (LLM Development Workflow)

Machine-readable code intelligence for LLM-assisted development.

Quick Reference: Which Map to Load?

Task	Load This Map	Size	Contains
Adding/modifying functions	code_map_api.json	~47KB	Function signatures, parameters, return types
System architecture work	code_map_architecture.json	~32KB	Autoloads, design patterns, structure
Signal/scene connections	code_map_flows.json	~7KB	Signal chains, scene transitions
Input validation/errors	code_map_security.json	~12KB	Validation patterns, error handling
Asset/resource management	code_map_assets.json	~12KB	Dependencies, preloads, licensing
Code metrics/statistics	code_map_metadata.json	~300B	Stats, complexity metrics

Generated Files (Git-Ignored)

Location: .llm/ directory (automatically excluded from git)

Format: All JSON files are minified (no whitespace) for optimal LLM token efficiency.

Total size: ~110KB if loading all maps (recommended: load only what you need)

Generating Code Maps

# Generate everything (default behavior - maps + diagrams + docs + metrics)
python tools/generate_code_map.py

# Generate only specific outputs
python tools/generate_code_map.py --diagrams  # Diagrams only
python tools/generate_code_map.py --docs      # Documentation only
python tools/generate_code_map.py --metrics   # Metrics dashboard only

# Explicitly generate all (same as no arguments)
python tools/generate_code_map.py --all

# Via development workflow tool
python tools/run_development.py --codemap

# Custom output location (single JSON file)
python tools/generate_code_map.py --output custom_map.json

# Skip PNG rendering (Mermaid source only)
python tools/generate_code_map.py --diagrams --no-render

New Features:

• Diagrams: Auto-generated diagrams (architecture, signal flows, scene hierarchy, dependencies) rendered to PNG using matplotlib
• Documentation: Human-readable markdown docs with embedded diagrams (AUTOLOADS_API.md, SIGNALS_CATALOG.md, FUNCTION_INDEX.md, etc.)
• Metrics: Markdown dashboard with statistics charts and complexity analysis

When to Regenerate

Regenerate code maps when:

• Starting an LLM-assisted development session - Get fresh context
• After adding new files - Include new code in maps
• After major refactoring - Update structure information
• After changing autoloads - Capture architectural changes
• When onboarding new developers - Provide comprehensive context

LLM Development Workflow

1. Generate maps: python tools/generate_code_map.py

2. Load relevant maps: Choose based on your task

   For API/Function development:

   Load: .llm/code_map_api.json (~47KB)
   Contains: All function signatures, parameters, return types, docstrings
   

   For architecture/system design:

   Load: .llm/code_map_architecture.json (~32KB)
   Contains: Autoloads, design patterns, system structure
   

   For signal/scene work:

   Load: .llm/code_map_flows.json (~7KB)
   Contains: Signal chains, scene transitions, connections
   

   For security/validation:

   Load: .llm/code_map_security.json (~12KB)
   Contains: Input validation patterns, error handling
   

   For assets/resources:

   Load: .llm/code_map_assets.json (~12KB)
   Contains: Asset dependencies, preloads, licensing
   

   For metrics/stats:

   Load: .llm/code_map_metadata.json (~300B)
   Contains: Code statistics, complexity metrics
   

3. Use selectively:

   • Load only maps relevant to current task
   • Reduces token usage and improves focus
   • Can always add more context later
   • Total size if loading all: ~110KB minified JSON

Essential Coding Patterns

Scene Management

# ✅ Correct - Use GameManager
GameManager.start_game_with_mode("match3")

# ❌ Wrong - Never call directly
get_tree().change_scene_to_file("res://scenes/game/Game.tscn")

Logging

# ✅ Correct - Use DebugManager with categories
DebugManager.log_info("Scene loaded successfully", "GameManager")
DebugManager.log_error("Failed to load resource", "AssetLoader")

# ❌ Wrong - Never use plain print/push_error
print("Scene loaded")  # No structure, no category
push_error("Failed")   # Missing context

Memory Management

# ✅ Correct - Use queue_free()
for child in children_to_remove:
    child.queue_free()
await get_tree().process_frame  # Wait for cleanup

# ❌ Wrong - Never use free()
child.free()  # Immediate deletion causes crashes

Input Validation

# ✅ Correct - Validate all inputs
func set_volume(value: float) -> bool:
    if value < 0.0 or value > 1.0:
        DebugManager.log_error("Invalid volume: " + str(value), "Settings")
        return false
    # Process validated input

# ❌ Wrong - No validation
func set_volume(value: float):
    volume = value  # Could be negative or > 1.0

See docs/CODE_OF_CONDUCT.md for complete coding standards.

Quick Reference

• Development commands: See docs/DEVELOPMENT.md
• Testing protocols: See docs/TESTING.md
• Architecture patterns: See docs/ARCHITECTURE.md
• Naming conventions: See docs/CODE_OF_CONDUCT.md
• Quality checklist: See docs/CODE_OF_CONDUCT.md

Project Structure

skelly/
├── src/autoloads/          # Global manager singletons
├── scenes/game/gameplays/  # Gameplay mode implementations
├── scenes/ui/              # Menu scenes and components
├── assets/                 # Audio, sprites, fonts (kebab-case)
├── data/                   # Godot resource files (.tres)
├── docs/                   # Documentation
├── tests/                  # Test scripts
└── tools/                  # Development tools

See docs/MAP.md for complete file organization.

Key Files to Understand

• src/autoloads/GameManager.gd - Scene transitions with race condition protection
• src/autoloads/SaveManager.gd - Save system with security features
• src/autoloads/SettingsManager.gd - Settings with input validation
• src/autoloads/DebugManager.gd - Unified logging and debug UI
• scenes/game/Game.gd - Main game scene, modular gameplay system
• scenes/game/gameplays/Match3Gameplay.gd - Match-3 implementation
• project.godot - Input actions and autoload definitions