CLAUDE.md for Game Devs: The File That Makes AI Actually Understand Your Game
CLAUDE.md for Game Devs: The File That Makes AI Actually Understand Your Game
Here's a scenario every game dev using AI has hit:
You ask Claude Code to add a health system. It creates a beautiful, well-tested health component — in a completely different architecture than the rest of your game. Wrong naming conventions. Wrong file structure. Wrong everything.
The code works. It just doesn't belong in your project.
This is the CLAUDE.md problem. Without one, your AI agent is a brilliant developer who's never seen your codebase before — every single time you start a session. With one, it's a team member who knows your project's architecture, conventions, and quirks.
Here's how to write one for a game project.
What is CLAUDE.md?
CLAUDE.md is a markdown file you put in your project's root directory. Claude Code reads it automatically at the start of every session. It's your project's onboarding document — except the new hire has perfect memory and follows instructions exactly.
Other tools have equivalents — Cursor has .cursorrules, Copilot has .github/copilot-instructions.md. The concept is the same: give the agent context it can't infer from code alone.
For game projects, this matters more than most software. Games have:
- Complex entity/component systems
- Engine-specific patterns (Godot, Unity, Unreal all work differently)
- Game design rules that affect code architecture
- Art/audio asset pipelines
- Balance constants that look arbitrary without context
A web app's conventions might be guessable. Your game's conventions almost never are.
The Template
Here's the CLAUDE.md structure I use for my game projects. I'll explain each section, then show a complete example.
# CLAUDE.md
## Project Overview
[What is this game? Genre, engine, one-paragraph summary.]
## Tech Stack
[Engine, language, key libraries/plugins, build system.]
## Architecture
[How the code is organized. Scene tree structure,
autoloads, manager pattern, ECS — whatever your game uses.]
## Conventions
[Naming, file organization, code style rules specific
to this project.]
## Game Design Context
[Core mechanics the AI needs to understand to write
good code. Not the full GDD — just what affects
architecture decisions.]
## Common Tasks
[Step-by-step instructions for tasks the AI will
do repeatedly.]
## What NOT to Do
[Anti-patterns, things that break your game,
past mistakes to avoid.]
Section by Section
Project Overview
Keep it short. The AI needs to know what kind of game this is so it makes appropriate architectural choices.
## Project Overview
Stellar Throne is a single-player 4X strategy game built in Godot 4.3.
Turn-based gameplay with real-time combat resolution. Players explore
a procedurally generated galaxy, manage an empire, conduct diplomacy,
and wage war. Target: PC (Steam), ~20 hour campaigns.
Why this matters: An AI that knows it's working on a turn-based 4X will make different decisions than one working on a real-time action game. Data structures, update patterns, UI approaches — all different.
Tech Stack
Be specific. Version numbers matter.
## Tech Stack
- **Engine:** Godot 4.3 (GDScript)
- **UI:** Godot's built-in Control nodes, custom theme
- **Data:** JSON resource files in res://data/
- **Audio:** FMOD integration via GDNative
- **Build:** Godot export presets, CI via GitHub Actions
- **Testing:** GdUnit4 for unit tests
Architecture
This is the most important section. Be explicit about how your game is structured.
## Architecture
### Scene Tree
- Root
- GameManager (autoload) — game state, turn management
- UIManager (autoload) — screen transitions, modal stack
- AudioManager (autoload) — music, SFX via FMOD
- Main (current scene)
### Manager Pattern
We use singleton managers (autoloads) for global systems.
Managers communicate through signals, never direct references.
Signal flow: GameManager emits → Managers react → UI updates
### File Structure
- res://scenes/ — .tscn files organized by feature
- res://scripts/ — GDScript, mirrors scene structure
- res://data/ — JSON game data (units, techs, buildings)
- res://ui/ — UI scenes and scripts
- res://resources/ — Godot .tres resource files
- res://tests/ — GdUnit4 test files
### Entity Pattern
Game entities (stars, planets, fleets, empires) are Resource
classes in res://scripts/entities/. They are NOT nodes — they're
pure data. Nodes in scenes reference entities, not the other way.
### State Management
All game state lives in GameManager.current_game (GameState resource).
Never store game state in nodes. Nodes are views, entities are models.
This prevents the #1 AI mistake in game projects: putting game state in the wrong place.
Conventions
The stuff that makes your codebase consistent.
## Conventions
### Naming
- Classes: PascalCase (DiplomacyManager, FleetEntity)
- Functions: snake_case (calculate_reputation, spawn_fleet)
- Signals: past_tense_snake (turn_ended, fleet_moved, war_declared)
- Constants: UPPER_SNAKE (MAX_FLEET_SIZE, BASE_FOOD_PRODUCTION)
- JSON keys: snake_case
### Files
- One class per file
- Filename matches class name in snake_case
- Tests mirror source: scripts/combat/battle.gd → tests/combat/test_battle.gd
### Signals Over Calls
Systems communicate through signals. Never call methods on
managers directly from other managers. UI can call managers
directly for user actions.
### Comments
- Add comments explaining WHY, not WHAT
- Every public function needs a one-line docstring
- Game design rationale goes in comments when it affects code
Game Design Context
This is game-dev specific and incredibly valuable. The AI needs to understand your game's rules to write correct code.
## Game Design Context
### Core Loop
Explore → Expand → Exploit → Exterminate (4X)
Each turn: player issues orders → AI empires act → combat resolves → economy updates
### Key Systems
- **Economy:** 5 resources (food, production, science, gold, influence).
Planets produce based on buildings + population. Always integers, never floats.
- **Combat:** Fleet-vs-fleet, auto-resolved. Strength = sum of ship combat values
× admiral bonus × tech modifiers. Rock-paper-scissors between ship classes.
- **Diplomacy:** Reputation system (-100 to 100). Affects AI willingness
for treaties. Decays 1/turn toward 0.
- **Fog of War:** Tile-based visibility. Fleets reveal adjacent systems.
Sensor buildings extend range.
### Balance Constants
All balance values live in res://data/balance.json.
NEVER hardcode balance numbers in scripts.
Without this section, Claude might implement your economy with floats, hardcode balance values, or create a combat system that doesn't match your design.
Common Tasks
Step-by-step instructions for things you'll ask the AI to do repeatedly.
## Common Tasks
### Adding a New Building
1. Add entry to res://data/buildings.json (follow existing format)
2. Create building scene in res://scenes/buildings/
3. Add building logic to BuildingManager
4. Add UI entry in build menu (res://ui/panels/build_panel.tscn)
5. Write test in res://tests/buildings/
6. Update CHANGELOG.md
### Adding a New Tech
1. Add to res://data/tech_tree.json
2. Implement effect in TechManager.apply_tech()
3. Add icon to res://assets/icons/tech/
4. Test prerequisites chain works
This turns a vague request ("add a new building type") into a reliable, consistent result every time.
What NOT to Do
Learn from your mistakes — and your AI's mistakes.
## What NOT to Do
- Do NOT use Godot's built-in physics for game logic (we fake it with data)
- Do NOT put game state in nodes (entities are Resources, nodes are views)
- Do NOT use await in manager _ready() functions (causes load order bugs)
- Do NOT create new autoloads without discussing first
- Do NOT modify balance.json values in code — they're data-driven for a reason
- Do NOT use get_tree().change_scene() — use UIManager.transition_to()
This section alone will save you hours of debugging AI-generated code.
A Complete Example
Here's a trimmed but real CLAUDE.md from one of my projects:
# CLAUDE.md — Stellar Throne
## Overview
Single-player 4X strategy game. Godot 4.3, GDScript.
Procedural galaxy, turn-based, ~20hr campaigns.
## Architecture
Managers (autoloads) own systems. Entities (Resources) hold state.
Nodes are views only. Signals between managers, never direct calls.
Key managers: GameManager, CombatManager, DiplomacyManager,
EconomyManager, ExplorationManager, UIManager, AudioManager
## Conventions
- PascalCase classes, snake_case functions, UPPER_SNAKE constants
- Signals: past tense (fleet_moved, turn_ended)
- One class per file, tests mirror source structure
- Balance values in data/balance.json only — never hardcode
## Game Rules That Affect Code
- Resources are always integers
- Combat: strength × modifiers, rock-paper-scissors ship classes
- Reputation: -100 to 100, decays 1/turn toward 0
- Economy updates AFTER combat in turn order
## File Layout
scenes/, scripts/, data/, ui/, resources/, tests/
## Anti-Patterns
- No game state in nodes
- No physics engine for game logic
- No await in _ready()
- No direct manager-to-manager calls (use signals)
- No new autoloads without asking
Fifty lines. That's all it takes to go from "brilliant but clueless" to "brilliant and aligned with your project."
Tips From the Trenches
Start small, grow it. Don't try to write the perfect CLAUDE.md on day one. Start with architecture and conventions. Add to it every time the AI makes a mistake you don't want repeated.
Update it when things change. Refactored your scene tree? Changed your entity pattern? Update CLAUDE.md or the AI will fight your new architecture.
Use sub-files for big projects. Claude Code supports .claude/ directories. Put module-specific instructions in separate files: .claude/combat.md, .claude/ui.md, .claude/economy.md.
Include examples. When a convention is ambiguous, paste a real code snippet showing the correct pattern. One example is worth ten rules.
Review the AI's mistakes. When Claude does something wrong, ask yourself: "Could CLAUDE.md have prevented this?" If yes, add a rule. Your CLAUDE.md should be a living record of lessons learned.
The Bottom Line
Every minute you spend on CLAUDE.md saves ten minutes of correcting AI-generated code. For game projects — where architecture is complex, conventions are non-obvious, and game design rules affect every system — it's not optional. It's foundational.
Your AI agent is only as good as the context you give it. Give it great context.
This is part of a series on agentic coding for game developers. Next up: how to structure multi-agent workflows for game projects. Subscribe to the newsletter to get it first.
Building a game with AI? Join Agentic Game Devs — a community for game creators using AI agents.