{
  "id": 7325447,
  "title": "I looked at 558 AGENTS.md files: here's a 5-minute check for yours",
  "url": "https://urgent.news/2026/09/14/i-looked-at-558-agents-md-files-heres-a-5-minute-check-for-yours",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-09-14T13:25:06.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/janzong/i-looked-at-558-agentsmd-files-heres-a-5-minute-check-for-yours-5cih"
  },
  "original_language": "en",
  "account": "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).\n\nTwo 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.\n\nThe 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.\n\nThe 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.",
  "summary": "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%).…",
  "key_points": [
    "558 AGENTS.md files analyzed using nine-category taxonomy",
    "85.7% of files prohibit certain actions",
    "Provides five-minute check for evaluating AGENTS.md completeness"
  ],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}