Codex CLI Template

AGENTS.md bootstrap for Codex CLI

A starter AGENTS.md template that gives Codex the repo map, validation commands, and review rules it needs to stop guessing.

Ada · 0 points · 20 188

#agents #coding

What vetted this — trust report

## What AGENTS.md is A README for agents: a predictable place to put the context an AI coding agent needs to work in your repository. It's an open convention rather than a vendor format — Codex reads it, and so do Cursor, VS Code, the Copilot coding agent, Gemini CLI, Aider, Zed, Jules, and a long list of others. One file, most of the ecosystem. There's no schema and no required fields. Which means the quality varies enormously, and the difference between a good one and a bad one is almost entirely about whether the lines are *load-bearing*. ## Copy this into `AGENTS.md` ````md # Repository guide for Codex ## Goal State what this codebase does in 2-3 sentences and what matters most when changing it. ## Project map - `src/...`: - `tests/...`: - `docs/...`: ## Commands you should prefer - Build: `...` - Targeted tests: `...` - Full tests: `...` - Lint or typecheck: `...` ## Working rules - Read the nearest implementation and test before editing. - Keep patches small and local. - Prefer updating existing patterns over inventing new ones. - Do not broaden scope after the first edit until validation runs. ## Review rules - After each substantive edit, run the narrowest validating command first. - Summarize failures concretely: command, error, likely cause. - If you cannot validate, say exactly why. ## Repo-specific traps - Paths or files that are commonly edited by mistake: - Commands that are slow or flaky: - Generated files to avoid touching directly: ## Output expectations - Be concise. - Mention changed files. - Mention validation performed. - List open assumptions separately. ```` ## How to use it 1. Run `/init` if you want Codex to scaffold the file for you. It produces roughly the right sections and roughly no insight — that's fine, it's a skeleton. 2. **Replace every placeholder with repo-specific truth.** A file full of scaffold text is worse than no file, because it looks maintained. 3. Keep the command section current. **Stale commands are worse than no commands** — an agent that runs a command that no longer exists loses its feedback loop and starts guessing, confidently. ## The sections that actually earn their place **Commands.** The highest-value section by a wide margin. Include the flags, and include the known failure: *"`make test` without Docker running fails with a confusing DNS error — start Docker first."* An agent with a working test loop can verify itself. Without one it writes code blind and reports success. **Traps.** The mistakes this repository has actually caused, with the symptom so they're recognizable. This section should grow every time you correct the agent twice for the same thing. **Project map.** Not a directory listing — the agent can run `ls`. Write the *decisions*: which layer may depend on which, which directory is generated, where the single source of truth lives for a rule that's easy to re-derive wrongly. **Output expectations.** Cheap to write, immediately visible in every response. ## Nesting, for monorepos Put an `AGENTS.md` inside each package. Agents read the **nearest** file in the directory tree, so the closest one takes precedence. Package-specific conventions belong in the package; only genuinely global rules go at the root. Precedence, in order: an explicit instruction in your prompt beats the file; the nearest file beats a more distant one. This is worth setting up properly. A root file carrying five packages' worth of conventions is mostly irrelevant on any given task, and irrelevant context competes with the actual work. ## What to leave out - **Praise and vibes.** "Write clean, maintainable code" changes no decision. - **A restatement of the framework's docs.** It knows what a React hook is; it doesn't know your team banned `useEffect` for data fetching. - **Anything a linter enforces.** Let the linter do it — a rule with a machine behind it can't be ignored, and one in prose can. - **Aspirational rules the codebase contradicts.** Conflicting evidence produces unpredictable behaviour, which is worse than no rule at all. - **Everything, exhaustively.** The file is read at the start of every session and competes with the task. One tight page that's entirely load-bearing beats five pages with three good paragraphs. The test for any line: **would an agent that ignored this sentence write code that compiles, passes tests, and is still wrong?** If yes, keep it. ## Maintaining it - **Write it from corrections, not from planning sessions.** The best files accumulate one line at a time, each one a mistake that won't happen twice. - **Delete aggressively.** When a rule becomes enforced by a test or a linter, remove it from the file. Its job is done by something better. - **Review it like code.** It ships in the repo, it changes behaviour, and a stale line costs someone an afternoon. ## Why it works Codex performs markedly better when the repository tells it where the real entry points and validation hooks live. Most of what an agent gets wrong in an unfamiliar codebase is a guess it had to make — and every accurate line in this file converts a guess into a fact, for every session, permanently.

What AGENTS.md is

A README for agents: a predictable place to put the context an AI coding agent needs to work in your repository. It's an open convention rather than a vendor format — Codex reads it, and so do Cursor, VS Code, the Copilot coding agent, Gemini CLI, Aider, Zed, Jules, and a long list of others. One file, most of the ecosystem.

There's no schema and no required fields. Which means the quality varies enormously, and the difference between a good one and a bad one is almost entirely about whether the lines are load-bearing.

Copy this into `AGENTS.md`

# Repository guide for Codex

## Goal
State what this codebase does in 2-3 sentences and what matters most when changing it.

## Project map
- `src/...`:
- `tests/...`:
- `docs/...`:

## Commands you should prefer
- Build: `...`
- Targeted tests: `...`
- Full tests: `...`
- Lint or typecheck: `...`

## Working rules
- Read the nearest implementation and test before editing.
- Keep patches small and local.
- Prefer updating existing patterns over inventing new ones.
- Do not broaden scope after the first edit until validation runs.

## Review rules
- After each substantive edit, run the narrowest validating command first.
- Summarize failures concretely: command, error, likely cause.
- If you cannot validate, say exactly why.

## Repo-specific traps
- Paths or files that are commonly edited by mistake:
- Commands that are slow or flaky:
- Generated files to avoid touching directly:

## Output expectations
- Be concise.
- Mention changed files.
- Mention validation performed.
- List open assumptions separately.

How to use it

Run /init if you want Codex to scaffold the file for you. It produces roughly the right sections and roughly no insight — that's fine, it's a skeleton.
Replace every placeholder with repo-specific truth. A file full of scaffold text is worse than no file, because it looks maintained.
Keep the command section current. Stale commands are worse than no commands — an agent that runs a command that no longer exists loses its feedback loop and starts guessing, confidently.

The sections that actually earn their place

Commands. The highest-value section by a wide margin. Include the flags, and include the known failure: "make test without Docker running fails with a confusing DNS error — start Docker first." An agent with a working test loop can verify itself. Without one it writes code blind and reports success.

Traps. The mistakes this repository has actually caused, with the symptom so they're recognizable. This section should grow every time you correct the agent twice for the same thing.

Project map. Not a directory listing — the agent can run ls. Write the decisions: which layer may depend on which, which directory is generated, where the single source of truth lives for a rule that's easy to re-derive wrongly.

Output expectations. Cheap to write, immediately visible in every response.

Nesting, for monorepos

Put an AGENTS.md inside each package. Agents read the nearest file in the directory tree, so the closest one takes precedence. Package-specific conventions belong in the package; only genuinely global rules go at the root.

Precedence, in order: an explicit instruction in your prompt beats the file; the nearest file beats a more distant one.

This is worth setting up properly. A root file carrying five packages' worth of conventions is mostly irrelevant on any given task, and irrelevant context competes with the actual work.

What to leave out

Praise and vibes. "Write clean, maintainable code" changes no decision.
A restatement of the framework's docs. It knows what a React hook is; it doesn't know your team banned useEffect for data fetching.
Anything a linter enforces. Let the linter do it — a rule with a machine behind it can't be ignored, and one in prose can.
Aspirational rules the codebase contradicts. Conflicting evidence produces unpredictable behaviour, which is worse than no rule at all.
Everything, exhaustively. The file is read at the start of every session and competes with the task. One tight page that's entirely load-bearing beats five pages with three good paragraphs.

The test for any line: would an agent that ignored this sentence write code that compiles, passes tests, and is still wrong? If yes, keep it.

Maintaining it

Write it from corrections, not from planning sessions. The best files accumulate one line at a time, each one a mistake that won't happen twice.
Delete aggressively. When a rule becomes enforced by a test or a linter, remove it from the file. Its job is done by something better.
Review it like code. It ships in the repo, it changes behaviour, and a stale line costs someone an afternoon.

Why it works

Codex performs markedly better when the repository tells it where the real entry points and validation hooks live. Most of what an agent gets wrong in an unfamiliar codebase is a guess it had to make — and every accurate line in this file converts a guess into a fact, for every session, permanently.