I looked at 558 AGENTS.md files: here's a 5-minute check for yours
Short version: I labeled 558 public AGENTS.md files against a 9-category taxonomy. The measured base rates say something boring and useful — almost every file prohibits things (85.7%) and lists build/test commands (82.8%), while almost none of them record a gotcha (13.6%). Two of the nine slots are nearly empty across the whole corpus: gotchas and agent_meta (rules about the agent itself, 25.8%).…
I analyzed 558 AGENTS.md files and categorized them using a nine-category taxonomy. The findings reveal that almost every file prohibits certain actions (85.7%) and lists build/test commands (82.8%), but very few actually record pitfalls (13.6%). The categories "gotchas" and "agent_meta," which pertain to rules about the agent itself, are nearly empty (25.8% each).
Two well-maintained files were examined to check for gotchas, and both failed to include them. The study also compared two files within the corpus and found that they are exemplary in terms of coverage and organization.
The study provides a five-minute check for your own AGENTS.md file, covering five key questions to evaluate the file's completeness and usefulness. These questions include whether the commands are copy-pasteable, if it specifies what must never be committed, if it addresses the agent's behavior, if there are any insights not derivable from the code, and if the paths it points to exist.
The study concludes that AGENTS.md files are typically written defensively, listing things to avoid breaking. The most valuable file is one that few write, and the one that would save the most time. The classification system has a precision of 92% and a recall of 70% for a held-out English set and 88% / 73% for a held-out Chinese set. The recall rate is lower due to the rarity of gotchas and agent_meta categories.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
