Should You Let AI Generate Your AGENTS.md? The Research Says No
It is tempting to ask a model to write your AGENTS.md for you. This is one of the few places where the manual approach genuinely wins, and not by a little. Studies comparing developer-written and LLM-generated instruction files found the generated ones reduced task success in five of eight tested settings, added several extra steps per task, and raised inference cost with no matching quality gain.
Why Generation Underperforms
A model filling in an AGENTS.md from general knowledge tends to restate things the agent already knows — generic best practices, obvious facts about your framework — adding tokens and noise without signal. It also produces vague, plausible-sounding directives that read well but do not translate into specific behaviour. The result is exactly the bloated, low-signal file that agents quietly ignore.
The Value Is in What Only You Know
The worth of an AGENTS.md is in the things only your team knows: 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 cannot generate what it does not know, so it fills the space with generalities instead. Writing it yourself is not a chore you failed to automate — it is the work, and it takes under an hour.
Where Automation Does Help
There are two legitimate uses. Scaffolding: letting an agent produce a skeleton of headings and detected tooling, which you then fill and prune by hand. And genuinely machine-maintained sections generated from a real, governed source of truth rather than the model's general knowledge. The dividing line is the source — never let the model invent your project's context, but do automate the parts that have a real system feeding them.
How to Tell a Hand-Written File from a Generated One
The tell is specificity. A generated file reads like advice that could apply to any project; a hand-written one reads like it could only describe yours — a specific command, a directory named off-limits for a reason you can guess, a convention that is clearly the scar of a past bug. Aim for that signature: every line so particular it could not have been guessed.