CLAUDE.md for Godot 4: a Template Under 200 Lines

Updated 2026-10-15 · Tested with Godot 4.3 and 4.7.2

In short: keep CLAUDE.md under ~200 lines. Include the engine version, a ban on Godot 3 and Python, typing rules, the 3 → 4 table and the verify commands. Move detailed topic rules into .claude/rules/*.md with paths: frontmatter so they load only when needed.

Where it goes and how it loads

Put it at the project root (./CLAUDE.md or ./.claude/CLAUDE.md). Claude Code loads it at session start and re-reads it after /compact. Run /context to confirm it is listed under Memory files.

A skeleton

# CLAUDE.md - Godot 4 project
## Core
- Godot 4.x (see project.godot config/features). GDScript 2.0 only.
- Never Python syntax, never Godot 3 APIs. Unsure an API exists? Say so; check docs.
- Type everything: var hp: int = 3; func hit(d: int) -> void:
- await not yield; @export/@onready/@tool; sig.connect(f) / sig.emit()
## Godot 3 -> 4 (never write the left side)
| yield(x, "s") | await x.s |
| KinematicBody2D | CharacterBody2D (velocity + move_and_slide()) |
| instance() | instantiate() |
...
## Architecture
- Call down, signal up. No get_parent() chains. %UniqueName for refs.
- Autoloads only for EventBus/GameState/Save. Ask before adding one.
## Workflow
- Read PLAN.md first. One feature per session. Small steps.
- After each step: godot --headless --path . --check-only --script res://file.gd
- Then: godot --headless --path . --quit-after 30 (catches autoload errors)
- Never claim success without running checks.

Move detail into path-scoped rules

# .claude/rules/testing.md
---
paths:
  - "tests/**/*.gd"
---
- GUT: extends GutTest ... run: godot --headless -d --path . -s addons/gut/gut_cmdln.gd -gdir=res://tests -gexit

Path-scoped rules load when Claude reads or edits a matching file, so testing rules don't cost context while you work on UI. Note that @imports help with organisation but don't save context, because imported files load at launch.

CLAUDE.md vs AGENTS.md

By default, Claude Code reads CLAUDE.md instead of AGENTS.md when both exist. If your team keeps AGENTS.md as the shared source, put @AGENTS.md at the top of CLAUDE.md and add only Claude-specific notes below it.

Common failure modes

• Too long: instructions buried in a 600-line file get skipped.
• Vague: "write clean Godot code" changes nothing. "Use @onready var n: Label = %Score" does.
• Contradictions between CLAUDE.md, nested CLAUDE.md files and rules files mean Claude may pick either one.
• Enforcement: CLAUDE.md is guidance. For hard guarantees, use hooks. For example, a PostToolUse hook can run godot --check-only on edited .gd files.