Write an AGENTS.md That Makes Codex Work Verifiable

When Codex hands back a small task, the final message usually ends with some version of "tests pass". Whether you can trust that sentence depends on decisions you made before the task started: whether the repository told Codex which test command is the real one, whether the prompt asked for the commands and results by name, and whether you have a fixed routine for checking the diff afterwards. This guide covers both halves for the local Codex CLI and IDE extension. First, a compact AGENTS.md that Codex will actually load, with the discovery chain, override semantics and byte cap taken from OpenAI's documentation. Second, a four-part acceptance check you can repeat on every task.

What Codex does with AGENTS.md

The official AGENTS.md guide states that Codex reads AGENTS.md files before doing any work, and describes the design as layering global guidance with project-specific overrides so that each task starts with consistent expectations no matter which repository you open. Codex builds this instruction chain when it starts: once per run, and in the TUI (the interactive terminal interface) usually once per launched session. If you edit the file and the instructions look stale, the guide's advice is to restart Codex in the target directory, which matters later when you check whether a change loaded.

Discovery happens at two scopes.

Concatenation, not replacement

This is the detail that is easiest to get wrong. Codex does not pick the nearest file and discard the rest. It concatenates files from the root down, and files closer to your current directory override earlier guidance only because they appear later in the combined prompt. The root file is still in the prompt. A nested file gets the last word by position, not by deletion.

The agents.md format site, whose FAQ says "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything", describes the format as a general convention across the tools that read it. For Codex, follow the Codex documentation: the unit of discovery is the directory you launched Codex in, not the file being edited, and the root guidance stays in the chain. The clause about chat prompts overriding everything is the format site's statement; the Codex guide makes no equivalent claim, so I would not rely on it as documented Codex behavior.

The one true replacement happens inside a single directory. If AGENTS.override.md sits next to AGENTS.md, the sibling AGENTS.md is ignored. The guide's own sample tree annotates services/payments/AGENTS.md with "Ignored because an override exists". That is the mechanism for a personal or temporary override that should not touch the shared file.

The walk ends where you started

Codex stops searching once it reaches your current directory, and the guide advises placing overrides as close to specialized work as possible. The practical consequence is easy to miss: a nested services/payments/AGENTS.md is part of the chain only when you launch Codex from inside that directory or deeper. Launch from the repository root and only the root project file (plus your global file, if any) loads. If you want service-specific guidance to apply, start Codex in the service. The guide defines the end of the walk as Codex's current working directory and does not say how the IDE extension sets it; if you use the extension, confirm the chain with the CLI check in the section below rather than assuming.

The 32 KiB cap and the two knobs

The two official pages that describe this knob do not word it the same way. The AGENTS.md guide describes a combined limit: Codex stops adding files once the combined size reaches project_doc_max_bytes. The advanced configuration page, which puts it as Codex including "a limited amount of project guidance in the first turn of a session", governed by two knobs, words the same knob per file, as the amount read from each AGENTS.md file. This tutorial follows the guide, because it is the page that spells out the discovery walk and the troubleshooting steps, and its own label for the failure is "Instructions truncated". On the guide's reading, files are added root-down until the budget runs out, so the guidance that is truncated or left out when you exceed 32 KiB is the later, deeper and more specific guidance, which is usually the part you cared about most. The configuration reference lists project_doc_max_bytes with a description only and does not print the default; the 32 KiB figure comes from the AGENTS.md guide itself. The guide's example of adjusting both knobs in config.toml looks like this:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

With that configuration, Codex checks each directory in the order AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Filenames not on the list are ignored for instruction discovery. Note that 65536 is an example override value in the docs, not a default; neither the guide, the advanced configuration page nor the configuration reference names a different default.

Persistent instructions versus per-task acceptance criteria

The agents.md site, home of the format now stewarded by the Agentic AI Foundation under the Linux Foundation, draws the line cleanly: README files are for humans, and AGENTS.md carries the extra, sometimes detailed context that coding agents need, such as build steps, tests and conventions that would clutter a README.

Acceptance criteria are a different artifact, and OpenAI's own prompting guidance models the split. In its Codex "Fix a bug" workflow, the constraints live in the task prompt ("Do not change the API shape." and "Keep the fix minimal and add a regression test if feasible."), the user is told that repro steps and constraints "matter more than a high-level description", Codex "should re-run the repro steps after the fix", and the verification line reads: "After the fix, run lint + the smallest relevant test suite. Report the commands and results."

That last sentence is in the prompt, not in a configuration file. The distinction matters because the agents.md FAQ answers the question of whether agents run the tests you list with a yes, adding that the agent "will attempt to execute relevant programmatic checks and fix failures before finishing the task". "Attempt" is the operative word, and it is a claim about the format in general. Neither the AGENTS.md guide nor the prompting page makes an equivalent promise; the prompting page models asking explicitly in the task prompt. So treat a listed test command as necessary but not sufficient. It tells Codex which command is the real one. It does not guarantee the command ran. The per-task prompt asks; the acceptance check confirms.

For completeness, Codex has a third layer that is neither of these. Rules control which commands Codex can run outside the sandbox. They are command policy, not instructions, and they are out of scope here.

An illustrative starter AGENTS.md

The starter below is illustrative. I have not run it through Codex, and it describes a hypothetical TypeScript repository. It is modeled on the official example in the guide, which is only two lines under a "Repository expectations" heading (run npm run lint before opening a pull request; document public utilities in docs/ when you change behavior), and on the reporting pattern from the prompting page. Adapt every line to your repository. A wrong test command is worse than none, because any report built on it tells you nothing.

The test I apply to each line is whether it enables a specific acceptance step later.

# AGENTS.md (illustrative; adapt to your repository)

## Setup
- Package manager: pnpm. Install with `pnpm install --frozen-lockfile`.
- Do not change toolchain or dependency versions unless the task says so.

## Verification
- Unit tests: `pnpm test`. For a single file: `pnpm test path/to/file.test.ts`.
- Lint and types: `pnpm lint` and `pnpm typecheck`.
- Tests under `tests/integration/` need network access and `INTEGRATION=1`.
  If you did not run them, say so explicitly in your final message.

## Ownership
- Do not edit `migrations/` or lockfiles unless the task names them.
- Changes under `src/billing/` need a one-line justification in the final message.

## Reporting
- End every task with three lists: files changed, commands run with their
  results (pass/fail counts, not "passed"), and anything you could not verify.

The whole file is a small fraction of the 32 KiB cap, which is the point. On the guide's combined reading, a compact root file leaves room for nested files in the directories where the guidance differs, and it is short enough that you will notice when it is stale. If your repository is large enough that a single file wants to approach the cap, the guide's own advice is to raise project_doc_max_bytes or split the content across nested directories so the critical guidance stays intact.

Confirm the chain loaded

Before trusting a new or edited file, check that Codex is actually reading it. The guide documents the following steps. They are CLI commands; if you work in the IDE extension, run them from a terminal opened in the directory whose chain you want to confirm.

1. From the repository root, run codex --ask-for-approval never "Summarize the current instructions." Codex should echo guidance from the global and project files in precedence order. If the summary omits your file's guidance, treat the load as unconfirmed rather than failed, and use the log audit in step 4 to see which files were actually read.
2. If you rely on nested files, run codex --cd subdir --ask-for-approval never "Show which instruction files are active.", where subdir is a placeholder for the path of the nested directory whose chain you want to confirm. The guide's nested check passes that directory with --cd rather than launching from inside it. Remember that the walk ends at Codex's working directory, which is why the root-level check in step 1 does not show nested files.
3. If the instructions look stale, restart Codex in the target directory. Codex rebuilds the chain on every run and at the start of each TUI session, so there is no cache to clear.
4. To audit exactly which files loaded, opt into the plaintext TUI log with codex -c log_dir=./.codex-log and read ./.codex-log/codex-tui.log, or inspect the most recent session-*.jsonl file if you have session logging enabled.

Two failure modes are documented directly. If instructions are truncated, raise project_doc_max_bytes or split large files across nested directories. If wrong guidance appears, look for an AGENTS.override.md higher in the directory tree or under your Codex home, which is where the guide points you first.

The per-task acceptance check

The instruction file makes the following routine possible. The per-task half begins before the prompt, with a baseline. Record the state of the working tree as it is: run git status and keep the output, and if the tree already holds uncommitted edits of your own, note which files they touch. You do not need to commit, stash or clean anything up first. The point is to know afterwards which changes were already there, so that the post-task file list can be attributed to this task and your earlier edits are preserved. Parts 1 and 3 below are read against that record.

Here is an illustrative prompt for a small fix, written to the same pattern as the official "Fix a bug" workflow:

Fix: formatPrice returns "NaN" for zero amounts.
Repro: `pnpm test src/lib/price.test.ts` fails on the "zero amount" case.

Constraints:
- Do not change the function signature.
- Keep the fix minimal and add a regression test.

Verification: re-run the repro, then `pnpm lint` and the smallest relevant
test suite. Report the commands you ran and their results, and list anything
you could not run.

When Codex finishes, work through four parts in order. The order matters because each part narrows what the next one has to cover.

1. Scope: stated up front, held at the end

Compare the list of changed files against the scope in the prompt, the ownership lines in AGENTS.md, and the baseline you recorded. Set aside anything the baseline already listed: those are your edits, and they stay. If Codex also changed one of those files, separate its hunks from yours before judging them. Among the changes you can attribute to this task, every file outside the stated scope is a finding to investigate, not a change to undo on sight. It needs either a justification in the final message or a question back to Codex about why it changed, and only then a decision about whether to keep it. This is the cheapest check, and it catches a familiar surprise: a "minimal fix" that also refactored a neighbor. If you did not state a scope in the prompt, you cannot do this step, which is the argument for always stating one.

2. Commands and results: reported, then rerun

The final message must name the actual commands and their results. "Tests pass" is not a result; a line of the form "pnpm test src/lib/price.test.ts, 14 passed, 0 failed" is. Then rerun the named command yourself. It is a short step that turns Codex's claim into your observation.

The sandboxing documentation explains why the rerun is not optional. The sandbox applies to spawned commands, not only to built-in file operations: if the agent runs git, package managers or test runners, those commands inherit the same sandbox boundaries. The default low-friction local mode is workspace-write, where the agent can read files, edit within the workspace and run routine local commands inside that boundary, and under the on-request approval policy the agent works inside the sandbox and asks when it needs to go beyond it. Approvals decide when Codex pauses; the sandbox decides which files and network resources commands can access. The same page lists blocked network access among the approval requests that can arise at that boundary.

Put together: if a test needs a resource the sandbox does not grant, count it as run only when the transcript shows approved access or a completed run with its result. If the access was declined or blocked, the test did not run, or the final message is silent about the integration suite, that suite is unverified until you run it. This is why the starter tells Codex which tests need the network and asks it to say when it skipped them.

3. Diff reviewed, by hand or with /review

Read the diff. For anything beyond a few lines, Codex's own code review feature is a reasonable second reader. Typing /review in the CLI opens the review presets and starts a dedicated reviewer that reads the selected diff and reports prioritized, actionable findings without changing your working tree. Four scopes are documented: review against a base branch (Codex finds the merge base and reviews the branch diff), review uncommitted changes (staged, unstaged and untracked files), review a single commit, and custom review instructions that focus the review on criteria you provide. For a small task, the uncommitted scope is usually the right one, with one caveat: it covers staged, unstaged and untracked files, so if your baseline was not clean it also covers your own pre-existing edits. Read its findings against that baseline and discount the ones that land in hunks you made yourself. The custom scope is where the task's constraints (OpenAI's prompting guide gives "Do not change the API shape." as an example) can be handed to the reviewer verbatim.

Treat the reviewer's findings the way you treat the agent's summary: as claims to check against the diff, not as a verdict. It is Codex reading Codex's work.

4. What was not verified, written down

Finish with an explicit list of what you did not check: integration tests not run, a manual UI path not exercised, a migration not applied locally, a dependency change not audited. This list is the honest part of the pull request description, and it is the part that a "tests pass" summary erases. If Codex's final message already contains its own list of what it could not run, merge the two; if it does not, that absence is itself a finding, and the reporting line in AGENTS.md is there to make it rarer.

What the documentation does not promise

Everything above describes how Codex loads instructions and what you can check afterwards. None of it is a compliance guarantee. The official guide describes discovery and troubleshooting; it does not state how reliably Codex follows what it loaded, and its own troubleshooting section anticipates cases where wrong guidance appears or instructions are truncated. That is the reason the acceptance check exists rather than a hope that the file is enough.

The independent measurement cited here is about efficiency, not correctness. An arXiv preprint by Lulla, Mohsenimofidi, Galster, Zhang, Baltes and Treude (first version January 28, 2026, revised March 30, 2026) analyzed 10 repositories and 124 pull requests, running agents with and without an AGENTS.md file and measuring wall-clock execution time and token usage. The authors report that the presence of AGENTS.md "is associated with a lower median runtime (Δ 28.64%) and reduced output token consumption (Δ 16.58%), while maintaining a comparable task completion behavior". That is a preprint, an association, and a measure of time and tokens. It does not show that the file makes output more correct, and I would not cite it as if it did.

Two scope notes. The guide also documents a ## Code Review Rules section, placed in the AGENTS.md closest to the code the rules govern, with repository-wide checks at the root and service-specific checks in nested files, and it advises keeping formatting and lint checks in CI. That section is documented for Codex code review in GitHub; neither the guide nor the code review page says it changes the local /review behavior, so do not assume it does. And this article covers the local CLI and IDE extension, where the sandbox facts above apply. Codex cloud tasks were not researched here.

Where to start

Write the root file first and keep it under a screen. Put in the real test command, the real install command, the tests that cannot run in the sandbox, the paths Codex should not touch, and the reporting expectation. Run the "Summarize the current instructions" check once so you know it loaded. Then, on the next small task, record the state of the working tree, state the scope and the verification in the prompt, and run the four-part check when the work comes back: scope held, commands rerun, diff read, unverified list written. The file is a one-time cost; the check is the habit that makes the file worth having.

If you also use Claude Code, the equivalent configuration file is covered in my CLAUDE.md and AGENTS.md guide, which is about the Claude Code side and mentions AGENTS.md conceptually rather than covering Codex's discovery chain. Claude Code's own verification hooks are discussed in my Claude Code 2.1 review. Neither covers what this guide does, which is how Codex loads instructions and how to accept the work it returns.