AGENTS.md: an example, and how it differs from CLAUDE.md.

Guides

AGENTS.md is an open, plain Markdown convention for agent instructions. Codex reads it, as do several other coding agents. Claude Code reads CLAUDE.md instead. The content you want in each is almost the same; the file name and a few engine-specific rules are what differ.

Which engine reads what

  • Codex reads ~/.codex/AGENTS.md for your personal rules, then AGENTS.md files from the repository root down to the folder it is working in, joined in that order. It caps the combined project size (32 KiB by default), so a long file can be cut off.
  • Claude Code reads ~/.claude/CLAUDE.md and project CLAUDE.md files. A CLAUDE.md can import another file with an @path line, which is the usual way to point it at an AGENTS.md.

Check your engine version's documentation for the exact search order; it has changed between releases.

An AGENTS.md example

Short, specific and checkable. The agent should be able to act on every line.

# AGENTS.md

## Setup
- Install: npm ci
- Verify: npm run verify (typecheck, lint, unit tests)

## Conventions
- TypeScript strict mode; no default exports.
- Tests sit beside the code as *.test.ts.
- Commit headings are short and lowercase; the body lists outcomes.

## Boundaries
- Do not edit migrations/ after they are merged; add a new migration.
- Ask before deleting files outside src/ or changing CI config.

## Pointers
- docs/architecture.md for module boundaries.
- docs/release.md only when cutting a release.

Where the two files should differ

Most rules are engine-neutral: style, verification, boundaries. Some are not. Claude Code has an Agent tool for subagents and an approval prompt that a hook can trigger with ask; Codex has neither, so a hook can only deny. A rule that says "use the approval prompt" is wrong for Codex, and a rule that says "leave the prepared change for the owner" is too weak for Claude. Write those few rules twice, one per engine, and share the rest.

Three ways to keep them in step

  • Import. Make AGENTS.md the source and put @AGENTS.md in CLAUDE.md. Simple; no per-engine rules.
  • Symlink. One file, two names. Simple; same limitation, and symlinks are awkward on Windows.
  • Generate both. Keep rules in one source with per-engine variants and render each file. More setup, and the only option that handles the differences above. This guide walks through it.

Whichever you pick, the size budget applies to each engine separately: about 3,500 estimated tokens across the personal and project files it loads.

Check your own files

Paste your CLAUDE.md or AGENTS.md into the free footprint scorer, or get the free sample and run rig doctor --lite locally. The hosted doctor check is A$0.50 a run and scores the whole setup, hooks included. The kit (A$10 once) has the rule source, generator, hooks and protocols these guides describe.

More guides