How to write AGENTS.md for Codex: a 25-line file for a product repository

What does Codex do with an AGENTS.md file?

OpenAI's Codex documentation opens its AGENTS.md page with one plain sentence: "Codex reads AGENTS.md files before doing any work." The file is added to the instructions at the start of every run, so whatever you put in it shapes every task without you retyping it. The format is not Codex-only: the AGENTS.md project site describes it as an open format "used by over 60k open-source projects" and lists Codex among a long set of agents that read it. That count covers open-source repositories in general, not product teams using Codex, so it says nothing about how well any one file works. What it does show is that the file you write here is not locked to one vendor.

The Codex best practices page lists what a good file covers: repo layout and important directories, how to run the project, build, test and lint commands, engineering conventions and PR expectations, constraints and do-not rules, and what done means and how to verify work. That list is the right checklist. The harder part is deciding what to leave out, and that is where most files go wrong.

What does a 25-line AGENTS.md for a product repository look like?

Here is a filled example for a B2B invoicing product: a monorepo with a Next.js customer app, a REST API, a Prisma database package and a shared UI package. Every line is something Codex cannot reliably work out by reading the code, or something that goes wrong when it guesses.

# AGENTS.md

## What this repo is
B2B invoicing app for finance teams. Specs for each feature live in docs/specs/.
apps/web: Next.js customer app. apps/api: REST API. packages/db: Prisma schema
and migrations. packages/ui: shared components used by every screen.

## Commands
- Install: pnpm install
- Run locally: pnpm dev (web on port 3000, api on port 4000)
- Test one package: pnpm test --filter api   (or web, ui, db)
- Before you say a task is done: pnpm lint && pnpm typecheck && pnpm test

## Rules that always apply
- Money is integer cents everywhere. Never use floats for amounts.
- Every new API route gets a test in apps/api/test/ in the same change.
- Copy the pattern in the nearest similar file before inventing a new one.

## Stop and ask before you
- Change anything in packages/db/ (schema or migrations)
- Add a production dependency
- Edit packages/ui/ when the task does not name it
- Touch billing, auth or permissions code

## Definition of done
- Lint, typecheck and tests pass, with the command output in your final message
- Your final message lists every changed file with one line on why
- Work on a branch and open a draft pull request. Never merge.

Four choices in that file are deliberate. The commands section names the filtered test command, because a full test run on a monorepo is slow enough that an agent without the filter will either wait or skip it. The rules section has three lines, each one a mistake that is expensive and easy to make: float money, an untested route, a new pattern where an old one existed. The stop list names paths rather than describing risk in general, because "be careful with shared code" gives Codex nothing to match against, while "packages/ui/" does. And the definition of done asks for evidence in the final message, which turns your review from rereading the work into reading a report you can check.

Notice what is missing. There is no tour of every folder, no style guide, no description of the architecture. Codex can read the code. The file carries only what the code does not say.

Where does Codex read AGENTS.md from, and how do nested files combine?

Codex builds an instruction chain when it starts, and the AGENTS.md page in the Codex docs spells out the order, as documented in October 2026. First it reads a global file from your Codex home directory (~/.codex unless you set CODEX_HOME). Then, starting at the project root, usually the Git root, it walks down to your current working directory and checks each folder on the way. Files are joined from the root down, so guidance closer to where you are working appears later and wins on a conflict.

Location	What Codex reads there	Use it for
~/.codex/AGENTS.md	Your personal file, or AGENTS.override.md if one exists	How you like to work, on every repository
Repository root	AGENTS.override.md, else AGENTS.md, else a fallback name	The shared contract everyone on the repo gets
Each folder between root and where you started Codex	The same order, at most one file per folder	Rules that only hold inside that package or service

Three details from that page change how you write the file. Codex includes at most one file per directory, so an AGENTS.override.md hides the AGENTS.md next to it entirely rather than adding to it. Empty files are skipped. And Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default, so a bloated root file can push a nested file out of the chain.

The detail people miss is the direction of the walk. The chain runs from the root down to the directory you launched Codex in, and stops there. If you start Codex at the repository root, an apps/api/AGENTS.md is not in the chain built at startup. Rules that must hold no matter where Codex starts belong in the root file. Package-level files earn their place when people routinely start Codex inside that package, for example with codex --cd apps/api.

How do you confirm Codex actually loaded the file?

Ask it. The Codex docs give the check for the CLI: run codex --ask-for-approval never "Summarize the current instructions." from the repository root, and Codex should echo your guidance in precedence order. For a nested folder, codex --cd apps/api --ask-for-approval never "Show which instruction files are active." confirms which files are in play. In the ChatGPT desktop app, start a new Codex chat in the project and send the same question.

A summary proves the file was read. It does not prove the rule will be applied, so add a probe: ask a question only your file can answer. With the example above, "What do you do before adding a production dependency?" should come back as "stop and ask", and "How are amounts stored?" should come back as integer cents. If either answer is vague, the line is either missing from the chain or written too loosely to stick.

When the answer is wrong, the docs list the usual causes: you are not in the folder you think you are, the file is empty, an AGENTS.override.md higher up or in your Codex home is winning, or the combined files hit the size cap and were truncated. Codex rebuilds the chain on every run and at the start of each session, so there is no cache to clear. Start a new session after editing the file.

Should you start with /init or write the file by hand?

Start with /init, then cut. The slash command reference documents /init as generating an AGENTS.md scaffold for the current project, and the best practices page is direct about what to do next: "It's a great starting point, but you should edit the result to match how your team actually builds, tests, reviews, and ships code."

A generated file describes what is in the repository. Your job is to add what is not: which test command is the real one, which folder is dangerous, what done means on this team. In practice the edit is mostly deletion. Remove every line that describes a folder Codex can open for itself, then add the stop list and the definition of done, which no scaffold can infer.

Can the same file steer Codex code review on GitHub?

Yes. When Codex reviews pull requests on GitHub, it searches the repository for AGENTS.md files and follows a section headed ## Code Review Rules. The GitHub review page recommends starting with two or three concise rules that describe the behaviour to flag and the safe path, and keeping formatting and lint checks in CI. For the invoicing repo, one rule earns its place:

## Code Review Rules
- Flag any change under packages/ui/ or packages/db/ that the pull request
  description does not list. Safe path: list it and say why, or move the change
  into the app that needs it.

The same page adds the limit worth remembering: "Code review rules guide Codex; they don't replace tests, branch protections, or required approvals." The guide to reviewing Codex pull requests shows that rule catching a real out-of-scope change.

Which three habits make an AGENTS.md worse?

The first is writing rules that are only sometimes true. "Use the new billing client" is right this sprint and wrong next quarter, and a file full of conditional rules teaches Codex that the file is negotiable. A rule that only applies to one kind of task belongs in that task's prompt or in a Codex skill.

The second is describing what the code already says. A paragraph on the folder structure goes stale the week someone renames a folder, and then the file is confidently wrong. Point at the spec folder and let Codex read.

The third is vague virtue: "write clean, maintainable code", "be careful", "follow best practices". OpenAI's guidance names the cost directly: "A short, accurate AGENTS.md is more useful than a long file full of vague rules." A vague rule gives Codex nothing to check its own work against, and it spends space that a specific rule could have used.

What is the monthly deletion habit?

Once a month, open the file and ask of each line: has Codex needed this in the last month, or would it get this wrong without it? If neither, delete the line. Then go the other way: OpenAI recommends that "When Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md." Every new line should trace back to a real repeated mistake, not to a worry.

The counterargument is fair: deleting a rule that has not been needed recently feels like removing a guardrail that might be quietly working. Keep a line if you can name the mistake it prevents. Delete it if you cannot. A line nobody can justify is not protecting anything, and it dilutes the lines that are.

What if the repository already has a CLAUDE.md or Cursor rules?

You can point Codex at an existing file instead of duplicating it. Add the name to project_doc_fallback_filenames in ~/.codex/config.toml, for example project_doc_fallback_filenames = ["CLAUDE.md"], and Codex treats it as an instructions file. Because Codex reads only one file per directory, a folder that holds both AGENTS.md and CLAUDE.md gives Codex the AGENTS.md only.

The cleaner long-term move, if more than one agent works on the repository, is the one the AGENTS.md site suggests for migrations: keep AGENTS.md as the real file and make the old name a symbolic link to it, so there is one contract to maintain. For the wider question of what lives in files versus the chat, vibe coding vs spec-driven development covers the three layers of context an agent needs, and the agent-ready spec checklist covers the per-task layer that AGENTS.md deliberately leaves out.

Run your first task against the new file

Write the file, run the summary check, then hand Codex one small task from your backlog and read its final message against your definition of done: did it paste the test output, did it list every file, did it stop before touching a path on your stop list? Each miss is either a line to tighten or a line to add. The Codex feature build loop takes the same file through a full feature, plan to pull request.

See the Building with Codex bootcamp for the session plan and the next cohort dates.