AGENTS.md: Operating Instructions for Codex

Codex starts every task with no memory of your repo. It does not know that you use pnpm, that the integration tests need a running Postgres, or that one module is a legacy minefield nobody is allowed to refactor. AGENTS.md is how you hand that knowledge over once and have it load automatically, every run, before you type a word.

If you have written a CLAUDE.md, the instinct is identical — a plain-text briefing the agent reads up front. The difference is the name and who reads it. AGENTS.md is not a Codex-only file. It is an open standard that more than two dozen coding tools agree to look for, which is exactly why it is worth learning as its own skill rather than as "the Codex version of CLAUDE.md."

What AGENTS.md actually is

The official site describes AGENTS.md as "a simple, open format for guiding coding agents" — in their words, "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." The split is deliberate. Your README is for the humans who clone the repo: what the project is, how to get started, how to contribute. AGENTS.md is for the agent: the build steps, the test commands, the conventions and gotchas that would clutter a README but that an agent needs in order to act correctly.

It is just standard Markdown. There is no schema, no required front-matter, no mandated section names — the agent simply parses the prose you write. That freedom is a trap if you treat the file as a dumping ground, and a superpower if you treat it as a tight, high-signal briefing.

What belongs inside

Because the format imposes no sections, the discipline is yours. The goal is the same as a great onboarding doc for a new engineer: the things they cannot guess by reading the code. The official guidance lists the kinds of content that earn their place — build, test, and lint commands; how to run the project; repository layout and the directories that matter; engineering conventions and PR expectations; constraints and prohibited practices; and the completion criteria that tell the agent when a task is genuinely done and verified.

What does not belong is everything Codex can already infer. It can read your code, so a paragraph restating what each folder obviously contains is wasted space. It knows standard language conventions, so "write clean, readable code" tells it nothing actionable. The test the pros use is blunt: for every line, ask whether removing it would cause the agent to make a mistake. If not, cut it. The official best-practices doc puts the philosophy plainly — "a short, accurate AGENTS.md is more useful than a long file full of vague rules."

Nesting and precedence: the nearest file wins

The single most important mechanic is how Codex finds and combines AGENTS.md files. It does not read just one. According to the official Codex guide, it builds an instruction chain in a fixed order.

First it checks your Codex home (~/.codex) for global, machine-wide defaults — AGENTS.override.md first, then AGENTS.md. Then, starting from your project root (usually the Git root), it walks down the directory path toward your current working directory, and in each directory along the way it checks for an AGENTS.md (again preferring an AGENTS.override.md if present). It includes at most one file per directory.

Then it concatenates. In the guide's own words, Codex "concatenates files from the root down, joining them with blank lines," and "files closer to your current directory override earlier guidance because they appear later in the combined prompt." Nothing is thrown away — a root file and a subdirectory file are both in context. But because language models weight later text more heavily, the deepest, most specific file naturally wins any conflict. That is the whole game: the nearest file takes precedence.

Patterns from real repositories

A few shapes show up again and again in repos that ship AGENTS.md. The lean root + nested specifics pattern keeps the top-level file broadly true (commands, layout, the handful of universal rules) and pushes package-specific guidance into per-directory files — ideal for monorepos, where the nearest-wins rule lets each service ship tailored instructions. The router pattern keeps the main file short and points to deeper task-specific Markdown for the rare deep dives, so the always-loaded file stays small. And the constraints-forward pattern leads with the prohibitions and the definition of done, because those are the lines that most change agent behavior.

One practical guardrail: Codex caps how much of an AGENTS.md it ingests. The verified current default is 32768 bytes — 32 KiB — set by project_doc_max_bytes [V]. Codex skips empty files and stops adding files once the combined size of the chain reaches that limit, so a fat root file can starve the nested ones below it. Raise the cap (project_doc_max_bytes = 65536 doubles it to 64 KiB) or, better, split instructions across nested directories. In practice, splitting is the better instinct — a file large enough to hit the cap is almost always too long to be followed well anyway.

Mixed-agent repos: AGENTS.md and CLAUDE.md side by side

Plenty of teams run more than one agent. Codex reads AGENTS.md; Claude Code reads CLAUDE.md. In a repo where both are used, you have two honest options. The first is to keep both files and let each be small, with the shared facts duplicated — fine for a short briefing, annoying to keep in sync as it grows. The second, which scales better, is to pick one file as the source of truth and have the other point at it: keep the substance in AGENTS.md and make CLAUDE.md a thin pointer (or vice versa) so there is one place to edit. Either way, the principle holds across both standards — short, specific, and organized beats long and vague, because both files are advice the model reads and tries to follow, not configuration it is forced to obey.

Discovery without Git: project_root_markers

The chain has to start somewhere, and "somewhere" is the project root. By default Codex finds it by walking up from your current directory until it hits a folder it recognizes as the root — and the only marker it looks for out of the box is .git [V]. The official config reference is explicit: "By default, Codex treats a directory containing .git as the project root." That is perfect for a normal clone and useless for the cases where there is no .git at all — a vendored source drop, a worktree extracted into a plain folder, a Python project you have not initialized yet. With no marker found, Codex falls back to checking only the current directory, so your nice repo-root AGENTS.md never enters the chain.

The fix is one setting in ~/.codex/config.toml. project_root_markers is the ordered list of filenames that mark a root, and you override it to match whatever your non-Git repo actually contains [V]. For a Python tree, point it at the files that always sit at the top:

project_root_markers = ["pyproject.toml", "setup.cfg"]

Now Codex walks up until it sees a pyproject.toml (or setup.cfg) and treats that directory as the root — the AGENTS.md chain assembles exactly as it would in a Git repo. Two related knobs round out the discovery model. Setting project_root_markers = [] does the opposite: it skips the parent walk entirely and pins the root to your current working directory [V]. And project_doc_fallback_filenames lets Codex accept instruction files under names other than AGENTS.md — in each directory it checks AGENTS.override.md, then AGENTS.md, then your fallbacks in order, so a repo that standardized on a house name keeps working [V]:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

Steering code review with a ## Review guidelines section

AGENTS.md does more than brief Codex on how to write code — a section named exactly ## Review guidelines changes how Codex reviews it. When Codex reviews a pull request (on GitHub, or when you ask @codex review), it searches the repo for AGENTS.md files and follows any Review guidelines it finds [V]. This is the lever for tuning what the reviewer cares about and, crucially, how loudly it complains.

The mechanism runs on severity. Codex classifies findings by priority and, by default, flags only P0 and P1 issues so review comments stay focused on high-priority risks rather than drowning the PR in nits [V]. Your Review guidelines both add domain-specific checks and let you re-rank severity — promote a class of problem you care about into P0/P1 so it actually surfaces, or define what counts as critical in your codebase. A minimal section looks like this:

## Review guidelines
 
- Don't log PII.
- Verify that authentication middleware wraps every route.
- Flag typos and grammar in user-facing strings as P0.
- Flag missing docs on exported functions as P1.

The nearest-wins rule carries straight over to review. Codex applies the guidance from the closest AGENTS.md to each changed file [V], so a stricter services/payments/AGENTS.md can demand extra scrutiny on money-handling code while the rest of the repo runs on the lighter root rules. Put broad review policy at the root and per-package severity bumps where the risk actually lives.