An AGENTS.md is the first thing a coding agent reads about your project. Most of them end up as a slightly shorter README: what the project is, how to install it, which framework it uses. All useful, and all of it the agent could have worked out from the code in a minute.
The sections worth the most are the ones the code cannot tell it.
Two or three sentences: what the project does, who uses it, and the shape of the codebase. An agent that knows this stops guessing from directory names.
## Project overview A web app that helps small clinics manage appointments. TypeScript monorepo: a React frontend, an Express API and PostgreSQL.
Install, run, test. Write them as you would type them, because they will be typed. The quickest way to lose an agent’s trust in this file is one command that no longer exists.
Agents are optimistic about being done. A short list of what must pass — the typecheck, the tests, regenerating whatever is generated — turns "I think this works" into something checkable, and saves the review where you discover it was never run.
These are the ones worth writing even if you skip everything above.
Short enough that you would read all of it before starting work, because that is what you are asking of the agent. One screen is a good target, two is a lot.
When a section wants to grow, move it into its own document and leave a pointer: "the architecture is in ARCHITECTURE.md". A pointer stays true for longer than a summary does.
Every instruction file decays, because the project moves and the file does not. The decay is invisible: nothing fails, agents simply start working from something that used to be right.
Canonly’s AGENTS.md template has the sections above, including the two most people skip. It also keeps track of which version is current, notices when the file contradicts another document in the project, and tells you when an agent has been working from a version you have since replaced.