A great AGENTS.md isn't the longest one — it's the one where every line changes what the agent does. The file loads on every task, and attention is finite, so every line competes with every other.
What earns its place
- Stack + versions (one line)
- A short directory map
- Exact build/test commands, including the single-test command
- Conventions a formatter can't enforce
- A clear "do not touch" list
The commands section is the highest ROI: list your checks and the agent runs them and fixes failures before finishing.
What to cut
- Personality instructions ("act as a senior engineer") — the agent already does this
- Rules a formatter/linter already enforces — wire them into tooling, not prose
- Task-specific context — that belongs in the session, not the file
The one-line test
For every line: "If I remove this, will the agent make a mistake?" Keep the yeses. Delete the nos.
Applied honestly, most of what you first wrote won't survive — and the file gets more effective, because the rules that matter stop competing with noise.
Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.
Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.
What's the one line in your AGENTS.md that's saved you the most rework? 👇
Top comments (0)