An AGENTS.md file tells a coding agent how to work in your repository. It is loaded into context on every session, which means every line you add is a line you pay for on every task — and a line competing for attention with the actual request.

That single fact explains most of what follows.

Write only what cannot be discovered

If the agent can learn something by looking, do not write it down. The directory layout, the framework in use, the test file naming convention — all of this is visible in the repository and does not need restating.

What cannot be discovered is intent and constraint:

  • The command that runs the tests, when it is not the obvious one
  • Conventions the code does not yet follow consistently
  • Things that look like bugs but are deliberate
  • Directories that must not be edited, and why

Keep it short enough to be read whole

A file over roughly a hundred lines starts to behave like documentation nobody reads. Instructions buried at line 180 do not reliably change behaviour, because they are competing with the entire rest of the context.

If yours has grown past that, the useful question is not “how do I make the agent follow this?” but “which of these lines have ever changed an outcome?”

Be specific about commands

Vague guidance produces vague behaviour. Compare:

Run the tests before committing.

with:

Run `pnpm test -- --run` before committing. It takes about 40 seconds.
Do not run `pnpm test` without `--run`; it starts watch mode and hangs.

The second version prevents a specific, repeated failure. The first is a sentiment.

Say why, not just what

A rule with a reason survives contact with an unfamiliar situation; a bare prohibition does not. “Do not edit src/generated/” invites an exception the first time editing it looks convenient. “Do not edit src/generated/ — it is overwritten by pnpm codegen and your change will vanish” does not.

Review it when it stops working

Treat the file as something that decays. When an agent repeatedly does something you did not want, that is evidence about the file, not just about the model. Either the instruction is missing, or it is present and being outcompeted by three hundred lines of things that no longer matter.