AGENTS.md: the contract between Codex and your repo

Every Codex session starts with total amnesia. The model has never seen your repo, does not know the integration tests need the local stack running, and will happily invent a make target you deleted two years ago. AGENTS.md is the fix: a plain markdown file, committed to the repo, that Codex reads before it starts working. It is the one channel where your repo gets to speak first.

The mistake is treating it as documentation. It's a contract, and every clause in it gets executed on every single session. Documentation describes system behavior for humans to read later; this file tells the agent what to do right now. That framing changes what you write.

What Codex actually reads

The mechanics are worth knowing precisely. Codex picks up AGENTS.md from the repo root, and it also honors nested files: an AGENTS.md inside packages/api/ applies when the agent works under that directory, with the deeper file winning where they conflict. That gives monorepos a clean pattern: global truths at the root, service-specific commands next to the service, nothing duplicated.

Keep the root file short. It should fit on one screen. The agent ingests it every session, so a 400-line essay burns context and buries the load-bearing rules. My working test: if a line would not change what the agent types, it does not belong in the file.

The four sections that earn their keep

• Setup commands. How to install dependencies and boot the dev environment, exactly as typed. If setup lies, everything downstream lies with it.
• Test commands. The single most valuable section. An agent that can run your tests can verify its own work; one that cannot is guessing. Name the fast unit loop and the slow integration path, and say which to prefer.
• Conventions. The rules a reviewer would enforce anyway: strict types, no default exports, errors wrapped rather than swallowed, where fixtures live. Encode your taste once instead of re-litigating it on every diff.
• PR and commit rules. Message format, branch naming, what must be green before a change counts as finished. This is exactly where sloppy defaults leak through if you stay silent.

A root file can be a dozen lines and still do its job:

## Setup
pnpm install && pnpm db:up
## Tests
pnpm test (fast, run after every change)
pnpm test:e2e (slow, run before finishing)
## Conventions
Strict TypeScript. No default exports. Zod at every API boundary.

A standard, not a vendor file

The quiet win is that AGENTS.md has stopped being an OpenAI file. It is now the closest thing agent tooling has to a shared standard. A growing list of coding agents and editors read the same file, while the holdouts keep dialects of the same idea: Claude Code reads CLAUDE.md, Gemini CLI defaults to GEMINI.md, and Junie has its guidelines file. The formats differ; the craft is identical. I keep one canonical file and make the dialects reference it, because maintaining four diverging contracts is how agents end up with four diverging pictures of your repo.

An agent context file is a contract, not a wiki: every clause either changes what the agent does next or dilutes the clauses that would.

Write the first version in ten minutes (/init in the CLI will even draft it for you, as covered in the quickstart), then let real sessions harden it. Every time Codex does something a sentence would have prevented, add the sentence. Every quarter, delete the lines that no longer earn their place; a contract that only grows eventually stops being read. The craft generalizes to every tool in this space (I went deeper in writing agent context files), but the habit starts here. Before you blame the model, check the contract.