Teams tested dozens of AGENTS.md files across a big monorepo using AuggieBench, their internal eval suite. They took high-quality PRs, ran the same tasks with and without AGENTS.md, and scored outputs against golden PRs. The gap was huge: the best docs boosted quality as much as jumping from Haiku to Opus, while the worst hurt more than having no AGENTS.md at all. One file improved a routine bug fix by 25% but dropped completeness by 30% on a complex feature because the agent got lost in reference sections. Seven patterns drove real gains. First, keep your main AGENTS.md to about 100–150 lines and push details into focused reference documents—this delivered 10–15% improvements in mid-size modules. Second, lay out numbered, step-by-step workflows; one six-step deployment guide cut missing wiring files from 40% to 10% and lifted correctness by 25%. Third, decision tables resolved common choices—React Query vs. Zustand tables alone upped best_practices by 25%. Fourth, include 3–10 line real-code snippets for core patterns; that nudged code_reuse up 20%. Fifth, enforce domain-specific rules sparingly—“Use Decimal for financials” caught precision bugs. Sixth, always pair “don’ts” with clear “dos.” And seventh, scope AGENTS.md to modular subsystems; 100-file modules outperformed sprawling repo-wide docs. The biggest failure mode was overexploration. Files with long architecture overviews or long lists of warnings made agents load tens of thousands of tokens, roam through irrelevant docs, and produce incomplete fixes. In one case, a two-line config change task saw completeness fall by 25% after the agent swallowed 80K tokens of extraneous context. The fix: trim high-level architecture to boundaries, avoid vague “why” sections, and pair every prohibition with a concrete alternative.