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:

```bash
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

```bash
# 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
```gdscript
# ✅ 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
```gdscript
# ✅ 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
```gdscript
# ✅ 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
```gdscript
# ✅ 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](docs/CODE_OF_CONDUCT.md) for complete coding standards.

## Quick Reference

- **Development commands**: See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
- **Testing protocols**: See [docs/TESTING.md](docs/TESTING.md)
- **Architecture patterns**: See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- **Naming conventions**: See [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md#naming-convention-quick-reference)
- **Quality checklist**: See [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md#code-quality-checklist)

## 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](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