AGENTS.md for Codex: Project Instructions That Actually Work

AGENTS.md is the repository's durable instruction file for coding agents. Codex reads it before starting work, giving every task the same map of the codebase, commands, constraints, and verification expectations without making you repeat them in each prompt.

Think of it as an agent-facing companion to README.md. The README helps a person understand and use the project; AGENTS.md tells an agent how to change it safely. It is plain Markdown, versioned with the code, reviewable in pull requests, and increasingly portable across coding tools.

What belongs in the file

An effective root AGENTS.md answers four questions:

1. Where is the relevant code? Name important directories and architectural boundaries.
2. How do I work here? Give setup, generation, formatting, and test commands that actually run.
3. What must remain true? State compatibility rules, ownership boundaries, and dangerous operations to avoid.
4. How do I prove a change is done? Map change types to focused and broader checks.

# Repository guide
 
## Map
- `apps/web/` is the Next.js application.
- `packages/api/` owns public request and response schemas.
- Generated clients live in `packages/sdk/generated/`; never edit them by hand.
 
## Working agreements
- Preserve the public API unless the task explicitly authorizes a breaking change.
- Reuse existing components from `apps/web/src/components/ui`.
- Add dependencies only when the standard library and current packages cannot do the job.
 
## Verification
- Web change: `npm run test:web` and `npm run lint`.
- API schema change: `npm run generate && npm run test:api`.
- Before finishing, review `git diff` for generated or unrelated files.

Notice what is missing: a manifesto, generic advice to write clean code, and a copy of every CI job. High-signal instructions are concrete enough to change what the agent does.

How Codex discovers instructions

Codex builds an instruction chain once at the start of a run:

1. At global scope, it checks the Codex home directory for AGENTS.override.md, then AGENTS.md, using the first non-empty file.
2. At project scope, it walks from the repository root toward the current working directory.
3. In each directory, it selects at most one file: AGENTS.override.md, then AGENTS.md, then any configured fallback filename.
4. It concatenates the selected files from broadest to most specific. Guidance closer to the current directory appears later and wins when rules conflict.

~/.codex/AGENTS.md                 personal defaults
repo/AGENTS.md                    project-wide commands and rules
repo/services/AGENTS.md           service conventions
repo/services/payments/
  AGENTS.override.md              payments-only override (closest wins)

If Codex starts in repo/services/payments, it can receive all four layers. If it starts at the repository root, it does not walk down into services/payments looking for instructions that do not govern the current directory.

Root file versus nested file

Keep the root authoritative for things every contributor shares: repository map, package manager, global checks, safety rules, and pull-request expectations. Add a nested file only when a subtree is operationally different — a mobile app uses another test runner, an infrastructure directory forbids applying changes, or a generated SDK has its own workflow.

Nested instructions should describe the difference, not repeat the root. Duplication creates drift and spends context on text Codex already has.

Use AGENTS.override.md for a deliberate replacement in that directory. It is also useful as a temporary global override, but an override is easy to forget; remove it when the exceptional workflow ends.

Write rules an agent can execute

Weak instructions describe taste:

- Follow best practices.
- Test thoroughly.
- Keep changes clean.

Strong instructions name an action and a boundary:

- Parse API payloads with the existing Zod schemas in `src/contracts/`; do not add parallel validation types.
- For changes under `src/billing/`, run `npm test -- billing` before the full suite.
- Do not edit files under `src/generated/`; run `npm run generate` from the schema source.

The second set affects search paths, implementation decisions, and verification. It also gives reviewers something objective to enforce.

Keep task requirements out

AGENTS.md is not a substitute for a good prompt. “Add an export button without changing the mobile layout” belongs to one task. “All new icon-only controls require an accessible name” is a durable engineering rule and may belong in the repository file.

Likewise, a multi-step release or incident workflow belongs in a skill, where it can carry detailed procedure and supporting files. Operational settings such as approval policy and MCP configuration belong in .codex/config.toml, not Markdown instructions.

Verify what Codex loaded

After adding or moving instruction files, start a fresh run from the directory where work will happen and ask Codex to summarize the active instruction sources, build command, test command, and most important do-not rule. A fresh run matters because discovery happens when the session starts.

If guidance is missing, check the working directory, repository root detection, empty files, a closer AGENTS.override.md, custom fallback names, and the combined instruction-size limit. If behavior is wrong, inspect for a specific contradiction before adding more prose.

The best AGENTS.md is not comprehensive. It is current, scoped, and operational: the smallest document that lets a new agent enter the repository and do verifiable work without relearning the same lessons.

Official reference: Custom instructions with AGENTS.md.