The example
How Codex finds and merges AGENTS.md files is on What is AGENTS.md and how does Codex read it?. This page is about the content. Here is a root AGENTS.md for a fictional TypeScript web app with a pnpm workspace, built from the list in OpenAI’s Codex best practices (as of November 2026):
# AGENTS.md
## Commands
- Install: pnpm install
- Dev server: pnpm dev
- Run one test file: pnpm vitest run path/to/file.test.ts
- Before you finish: pnpm lint && pnpm typecheck && pnpm test
## Layout
- apps/web: the customer-facing Next.js app
- packages/api-client: generated from openapi.yaml, do not edit by hand
- src/legacy/: still live, but do not copy its patterns into new code
## Conventions
- Use the error helpers in packages/shared/errors.ts, never throw raw strings
- New endpoints need an entry in openapi.yaml; CI fails without it
- Ask before adding a new production dependency
## Do not
- Do not edit migrations that are already merged; add a new one
- Do not touch .github/workflows/ without saying so in the PR description
## Done means
- Lint, typecheck and tests pass, and you show the commands and their output
- Changed behavior has a test
- PR title: [area] short summary
Why each section is there
- Commands. The single most useful thing in the file. Codex can only check its own work if it knows how. agents.md notes that when you list test commands, the agent will try to run them and fix failures before it finishes. Give the command for one test file too, so Codex does not run the whole suite for every change.
- Layout. Not a tree of every folder, which Codex can read itself, but the places where the code misleads: generated code, a legacy directory that looks unused.
- Conventions. Only the ones Codex cannot infer from the code: which of two patterns the team chose, what CI enforces, when to ask first. OpenAI’s own example of a global file includes “Ask for confirmation before adding new production dependencies.”
- Do not. OpenAI’s list calls this “constraints and do-not rules”. Keep it to things that actually went wrong or would be expensive.
- Done means. The best-practices list ends with “what done means and how to verify work”. It turns “looks done” into something Codex can check.
What to leave out
- Things the code already says. A file-by-file architecture description goes stale and takes up the 32 KiB budget Codex reads.
- Vague rules. “Write clean code” or “be careful” give Codex nothing to act on. OpenAI: “A short, accurate AGENTS.md is more useful than a long file full of vague rules.”
- Rules nobody needed yet. Start with the basics and add a rule when Codex makes the same mistake twice. OpenAI suggests asking Codex for a short retrospective at that point and updating the file from it.
- Long procedures. Move planning, review or architecture guidance into separate Markdown files and point to them from AGENTS.md, or into a skill.
- Secrets and personal preferences. Personal defaults belong in
~/.codex/AGENTS.md, not in the shared file.
Nested files in a monorepo
A rule that applies to one package goes in that package’s directory. Codex reads files from the root down to where it works, and the closest file comes last and wins. OpenAI’s docs give a payments example as an AGENTS.override.md:
# services/payments/AGENTS.override.md
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.
The openai/codex repository itself shows the pattern. When we looked on 17 November 2026, it had no AGENTS.md at the root, but several small ones deep in the tree. The one in codex-rs/tui/src/bottom_pane/ is a dozen lines: when you change the paste-burst or composer state machines in that folder, update the module docs too, and check afterwards that the docs mention only behavior that exists in code. Narrow, local and checkable.
The misunderstanding: more rules make a better agent
AGENTS.md loads into context automatically at the start of every session, so every line rides along on every task, relevant or not, and Codex stops reading once the combined files reach 32 KiB by default. A long file does not make Codex more careful; it makes the important rule harder to find and can push a subdirectory’s file out of the window. If Codex keeps ignoring a rule, the fix is usually a shorter file or a rule moved closer to the code it governs.
What this means for a team
A committed AGENTS.md is one of the few things every agent on the team can read: agents.md describes it as an open format for coding agents in general, not for Codex alone. That makes it the right home for build commands and hard conventions. It is also manual: someone has to notice the repeated mistake and write the rule. What Codex learns in one developer’s session stays there; see Does Codex remember previous work? and Codex vs Claude Code for teams.
Where Bombos fits
AGENTS.md holds the rules someone wrote down for one repo. Bombos is a plugin that gives Codex, Claude Code, Cursor and the team’s other AI tools one shared memory above that: team knowledge, rules learned from corrections, and what already lives in mail, documents and other repos, traceable to its source. One developer can try it on their own agents first.
Related questions
How do I generate a first AGENTS.md?
Run /init in the Codex CLI. It scaffolds a starter AGENTS.md in the current directory. OpenAI's best practices say to edit the result so it matches how your team actually builds, tests, reviews and ships.
How do I check what Codex actually loaded?
From the repo root, run codex --ask-for-approval never "Summarize the current instructions." For a subdirectory, add --cd subdir and ask which instruction files are active. Restart Codex after a change; it rebuilds the chain at the start of a session.
Where do code review rules go?
In a ## Code Review Rules section of the AGENTS.md nearest the code it applies to, with repository-wide checks at the root. You can also keep a code_review.md and reference it from AGENTS.md.
Can I put secrets or API keys in AGENTS.md?
No. The file is committed and read by every agent and person with repo access. Point to where configuration lives, such as .env.example, not to the values.
