Writing AGENTS.md for Codex

Codex agents md is the file Codex CLI reads before it touches your code, and if you get it wrong you end up with an agent that ignores your build commands, invents its own coding style, and asks questions you already answered somewhere in the repo. This guide covers what AGENTS.md is, how Codex discovers and merges multiple copies of it, what to put in it, and the format mistakes that quietly make agents skip half your instructions.

What AGENTS.md actually is

AGENTS.md is a plain markdown file, usually placed at the root of a repository, that gives a coding agent the context a human contributor would get from a README, a CONTRIBUTING guide, and a Slack message from a senior engineer combined. Codex reads it at the start of a session and treats its contents as standing instructions for the rest of that session: how to run tests, which package manager to use, which directories are off-limits, what the commit message convention looks like.

The idea is not new. It grew out of the same instinct that produced .editorconfig and CONTRIBUTING.md: a machine-readable (or in this case, agent-readable) place to put the operational knowledge that lives in a senior developer's head. AGENTS.md became a shared convention across coding agents in 2025 because every team writing agent instructions kept reinventing the same file under different names: CLAUDE.md, .cursorrules, .windsurfrules, CODEX.md. AGENTS.md is the vendor-neutral name that most tools, including Codex, now recognize out of the box.

If your repo already has a CLAUDE.md or a .cursorrules file, you do not need to throw it away. Codex specifically looks for AGENTS.md, so keep an AGENTS.md as the canonical file and, if you use multiple agents, either symlink the other files to it or keep a short pointer in each ("see AGENTS.md for project conventions").

Where Codex looks for it

Codex walks the directory tree and merges every AGENTS.md it finds, from most general to most specific:

1. A global AGENTS.md in your Codex config directory (personal preferences that apply across all your projects).
2. An AGENTS.md at the repository root (project-wide conventions).
3. An AGENTS.md in the current working directory or any parent directory between the repo root and where the session started, if you are working inside a subproject or monorepo package.

More specific files win when instructions conflict, and all of them are additive otherwise. This nesting model is the main reason AGENTS.md scales to monorepos: you put shared conventions (formatting, git hygiene, PR description format) at the root, and put package-specific instructions (how to run this particular service, which test command applies here) inside the package.

A minimal example for a monorepo:

repo-root/AGENTS.md          # workspace-wide rules: package manager, PR style, CI gate
repo-root/apps/api/AGENTS.md # "run `make test` here, not npm test"
repo-root/apps/web/AGENTS.md # "this app uses Vitest, not Jest"

Codex resolves these by reading root-to-leaf as it works in a given directory, so a session that starts editing files in apps/api picks up both the root file and the api-specific file.

What to put in it

Think of AGENTS.md as answering the questions a new hire would ask on day one, minus the ones covered by the code itself. In order of how often they matter:

Setup and run commands. The exact commands to install dependencies, start a dev server, and run the test suite. Do not make Codex guess between npm test, yarn test, and pnpm test when your repo has a lockfile that already answers this. Spell it out anyway; agents burn turns discovering commands that a single line would have given them.

## Setup

Install: `npm install`
Dev server: `npm run dev` (port 3000)
Tests: `npm test` (Vitest, watch mode off by default)
Typecheck: `npm run typecheck`
Lint: `npm run lint -- --fix`

Code style rules that aren't enforced by a linter. If your linter catches it, you don't need to repeat it here; agents will run the linter. Put in AGENTS.md the rules a linter can't check: naming conventions for files, where new components go, which patterns are banned even though they'd pass lint (for example, "never use any, use unknown and narrow").

Directory map and ownership. A short paragraph on what lives where, especially for anything non-obvious. "The legacy/ folder is frozen, do not add new code there, port to src/ instead" saves an agent from confidently building on top of code you're trying to retire.

Git and PR conventions. Commit message format, branch naming, whether to squash, whether Codex should open a PR itself or just leave changes staged. If you have a strict rule like "never add a Co-Authored-By trailer" or "never force-push to main," this is where it lives, and Codex will follow it far more reliably than a rule buried in a chat message three turns ago.

Testing expectations. Whether tests are required before a change is considered done, what coverage bar applies, whether integration tests need a running database and how to start one. If your CI has a required check, name it, so Codex can try to satisfy it locally before handing back control.

Things that are explicitly out of scope. Secrets files, generated code, vendored directories, anything Codex should read but never edit. A short "never edit" list prevents an agent from "helpfully" reformatting a generated schema.ts or touching .env files it found while grepping.

A compact but complete example for a typical Node/TypeScript service:

## Project

Node/TypeScript service behind an Express API. Postgres via Prisma.

## Setup

Install: `npm install`
Dev server: `npm run dev`
Tests: `npm test` (Jest, requires local Postgres via `docker compose up -d db`)
Typecheck: `npm run typecheck`
Build: `npm run build`

## Conventions

- Files: kebab-case. Exports: named exports only, no default exports.
- New API routes go in `src/routes/`, one file per resource.
- Never use `any`; use `unknown` and narrow with a type guard.
- Prisma schema changes require a migration: `npx prisma migrate dev --name <slug>`.

## Testing

Every new route needs at least one integration test in `tests/routes/`.
Run the full suite before calling a task done: `npm test`.

## Do not touch

- `src/generated/` (Prisma client output, regenerate with `npx prisma generate`)
- `.env*` files
- `legacy/` (frozen, being ported to `src/`)

## Git

Conventional commits (`feat:`, `fix:`, `chore:`). No Co-Authored-By trailers.
Open a draft PR when a task spans more than one file; otherwise leave changes staged.

That whole file is under 40 lines and covers the questions that otherwise cost an agent several exploratory tool calls, or worse, get answered wrong by guessing from context.

Writing style that agents actually follow

Codex agents md files behave like a system prompt appended to the session, not like documentation a human will skim later. That changes how you should write it.

Use imperative, unambiguous instructions instead of descriptive prose. "Tests are run with Jest" is a fact; "Run npm test before finishing a task" is an instruction. Agents follow instructions more reliably than they infer instructions from facts.

Keep it short. A 2,000-word AGENTS.md with every historical decision the team ever made is worse than a 200-word one with the five things that matter today. Long files dilute attention across everything else in context; the agent is more likely to miss the one line that matters if it's buried in ten paragraphs of team history. If you have genuinely long-form context (an architecture decision record, a migration plan), link to the file by path and let the agent read it on demand rather than inlining it.

Put the highest-priority rules first and repeat critical ones. If there's exactly one rule you cannot afford Codex to break (never touch production config, never commit secrets, always run migrations through the CLI rather than editing the schema by hand), state it plainly near the top, not buried in a bullet list halfway down.

Prefer commands over descriptions. "Use the project's linter" is weaker than "Run npm run lint -- --fix before committing." An agent can execute the second one verbatim; the first one requires it to go find out what the linter command is, and it may guess wrong.

Avoid contradicting the codebase. If AGENTS.md says "we use Yarn" but the repo has a package-lock.json and no yarn.lock, the agent has to resolve the conflict itself, and it may pick wrong. Keep AGENTS.md in sync with the actual repo state, especially after a tooling migration.

Common mistakes

Writing it once and never updating it. AGENTS.md rots the same way READMEs do. The fastest way to lose an agent's trust in the file is to have it run a command that no longer exists because the project moved from Webpack to Vite six months ago and nobody updated the setup section. Treat AGENTS.md updates as part of the PR that changes the underlying tooling, not a separate cleanup task that never happens.

Making it a wishlist instead of instructions. "It would be nice if tests were written for new features" reads as optional. "New features require tests in the corresponding *.test.ts file" reads as a rule. Agents, like people, treat soft language as soft.

Putting secrets or sensitive infrastructure details in it. AGENTS.md is a plain file in your repo, often committed to version control. Do not put API keys, internal hostnames that shouldn't be public, or security-sensitive detail in it. If Codex needs a credential to run something, point it at an environment variable or a local secrets file that is gitignored, not the value itself.

One giant root file for a monorepo with wildly different subprojects. If your monorepo has a Python data pipeline and a TypeScript frontend, a single root AGENTS.md that tries to cover both ends up vague for both. Push the specifics down into per-package AGENTS.md files and keep the root file to what's genuinely shared: git conventions, CI gates, overall architecture.

Assuming Codex will infer unstated constraints. If your team has a strong opinion ("never introduce a new dependency without asking first," "all database access goes through the repository layer, never raw SQL in route handlers"), it has to be written down. Agents are good at pattern-matching existing code, but a constraint that isn't consistently reflected in the code itself won't be inferred from silence.

Confusing AGENTS.md with a task list. AGENTS.md is standing context, not a to-do list for the current session. Keep task-specific instructions in your prompt to Codex, not in the file. If you find yourself editing AGENTS.md before every session to describe what you want done today, that content belongs in the prompt, not the file.

Testing whether your AGENTS.md is working

Treat it like you'd treat a prompt: iterate based on observed behavior, not intention. A quick way to check whether Codex is actually reading and applying it:

Start a fresh session and ask Codex an operational question it should be able to answer purely from AGENTS.md, such as "what command do I run to execute the test suite here?" If it answers correctly without exploring the repo first, the file is being read and parsed as expected. If it starts grepping for a package.json or Makefile instead of citing the file, either the file isn't present where Codex expects it, or the relevant instruction is buried too deep to surface.

Watch for repeated violations of the same rule across sessions. If Codex keeps adding a default export even though AGENTS.md says named exports only, the instruction is either contradicted by existing code (agents pattern-match code over prose) or worded too weakly. Fix the underlying code inconsistency first; a rule that the codebase itself doesn't follow is fighting an uphill battle.

Keep an eye on session length. A well-written AGENTS.md should reduce the number of exploratory tool calls Codex makes before it starts working, because it isn't rediscovering the same setup facts every session. If sessions still open with several minutes of "let me check how tests are run here," the file isn't doing its job yet.

FAQ

Does Codex support AGENTS.md out of the box, or does it need configuration? Codex looks for AGENTS.md automatically at the repository root and in parent/working directories without extra configuration. You don't need a flag or a settings entry to enable it; simply adding the file is enough.

Can I use the same AGENTS.md for Codex and other coding agents? Yes, and this is the point of the convention. Most modern coding agents, including Codex, either read AGENTS.md natively or can be pointed at it. If a tool insists on its own filename (like CLAUDE.md), keep that file as a short pointer to AGENTS.md, or symlink it, rather than maintaining two divergent sets of instructions.

How long should AGENTS.md be? Long enough to answer the setup, convention, and boundary questions a new contributor would ask; short enough that every line still matters. Most well-maintained ones land between 100 and 400 lines for a single project, with monorepo root files on the shorter end and package-specific files even shorter.

What happens if I have conflicting instructions in a root AGENTS.md and a nested one? The more specific file (closer to the directory Codex is working in) takes precedence for anything it explicitly overrides. Keep genuinely shared rules, like git conventions, only in the root file so you don't have to repeat or accidentally contradict them lower down.

Should AGENTS.md include the project's architecture in detail? A short orientation, yes: what the major pieces are and how they talk to each other. A full architecture document belongs in its own file, linked from AGENTS.md by path, so agents can read it on demand instead of loading it into every session whether or not it's relevant to the current task.

Can Codex edit AGENTS.md itself? Nothing stops it technically, but treat AGENTS.md as something a human reviews before it changes, the same way you'd review a change to a CI config. If you want Codex to propose updates (for example, after it discovers a new test command), have it suggest the diff rather than committing directly, so a person signs off on new standing instructions before they apply to every future session.

Does a missing AGENTS.md break anything? No. Codex works without one, falling back to exploring the repo and inferring conventions from the code itself. The tradeoff is that every session pays the discovery cost again and is more likely to guess wrong on anything that isn't obvious from the code, which is exactly the gap AGENTS.md is meant to close.