How to Write AGENTS.md for Codex Without Bloated Instructions

If Codex repeatedly chooses the wrong package manager or test command, you should not have to restate the correction in every chat. Persistent repository behavior belongs in AGENTS.md.

The file can also become a liability. A giant handbook buries critical constraints, conflicts with service-specific exceptions and spends context on irrelevant history. Think of AGENTS.md as a compact constitution, not a wiki.

The exact AGENTS.md discovery order

At startup, Codex builds an instruction chain. At global scope it reads AGENTS.override.md when present; otherwise it reads AGENTS.md. Only the first non-empty file at that level is used.

Within a project, Codex walks from the root to the current working directory. In each directory it checks the override, the regular file and configured fallback names, selecting at most one. Root guidance arrives first and closer guidance later, so local rules can refine general rules.

• Global: personal defaults across repositories
• Root: repository-wide build, test and architecture rules
• Nested directory: service or package exceptions
• Override: an intentional replacement, not a second copy

What belongs in the file—and what does not

Include facts needed on almost every relevant task: package manager, verification commands, generated-file boundaries, public API rules and safe local actions.

Keep feature requirements, deadlines and one-off reproduction details in the task prompt. Put multi-file reusable procedures in a Skill. Frequently changing facts become stale instructions and should not live here.

A production-ready starting template

Concrete commands outperform “ensure quality.” State the trigger for each command. When you prohibit an action, give a safe path where one exists.

Repository-specific review rules can live under ## Code Review Rules in the closest applicable file. Focus on domain failures that CI cannot already catch.

# AGENTS.md

## Repository workflow
- Use pnpm; do not create npm lockfiles.
- Inspect the affected package before editing shared code.
- Preserve unrelated user changes.

## Verification
- UI change: pnpm test:ui && pnpm build
- Shared types: pnpm typecheck
- Report the exact blocker if a command cannot run.

## Boundaries
- Do not deploy or change production data without explicit approval.
- Local tests use disposable fixtures and may be rerun freely.

Split monorepo rules by directory

If the root file contains every frontend, payments and data-pipeline rule, every task receives every explanation. Keep only shared rules at the root and move service commands close to their code.

A root file can define pnpm and global type checks while services/payments/AGENTS.override.md defines payment tests and key-handling rules. The later, closer instruction provides the explicit exception.

Signal-to-noise matters before the 32 KiB limit

The documented combined default is 32 KiB. Once the limit is reached, later guidance may not be included. Splitting by directory can help, but staying under the cap does not make a file useful.

Remove historical essays, exhaustive style guides and formatting rules already enforced by CI. OpenAI warns that accumulated instructions can contradict one another and make skill selection worse on newer models.

A five-minute AGENTS.md audit

Ask Codex to summarize the instruction sources it loaded. If an expected nested override is absent, check the launch directory and filename.

Review for deletion, not only addition. Retire obsolete commands, scaffolding the current model no longer needs and duplicated CI rules.

• Do commands match the current repository?
• Do parent and child rules conflict?
• Did a one-off request leak into persistent guidance?
• Does each prohibition include a safe alternative?
• Should any rule move closer to its directory?

Frequently asked questions