A good AGENTS.md is a model upgrade. A bad AGENTS.md is worse than no docs at all

After analyzing dozens of AGENTS.md files, agent performance varied significantly depending on document quality. Well-made documents produced improvements equivalent to upgrading a coding agent from Haiku to Opus, while flawed documents made results worse than having no documentation at all.

The key factor wasn't the amount of documentation but its structure and scope. The best approach was a short main document of around 100-150 lines linking out to necessary reference documents, and procedural workflows, decision tables, and real code examples boosted performance more than lengthy explanations.

Two patterns stood out in particular. One was using tables to lock in decisions in advance when there were choices to make, like React Query vs Zustand. The other was not just listing "don'ts" but always pairing them with "what to do instead." This combination improved metrics such as best_practices, completeness, and code_reuse.

Conversely, failure patterns were also clear. Excessively expanding architecture explanations or overloading documents with warnings caused agents to fall into overexploration, continuously reading irrelevant documentation, resulting in slower and less complete code. For tasks like introducing new patterns, where existing documentation could actually steer the agent in the wrong direction, spec-driven development was suggested as a better solution than AGENTS.md.

Document discovery paths also mattered. AGENTS.md was almost always discovered automatically, and other reference documents were read when needed. In contrast, nested READMEs or documents isolated under _docs/ were rarely read, leading to the conclusion that important information should be placed in AGENTS.md or referenced directly from it.