The counterintuitive finding
Generating your AGENTS.md from a model feels efficient. The research disagrees: developer-written vs LLM-generated instruction files showed the generated ones reduced task success in 5 of 8 settings, added extra steps per task, and raised inference cost with no quality gain.
Why it underperforms
A model writing from general knowledge:
- restates what the agent already knows (generic best practices)
- produces vague, plausible directives that don't change behaviour
- → the exact bloat that makes agents ignore the file
The value is what only you know
The convention you adopted after a painful bug. The directory that must never be touched, for a non-obvious reason. The exact command with the flag that matters. A model can't generate what it doesn't know — so it fills the space with filler.
Where automation does help
- Scaffolding: generate a skeleton of headings + detected tooling, then fill and prune by hand.
- Machine-maintained sections fed by a real source of truth (not the model's guess).
The dividing line is the source: never let the model invent your project's context.
The tell
Generated files read like they could describe any project. Hand-written ones read like they could only describe yours. Aim for that.
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.
Hand-written or generated — what's in your AGENTS.md right now? 👇
Top comments (0)