AGENTS.md: instructions Codex can follow

A good AGENTS.md file answers the questions Codex would otherwise have to work out on every task. How do you run the project? Which commands check the change? What should stay untouched? A few precise instructions are already useful.

The trap is turning it into a second README. The product history can stay in the documentation. Here, I mainly want information that changes how you work in the repository.

Start with commands that exist

Here is a starting point for this kind of project. The commands must match the scripts actually present in package.json. An invented command in the instructions costs more time than it saves.

1# Working in this project
2
3## Stack
4React 19, TanStack Start, Tailwind CSS 4, pnpm.
5
6## Check a change
7pnpm build
8pnpm typecheck
9pnpm test
10pnpm format:check
11
12## Keep the scope
13Reuse components before adding new ones.
14Do not edit generated files by hand.
15Do not add a dependency without explaining the need.
16
17## Protect data
18Do not read .env files without an explicit request.
19Do not put secrets in client code.
20Do not send real emails during tests.
21
22## Deliver
23Check keyboard navigation and a mobile viewport.
24Report what was tested and what remains uncertain.
25Do not commit, push or deploy without a request.

Put rules in the right place

Codex can read global instructions and project instructions. Files closer to the working directory can refine the rules. To avoid surprises, keep an instruction at the level where it applies. A rule about email concerns the server, not every interface component.

If the file gets long, replace detailed explanations with paths to the relevant documents. “For migrations, read docs/database.md” is easier to maintain than a copy of that page. The file must, of course, exist and still be up to date.

Write rules you can check

“Write clean code” leaves almost everything open. “Reuse the Button component and check keyboard focus” gives two concrete actions. A good instruction says what matters in this repository without forcing a universal recipe on every file.

After changing the stack or scripts, review the instructions. When an error keeps coming back, ask whether a precise sentence could prevent it. The file should remain useful for the next task.

Instructions do not lock down access

Writing “do not deploy” does not remove deployment permissions. Approvals, account permissions and the execution environment still matter. AGENTS.md explains the boundaries. It does not replace the technical controls that enforce them.

For the request itself, I go through an example in Working better with Codex.