Codex AGENTS.md: Write Project Instructions You Can Verify

AGENTS.md and AGENTS.override.md can change which project instructions Codex receives. Before adding another rule, check which file applies. This independent guide was checked against official documentation on September 20, 2026.

Check the instruction chain first

The official AGENTS.md guide describes global guidance followed by project files from the root toward the starting working directory. Within a directory, AGENTS.override.md takes precedence over AGENTS.md. Start a fresh session after changing instructions. An instruction file expresses expectations; it does not grant filesystem or network access.

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. 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. Inspect the named files yourself, then check the actual diff. A correct summary does not prove the agent followed the rule during execution.

Test the rule with a small controlled task

Save the initial commit and prepare an isolated copy with no unrelated work. Use the same bounded task before and after the instruction change. Record three outcomes: whether the generated file was edited directly, whether regeneration ran, and whether the resulting diff was correct.

A single successful run is a useful check, but cannot establish reliability. Repeat from the same starting state and keep failures. The repeatable benchmark guide describes what to record. If the rule is 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. For instructions specifically about pull requests, continue with the code review workflow.