Field guide / 15 min
Make repository knowledge durable with AGENTS.md
Layer global preferences, team rules, and directory-specific instructions without a giant prompt.
Codex reads an instruction chain before work begins: global guidance, then project files from repository root toward the working directory. Closer guidance appears later and overrides broader guidance. AGENTS.override.md wins at a level, and the combined project guidance has a default size limit.
Verified terminal sequence
- ›
/init - $
codex --ask-for-approval never "Summarize the current instructions." - $
codex -C services/payments --ask-for-approval never "List the instruction sources you loaded."
Working principles
Put rules near their scope
Repository-wide commands belong at root; service-specific constraints belong closer to that service.
Encode recurring friction
Add guidance after repeated mistakes or review comments, not every preference you can imagine.
Verify discovery
Ask Codex to list loaded sources from the intended working directory instead of assuming precedence.
Field procedure
- 01
Generate a scaffold
Use /init as a starting point, then replace generic prose with actual repository commands and constraints.
- 02
Write the root contract
Document layout, build, tests, lint, architectural boundaries, and what done means.
- 03
Add narrow overrides
Use nested AGENTS.md or AGENTS.override.md only where behavior genuinely differs.
- 04
Keep the chain small
The default combined project guidance limit is 32 KiB. Link to deeper docs rather than copying an encyclopedia.
- 05
Test from multiple directories
Run the verification prompts from root and a specialized subtree to confirm effective sources.
PASS / FAIL
Acceptance checklist
- Commands are executable and current.
- Critical constraints live at the closest correct scope.
- Loaded instruction sources are verified.
- Secrets and volatile personal details are absent.
WATCH / REJECT
Failure patterns
- Treating AGENTS.md as complete security enforcement.
- Writing vague values instead of commands.
- Adding an override and forgetting it shadows the base file.