Don't generate your AGENTS.md with an LLM

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? 👇