What to Put in Your AGENTS.md (and What to Leave Out)
A great AGENTS.md is not the longest one — it is the one where every line changes what the agent does. There is no required schema, but a handful of sections earn their place on almost every project because they capture exactly the things an agent cannot infer from the code. Just as important is knowing what to keep out, because everything you add competes for the agent's limited attention.
The Sections That Earn Their Place
Open with a one-line stack description and your tech stack, with version numbers — an agent will not reliably guess that you are on Next.js 15 rather than 14. Add a short directory map, the exact build and test commands (including how to run a single test), the conventions a formatter cannot enforce, and a clear list of what never to touch. That last section is among the highest-value content in the file: one line can prevent a whole class of mistakes.
The Commands Section Is the Highest ROI
If you get only one section right, make it the commands. When an agent knows the exact build and test commands, it can run them, read the output, and fix its own errors before handing the work back. Write them as literal strings, not descriptions — "pnpm test", not "run the tests" — and include the single-test command so the agent can iterate in seconds on a focused change.
What to Leave Out
Two kinds of content waste the file's budget. The first is personality instructions — "act as a senior engineer," "think step by step" — which change nothing, because the agent already does them. The second is restating rules a tool already enforces: if a formatter handles your style, do not spend lines describing it. Wire those into your tooling and let AGENTS.md carry only the judgement calls nothing automated can check.
The One-Line Test
All of this reduces to a single question you can apply to every line: "If I remove this, will the agent make a mistake?" Keep the line if yes, delete it if no. Applied without mercy, this one test is the whole difference between a file an agent follows and one it ignores — and most of what you first wrote will not survive it, which is the method working.