Understand the AGENTS.md instruction chain

Understand the approach

Codex discovers instructions in a defined chain when it starts. At the global layer, it looks in the Codex home directory, normally .codex in your user home. It prefers a nonempty AGENTS.override.md over AGENTS.md there. At project scope, it walks from the project root toward the current working directory and selects at most one instruction file at each directory level.

Within a directory, the order is AGENTS.override.md, AGENTS.md, then configured fallback filenames. More specific files appear later in the combined instructions and can refine earlier guidance. An override in one directory does not mean that every parent instruction disappears: it replaces the ordinary file selected at that same directory. Keep specialized instructions close to the work they govern rather than changing the global layer for a single project.

This mechanism depends on the actual working directory and project root. A file sitting in a sibling folder is not automatically the governing source for your session. Instruction size is also bounded; the documented combined default limit is 32 KiB. When guidance looks wrong, inspect the selected path and override files, then restart in the intended directory. Do not try to solve discovery problems by repeatedly pasting conflicting instruction copies into chat.

Test the override and its absence

The fixture includes root AGENTS.md, ordinary docs guidance, a docs override and contradictory sibling guidance. At docs, the expected project chain retains the root preservation rule and selects the docs override’s short-heading rule. The ordinary docs file and sibling file are counterexamples: neither should be selected at that level.

Remove the override only in the disposable exercise and start a new docs session. The ordinary docs rule should now apply. Compare actual loaded paths, not just a fluent summary. The offline verifier checks these fixture files; it does not claim to have executed Codex discovery.

Resolve conflicts explicitly

If two instructions appear incompatible, name the files, scopes and concrete conflict. A local test command can refine a root command for a specialized service, but it should not erase unrelated requirements. Put the resolution in the smallest maintainable source when you are authorized to edit it. For a shared repository, preserve existing agreements and ask about a material unresolved conflict instead of silently choosing whichever sentence is easiest to follow.

Try it step by step

1. Draw the path from your scratch repository root to a nested docs folder, marking every applicable instruction file.
2. Predict which file is selected at a directory containing both AGENTS.md and AGENTS.override.md.
3. Start a fresh session at the root, then another in docs, and ask for the loaded source paths and applicable differences.
4. Compare the predictions with the evidence; correct the folder or file placement before editing any configuration defaults.

A useful starting example

Illustration · adapt before use.

codex --cd ./codex-lab --sandbox read-only "List the instruction files loaded for this directory and summarize their scope."
codex --cd ./codex-lab/docs --sandbox read-only "List the instruction sources and explain which docs-specific guidance applies."

Check your result

• The reported instruction paths belong to the expected root-to-working-directory chain.
• A same-directory override is distinguished from parent guidance, rather than described as deleting the entire hierarchy.
• The result is checked in fresh sessions, and no user-global instruction file is changed for the experiment.

Common mistakes

• Assuming every AGENTS.md anywhere in the repository loads into every chat.
• Confusing config.toml precedence with Markdown instruction discovery; they are related configuration mechanisms with different purposes.