Agent handbook

405 words

This directory is the working guide for coding agents. Human documentation lives under docs/. The visual system is DESIGN.md. The product brief is PRODUCT.md. The build log is CONTEXT.md.

AGENTS.md at the repository root is the auto-loaded working card: the invariant imperatives, the definition of done, and pointers here. The invariant handbook holds their full constraints and reasoning. Keep that file short. Put anything an agent needs that is not an invariant here, so a person reading the technical docs is not walking through session instructions.

Read in this order

  1. AGENTS.md — invariants and definition of done.
  2. The ADR for the area you are about to touch — docs/adr/.
  3. This handbook, then the technical page for the mechanism.
  4. CONTEXT.md on demand, when you need the history of a bug or a decision that never became an ADR. It is long on purpose and is not loaded into context automatically.
I need to… Read
Not violate an invariant AGENTS.md · map to technical docs
Know how to start, verify, and stop Working
Use the toolchain Development
Drive the simulation Harness · Driving
Change the client shell Client · ADR-0011, ADR-0012
Author or change a cutscene Cinematics · ADR-0010
Add generated content or a task Extending
Write a test Testing
Match the written voice Style

Executable machinery — path-scoped rules, skills, hooks, subagents — lives in .claude/. Codex's adapters reuse those sources through native configuration and skill symlinks. Cursor's adapters reference those files rather than copying their contents. Claude Code and Cursor can load rule extracts by path. Codex reads the relevant shared extracts explicitly; Claude's paths: is not a Codex feature. The rule's reasoning stays in invariants.md and the technical docs.

What does not belong here

  • Product vision, architecture, and concept pages — those are docs/.
  • Game design — that is docs/design/.
  • A plan, a working review, or a tooling report — that is design/, which is outside the published tree because a plan describes what is not built yet.
  • A running diary of what landed — that is CONTEXT.md.
  • Vendor-specific Claude Code setup — that is CLAUDE.md.

If you are about to write a page that a human contributor should also read, it belongs under docs/guides/ or docs/concepts/, and this handbook should link to it.