AGENTS.md is the repository's durable contract: instructions Codex reads before starting work and builds a chain from once per run or session. Unlike a one-off prompt, it is a reviewed source of truth living in the repository under version control. Global guidance is in $CODEX_HOME, while the project chain is built from the repository root to the current working directory - that is, the more general is set higher, the more specific closer to the code.

The order of building the chain matters, because it determines what wins. In each directory, AGENTS.override.md is looked for first, then AGENTS.md, then names from project_doc_fallback_filenames. No more than one non-empty file is taken per directory. Instructions closer to the current directory appear later in the chain and therefore override the general ones. This is the same precedence logic as in config: the specific overrides the general, not the other way around.

A good AGENTS.md is a project contract, not a retelling of the structure. It helps to see a meaningful example once. Below are the repository map, the required checks and the change policy: where the code and tests are, which commands to run after edits, what not to do without approval. It is exactly what cannot be reliably inferred from the code - verification commands, boundaries, the definition of done - that is worth writing, and there is no need to repeat the obvious from package.json.

The point of AGENTS.md is to name what the agent will not infer itself. A repository map saves it exploration: where the application code lives, where the integration tests are. Required checks set the signal: run lint after TypeScript edits, run the affected tests for behavior changes. A change policy sets boundaries: do not add production dependencies without approval, preserve public API compatibility unless the task explicitly requires otherwise. This is the contract by which the agent acts by default.

AGENTS.md is worth keeping short and checkable rather than growing into an encyclopedia. Long instructions take up context and lose salience - the agent follows vague verbosity worse than a short clear list. General facts stay in the root file, while requirements specific to a subdirectory are moved into its own AGENTS.md, which is picked up right there. Nested overrides are a way to keep an instruction next to the code it relates to rather than dumping everything into the root.