Home / AGENTS.md for Godot 4

AGENTS.md for Godot 4

Point an AI agent at a Godot project and it will happily restructure your scene tree, chain get_parent() calls, hardcode keycodes and quietly "improve" your jump feel. In a 48-hour jam, that's how the build is broken at hour 40.

What AGENTS.md is

AGENTS.md is a plain Markdown file at the repo root that coding agents (Codex, Cursor, Windsurf, Aider, Zed, and Claude Code via an import in CLAUDE.md) read before working. For Godot, put it next to project.godot.

The rules that matter most for games

Scope is king. The agent implements only the current task and suggests cuts, never additions.
Always runnable. Every change must leave F5 working.
Signals up, calls down. This keeps scenes decoupled so the agent can't tangle them.
Feel numbers are @export, and every change lists old → new values, so you stay in control of game feel.
InputMap actions only, so gamepad works for free.

Free snippet: copy it

AGENTS.md (Godot 4)

# AGENTS.md (Godot 4)
Game: <<FILL title>>. Genre: <<FILL>>. Jam: <<FILL name, theme, deadline>>. Engine: Godot 4.x, GDScript (typed). Target: <<FILL web/desktop>>.

## Working rules
1. Scope is king. Implement only what's in the current task from TASKS.md. Suggest cuts, never additions.
2. Before coding, list the scenes/scripts you'll touch. Never restructure the scene tree without asking.
3. Every change must leave the game runnable (F5). If a change takes more than 30 minutes, split it.
4. Explain how to test in-editor in 1-3 steps after every change.

## Conventions
- Folders: `scenes/`, `scripts/`, `assets/{sprites,audio,fonts}/`, `autoload/`, `ui/`.
- Files are snake_case; class_name is PascalCase. One script per scene root.
- Static typing everywhere: `var speed: float = 200.0`, typed func signatures, `@export` for tunables.
- Signals up, calls down: children emit signals, parents call methods on children. No `get_parent().get_parent()`.
- Global state only in autoloads: `Game` (state machine, score), `Audio` (SFX/music bus), `Events` (signal bus).
- Input via InputMap actions (`move_left`, `jump`, `action`), never raw keycodes. Support keyboard and gamepad.
- Physics in `_physics_process`, visuals in `_process`. Use `delta`.
- State machines: an enum + match for small actors; node-based states only for the player when there are more than 4 states.
- Tunables (speed, jump, timers) are `@export` vars or live in a `Tuning` resource so they can be tweaked in the inspector.

## Don't
- Don't use `await get_tree().create_timer()` chains for gameplay logic; use a Timer node or state.
- Don't load in `_process`. Preload scenes with `preload()`.
- Don't add plugins/addons without asking.

## Web export
Use the Compatibility renderer for web. Keep total size under 40 MB. Test the exported build in the browser before the deadline, not after.

Want the whole drawer?

The Game Jam Agent Kit ($24) adds scoped Cursor rules for GDScript, player feel and juice, a Phaser/Three.js rule set, 10 prompts along the jam timeline, and GDD + playtest templates.

See the pack