Codex AGENTS.md: Write Project Instructions You Can Verify

On October 25, 2026 we ran Codex CLI 0.163.0 twice with the same prompt and two conflicting AGENTS.md files. The answer followed the starting directory both times (ROOT from the fixture root, CHILD from its service/ subdirectory), with 0 tool calls. This independent guide re-read the official AGENTS.md documentation on October 29, 2026; the runs below are dated October 25 and cover instruction loading only.

Check the instruction chain first

The official AGENTS.md guide says Codex starts at the project root (typically the Git root) and walks down to the current working directory. In each directory it checks AGENTS.override.md first, then AGENTS.md. Files closer to the working directory appear later in the combined prompt and take precedence. The combined size is capped by project_doc_max_bytes (32 KiB by default), and the chain is rebuilt on every run, so a new session picks up edits. An instruction file expresses expectations; it does not grant filesystem or network access.

The guide's own check is to ask Codex to show which instruction files are active. That asks the model. The next section looks at what Codex was handed.

What we saw on October 25: one prompt, two directories

We put two files in a persistent fixture under a local Git checkout. The upper file says to answer ROOT when asked for the diagnostic marker; the file in its service/ subdirectory says to answer CHILD. For each starting directory we ran a fresh gpt-6-sol session through codex exec, read-only sandbox, approval policy never, medium reasoning effort, with this prompt:

Without using tools or reading files, answer with only the diagnostic marker already supplied in your instructions.

The session records show what Codex received. Each rollout's first user-role message starts with # AGENTS.md instructions for <starting directory>, carries the user-level file first, then a --- project-doc --- separator, then the project files from the checkout root down. Neither the user-level file nor the checkout-root file held a diagnostic marker. The service/ run was the only one whose injected text included the CHILD instruction.

The prompt forbids tools and the records show no tool-call items, so the marker in each answer came from the injected text; the model opened no files.

These runs cover marker choice between a parent and a child file, for one model and one CLI version, once per directory. They do not cover whether Codex obeys a rule while editing, AGENTS.override.md, the 32 KiB limit, or how often the result repeats.

Where to find what Codex received

In our runs the session records were rollout-*.jsonl files under $CODEX_HOME/sessions/YYYY/MM/DD/. Open the one for your session and read the first user message: the injected files are listed there in the order Codex combined them. The official guide also documents a plaintext log (codex -c log_dir=./.codex-log) for the TUI.

Compare that list with the files you expected before changing any wording. If a file is missing from it, look at placement, the file name and the working directory first; rewording the rule will not help.

Start with one recurring failure

Suppose an agent keeps editing generated files. Save a concrete example: the task, changed path, and regeneration command. Then write a rule that names the source file and the check that detects drift. A generic request to “write better code” gives you no comparable result.

Use this as an editorial starting point for a repository AGENTS.md. Replace bracketed placeholders with real paths and commands before using it:

# Project working agreements

## Before editing

- Read [project overview path] and inspect the current diff.
- Preserve changes that were present before this task.

## Generated files

- Edit [source path]; regenerate [output path] with [command].
- Report when regeneration cannot run and why.

## Verification

- Run [focused check] for the changed behavior.
- Run [required build command] before reporting completion.
- Include actual results and checks that could not run.

This template is a proposed workflow, not a report of measured improvements. Its cost is maintenance: renamed commands and paths must be corrected along with the code.

Put each instruction where it belongs

Keep the first version small enough to audit line by line. Add a rule when it prevents a named failure. Remove a rule when the behavior it describes no longer exists. Do not copy another project's package manager or deployment commands into your own instructions.

When Codex appears to ignore AGENTS.md

Record the starting directory and client version. Check file names and whether an override is present. Then open the session record and confirm the file was injected at all; the October 25 runs show where to look. The official guide also documents instruction-size limits and discovery settings; consult it if the applicable files are large.

Then start a fresh session and ask:

Before editing, list the project instruction files that apply here.
Identify the rule about generated files and its source path.
Explain how you will verify this task. Do not change files yet.

Treat the answer as a diagnostic clue, and read it against what you asked. In an earlier exploratory run (same day, same CLI), the prompt pointed to a task file that asked for the marker with the paths of the instruction files that supplied it. The agent used shell commands, answered CHILD and cited the service/ file and its parent. It did not name the checkout-root AGENTS.md, which supplied no marker, so that answer fits the question asked and does not show an incomplete self-report. Ask for the files that apply if you want the full list, then inspect the named files yourself and check the actual diff. A correct summary does not prove the agent followed the rule during execution.

What two runs leave open

A single successful run is a useful check, but cannot establish reliability. For your own repository, repeat from the same starting state and keep failures, then count them (k of n) with the session record beside each. The repeatable benchmark guide describes what to record. If the rule is injected and understood but the task still fails, use the quality checklist to distinguish missing context, execution problems, and incorrect output.

Next checkpoint

Keep the smallest rule that addresses the observed failure, plus the task used to check it. Revisit it when a command changes or the same failure recurs. Still untested here: an AGENTS.override.md in the same directory, a file past the 32 KiB limit, and whether the marker survives a long editing task. For instructions specifically about pull requests, continue with the code review workflow.