AGENTS.md for Codex: a practical template that actually loads

Updated 2026-10-20

In short: Codex reads AGENTS.md before it does any work, but only the files on the path from your project root to the folder you launched from, at most one per folder, and only up to 32 KiB combined by default. Keep the root file short: exact commands, the conventions Codex can't guess, hard limits, and what "done" means. Put area-specific rules in nested files, procedures in skills, and check what loaded instead of assuming.

How Codex builds its instruction chain

From the Codex AGENTS.md guide: Codex builds the chain once per run (in the TUI, usually once per launched session), in this order:

1. Global. In your Codex home (~/.codex, or $CODEX_HOME if set) it reads AGENTS.override.md if it exists, otherwise AGENTS.md. Only the first non-empty file at this level counts.
2. Project. Starting at the project root (typically the Git root), it walks down to your current working directory. In each directory it checks AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames, and includes at most one file per directory. If it can't find a project root, it only checks the current directory.
3. Merge. Files are concatenated from the root down, joined with blank lines. Files closer to your current directory come later in the prompt, so they override earlier guidance.

Codex skips empty files and stops adding files once the combined size reaches project_doc_max_bytes (32 KiB by default). By default, a directory containing .git is the project root; project_root_markers in config.toml changes that, and an empty list makes the current directory the root (advanced config).

Three consequences catch people out:

• Launch directory matters. Codex stops searching once it reaches your current directory. Start it at the repo root and services/payments/AGENTS.md isn't in the chain.
• One file per folder. An AGENTS.override.md hides the AGENTS.md next to it, and a fallback name like TEAM_GUIDE.md is only read when neither exists in that folder.
• The budget fills from the top. The root file is read first, so a bloated root AGENTS.md leaves less room for the more specific files below it.

A starting template

Codex's best practices list what a good AGENTS.md covers: repo layout and important directories, how to run the project, build/test/lint commands, engineering conventions and PR expectations, constraints and do-not rules, and what done means and how to verify work. They also say "a short, accurate AGENTS.md is more useful than a long file full of vague rules." Here is a root file in that shape, about 40 lines. Replace every command and path with your own:

# AGENTS.md: acme-shop (pnpm monorepo, TypeScript, Node 22)

## Layout
- `apps/web/`: Next.js storefront
- `apps/api/`: HTTP API, handlers in `apps/api/src/handlers/`
- `packages/db/`: schema and migrations (the only place SQL lives)
- Generated code in `packages/db/generated/`: never edit by hand

## Commands
- Install: `pnpm install` (never npm or yarn)
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`
- One test file: `pnpm exec vitest run path/to/file.test.ts`
- All tests: `pnpm test` (needs `docker compose up -d db` first)

## Conventions that differ from the defaults
- Money is integer cents (`amountCents`), never floats
- Services return `{ ok: false, code, message }` instead of throwing
- New env vars go in `apps/api/src/env.ts` and `.env.example`

## Do not
- Add a production dependency without asking first
- Edit files under `packages/db/migrations/` that are already merged
- Delete, skip or loosen a test or assertion to get a pass

## Done means
- `pnpm typecheck` and the tests for every changed file pass, then `pnpm test`
- Your final message lists the commands you ran and their results.
  If you didn't run something, say so

## Where to look
- Payments work: read `services/payments/AGENTS.md` before editing there
- Architecture notes: `docs/architecture.md` (read only when needed)

## Code Review Rules
- Flag handlers that skip `requireUser()` before reading account data.
  Safe path: call it first and return 401 when it fails.

Why each part is there:

• Commands are the highest-value lines. The best practices list "not letting the agent see its work by not giving details on how to best run build and test commands" as a common mistake.
• "Done means" turns verification into something Codex can run. The guide's advice is to tell Codex what "good" looks like (tests, lint, type checks, confirming the behavior) in the prompt or in AGENTS.md.
• "Where to look" is routing guidance. The customization guide suggests adding it when Codex "finds the right files but reads too many documents", and the best practices suggest referencing task-specific markdown files instead of growing the main file.
• Code Review Rules is the section name the AGENTS.md guide gives for Codex code review in GitHub: put it in the AGENTS.md closest to the code it governs, explain the behavior to flag and the safe path, and leave formatting and lint checks to CI.

Don't start from a blank page if you don't have to. In the CLI, /init generates an AGENTS.md scaffold in the current directory (slash commands). The best practices call it a starting point that you should edit to match how your team actually builds, tests, reviews and ships.

Personal defaults go in ~/.codex/AGENTS.md

The customization guide splits the two levels cleanly: use the global file to shape how Codex works with you (review style, verbosity, defaults) and keep repo files focused on team and codebase rules. A personal file can be as small as this:

# ~/.codex/AGENTS.md
- Be brief. Show the diff summary, not the whole file
- Ask before running anything that touches the network or deletes files

Need to change it for a while? Create ~/.codex/AGENTS.override.md; Codex uses it instead of the base file until you remove it.

Nested files and overrides

For a folder with its own rules, add a short file there. The guide's own example is a payments service that uses a different test command:

# services/payments/AGENTS.override.md
## Payments service rules
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

Start Codex from that folder (codex --cd services/payments) and the chain is: your global file, the root AGENTS.md, then the payments file, which wins on conflicts because it comes last. Because this one is named AGENTS.override.md, an AGENTS.md in the same folder would be ignored. Use the override name only when you mean to replace that folder's regular file; otherwise call it AGENTS.md.

If you usually launch Codex at the repo root, nested files below it aren't loaded at startup. That's why the template has a "Where to look" line telling Codex to read services/payments/AGENTS.md before editing there. It's an instruction Codex reads like any other, not an automatic load, so keep the critical rules for that folder in the root file too, or launch from the folder.

Already have a team guide under another name? Add it as a fallback in ~/.codex/config.toml and restart Codex:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Filenames not on that list are ignored for instruction discovery. The second line raises the size cap; use it only after you've trimmed.

Stay inside the budget: move procedures into skills

To see how close you are, measure the files on the path to where you launch:

wc -c AGENTS.md services/payments/AGENTS.md

The default limit is 32 KiB (32,768 bytes). If you're near it, the docs give two fixes: raise project_doc_max_bytes or split instructions across nested directories. The better fix for most repos is to cut, because every line in AGENTS.md is read in every session.

Multi-step procedures (releases, migrations, review checklists) belong in skills. The skills docs describe progressive disclosure: Codex starts with each skill's name, description and file path, and loads the full SKILL.md only when it decides to use that skill. By default that initial list uses at most 2% of the model's context window (or 8,000 characters when the context window is unknown). Repo skills live in .agents/skills, which Codex scans in every directory from your working directory up to the repo root; personal skills live in $HOME/.agents/skills.

.agents/skills/release/SKILL.md
---
name: release
description: Cut a release. Bumps the version, updates CHANGELOG.md, tags and pushes. Use only when the user asks to release or publish a version.
---
1. Check `git status --porcelain` prints nothing. If not, stop and report.
2. Run `pnpm typecheck` and `pnpm test`. If anything fails, stop and report.
3. Move the "Unreleased" notes in CHANGELOG.md under the new version and commit.
4. Bump `version` in package.json, commit, then `git tag -a v<version> -m v<version>`.
5. Run `git push --follow-tags`.
6. Report the new version and every command you ran.

For anything with side effects, stop Codex from picking the skill on its own. Add agents/openai.yaml next to SKILL.md:

policy:
  allow_implicit_invocation: false

With that set, Codex won't invoke the skill implicitly from your prompt, but $release (or /skills) still runs it. Writing descriptions that trigger when they should is its own skill; see how to write a SKILL.md that actually triggers, which covers Codex too.

Check what actually loaded

The AGENTS.md guide gives these checks:

• codex --ask-for-approval never "Summarize the current instructions." from the repo root. Codex should echo guidance from your global and project files in precedence order.
• codex --cd services/payments --ask-for-approval never "Show which instruction files are active." to confirm a nested file is picked up.
• For an exact record, start Codex with codex -c log_dir=./.codex-log and read ./.codex-log/codex-tui.log, or inspect the latest session-*.jsonl if you enabled session logging. Asking the model is a quick sanity check; the log is what was actually sent.
• Edited AGENTS.md mid-session? Restart Codex in the target directory. It rebuilds the chain on every run, and there's no cache to clear.

Keep it current, and enforce what matters

The customization guide treats AGENTS.md as a feedback loop. Add a rule when Codex repeats a mistake or when you leave the same PR feedback twice. Put it in the closest directory where it applies. When you correct Codex, ask it to update AGENTS.md so future sessions inherit the fix. On GitHub you can comment @codex add this to AGENTS.md on a pull request. The best practices add: when Codex makes the same mistake twice, ask it for a retrospective and update the file.

AGENTS.md is guidance, not enforcement. The same guide recommends pairing it with pre-commit hooks, linters and type checkers that catch issues before you see them. If a rule must never be broken, make a tool check it, and keep the AGENTS.md line as the explanation.

Using the same file with Claude Code and Cursor

AGENTS.md is an open format that other agents read too, including Cursor. Claude Code is the odd one out. Per its memory docs, it reads AGENTS.md only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it, and it never reads AGENTS.override.md. So once you have a CLAUDE.md, make it a one-line @AGENTS.md import plus Claude-only notes, and remember that Codex overrides stay Codex-only. The details, and how nested files load in each tool, are in AGENTS.md vs CLAUDE.md: one source of truth. If you're moving from Claude Code or Cursor to Codex, the CLI's /import command migrates supported setup, projects and chats. Its import page lists instruction files among what it can bring over, and says it leaves your existing agent setup unchanged. Review the resulting AGENTS.md against this checklist before you trust it. The same trimming advice applies across tools; see why a long CLAUDE.md gets ignored.

Checklist

1. Run /init, or start from the template above.
2. Replace every command with one you've actually run in this repo.
3. Delete anything Codex can learn by reading the code, and every line you can't check.
4. Add "Done means" with exact commands and "report what you ran".
5. Move procedures into .agents/skills; make side-effect skills manual with allow_implicit_invocation: false.
6. Put folder-specific rules in nested AGENTS.md files, and route to them from the root if you launch at the root.
7. Check the size with wc -c and stay well under 32 KiB.
8. Restart Codex and run the "Summarize the current instructions" check.

FAQ

Sources

Official docs, checked 2026-10-20.

• Codex docs: Custom instructions with AGENTS.md
• Codex docs: Best practices
• Codex docs: Customization (AGENTS.md, skills, MCP, subagents)
• Codex docs: Advanced config (project instructions discovery, project root detection)
• Codex docs: Config reference
• Codex docs: Build skills
• Codex docs: CLI commands and slash commands (/init, /import, /skills, /review)
• Codex docs: Import from another agent
• Claude Code docs: How Claude remembers your project (when Claude Code reads AGENTS.md)
• Cursor docs: Rules (AGENTS.md support)
• agents.md: the open AGENTS.md format