AGENTS.md: Steering Codex with a Repo Contract

AGENTS.md is a markdown file at the root of your repository that Codex reads before it touches anything: a standing contract covering how to build, what conventions hold, and where the agent must not go. No schema, no special syntax, just instructions a model can follow. It is the highest-yield configuration the Codex CLI has, because one well-written file upgrades every session in the repo, interactive and scripted alike.

What AGENTS.md is

Think of it as a README whose audience is an agent. Humans skim docs and fill gaps with judgment; an agent fills gaps with guesses, and a guessed test command or an improvised convention is how unattended runs go sideways. The file is an open format used by Codex and other coding agents, so one contract serves every tool that reads it.

Codex looks for the file at the repo root. Two extensions matter once projects grow: nested AGENTS.md files in subdirectories apply to their subtree, with the closest file taking precedence, and a global file under ~/.codex carries your personal defaults across every project on the machine. Monorepos use the nesting; everyone else mostly needs the root file. OpenAI’s Codex docs (developers.openai.com/codex) describe the lookup, and the getting-started guide shows where it fits in initial setup.

What belongs in it

Four categories cover nearly everything worth writing down:

• Commands. The exact invocations for install, test, lint, and build, plus the expectation that tests run before any task is called done. Agents are good at running commands and bad at divining which of your five test scripts is canonical.
• Conventions. The decisions a reviewer would flag: strictness settings, error-handling patterns, naming, file size norms. Write the rule you actually enforce, not the one you wish you enforced.
• Boundaries. Generated directories, migrations, vendored code, secrets. “Never edit src/generated/” saves you from the diff that touches 4,000 lines of build output.
• Output contracts. For repos driven by codex exec: what format answers take, where reports land, what a verdict line looks like. This is what makes piped output parseable on the first try.

A useful test for every line: would the agent plausibly get this wrong without being told? If not, cut it. An AGENTS.md is a contract, and contracts get shorter as trust in defaults grows.

What to leave out

Secrets and credentials, first and always: the file is committed and read in full on every run. Long prose explains itself out of being read; a 600-line manifesto gets the same attention as your unread style guide. Stale commands are worse than none, because the agent will trustingly run them. And skip the aspirational rules nobody enforces in review; the agent following a rule humans ignore produces diffs that look wrong to everyone.

A complete example for an exec-driven repo

This is the shape we use for repositories where codex exec recipes run unattended, from cron and CI:

# AGENTS.md

## Project

Invoice-processing service. TypeScript, Node 22, pnpm.
Source in src/, tests in tests/, generated clients in src/generated/.

## Commands

- Install: pnpm install --frozen-lockfile
- Test: pnpm test
- Lint: pnpm lint
- Build: pnpm build

Run tests and lint before declaring any task complete.

## Conventions

- TypeScript strict mode; no `any` without a comment giving the reason.
- Errors: throw typed AppError subclasses, never bare strings.
- Keep files under 300 lines; split modules by domain concept.

## Boundaries

- Never edit src/generated/ or db/migrations/.
- Never commit or push; leave changes in the working tree.
- Do not add dependencies; propose them in your summary instead.
- .env files are secrets: read if needed, never print or copy them.

## Non-interactive runs

This repo is driven by codex exec from cron and CI.

- When asked for JSON, output only JSON, no surrounding prose.
- End review tasks with exactly one line: VERDICT: PASS or VERDICT: FAIL.
- Write reports to reports/, named YYYY-MM-DD-<topic>.md.

The last section is the part most repos miss. Interactive users correct a chatty answer in the next message; a pipeline cannot. Pinning output contracts in the repo, once, beats restating them in every prompt of every recipe, and it is the difference between jq parsing the result and jq failing at 6 a.m.

One adjacent file does a different job. ~/.codex/config.toml holds behavior settings, the sandbox level and approval policy, while AGENTS.md holds knowledge. Keep “what the agent may do” in config and “what the agent should know” in the contract; asking AGENTS.md to enforce sandbox rules produces instructions the CLI cannot actually guarantee, since markdown is advice and config is enforcement.

Treat it like code

The file decays the same way docs decay, so give it the same defenses: change it in PRs, review it when commands change, and prune it quarterly. When an unattended run misbehaves, fix the contract before you fix the prompt; prompts patch one run, AGENTS.md patches all of them. A repo that pins its commands, boundaries, and output formats turns Codex from a clever guest into a colleague who has read the onboarding doc.

Standing instructions matter most where nobody is watching the agent work. If your AGENTS.md exists because exec jobs run around the clock, the remaining question is what those jobs run on, and Codex Hosted vs running Codex yourself lays out that trade honestly. Codex Hosted runs the same official CLI against your repos’ same contracts, in a container signed in with your own account, behind one OpenAI-compatible endpoint.