A single poorly written documentation file can tank your AI coding agent's performance by 30 percent, while a well-crafted one delivers quality improvements equivalent to upgrading to a significantly more capable AI model. That's the surprising finding from Augment Code's systematic study of how documentation affects AI agent behavior in real development environments. The research challenges a widespread assumption: that more documentation always helps. It doesn't. The patterns that actually work are specific, learnable, and counterintuitive.

What Happens When AI Agents Read Your Documentation?

Augment Code pulled dozens of AGENTS.md files (documentation files that guide AI coding agents) from across a large monorepo and measured their effect on code generation quality. The results were stark. The best-performing documentation files boosted agent output quality by an amount equivalent to upgrading from Claude Haiku to Claude Opus, Anthropic's most capable model. The worst files made agent performance worse than having no documentation at all.

What made this gap so dramatic was that the same documentation file could help one task and hurt another by 30 percent. A decision table for choosing between two data-fetching approaches helped the agent on a routine bug fix but caused it to over-explore and produce incomplete solutions on a complex feature task in the same module. The agent read the reference section, opened dozens of other markdown files trying to verify its approach, created unnecessary abstractions, and shipped incomplete work.

Which Documentation Patterns Actually Work?

Augment Code's research identified seven documentation patterns that consistently improved agent performance. The most effective files were concise, focused, and structured around how agents actually read and process information, not how humans prefer to write documentation.

• Progressive Disclosure: The best-performing AGENTS.md files were 100 to 150 lines long with a handful of focused reference documents. Files longer than 150 lines saw gains reverse. The pattern treats documentation like a skill, covering common cases at a high level and pushing details into reference files the agent can load on demand.
• Procedural Workflows: Describing tasks as numbered, multi-step workflows was one of the strongest patterns measured. A six-step workflow for deploying a new integration moved agents from unable to complete tasks to producing correct solutions on the first try. Missing wiring files dropped from 40 percent to 10 percent, and correctness improved by 25 percent.
• Decision Tables: When codebases have two or three reasonable ways to do something, decision tables force the choice up front. A table resolving React Query versus Zustand for state management improved pull request scores by 25 percent on best practices.
• Real Code Examples: Short snippets of 3 to 10 lines from actual production code improved code reuse by 20 percent. Agents followed templates instead of inventing their own patterns, keeping the codebase consistent.
• Domain-Specific Rules: Language or organization-specific rules still matter, but only when specific and enforceable. A rule like "Use Decimal instead of float for all financial calculations" catches precision issues agents would otherwise miss.
• Pairing Prohibitions with Alternatives: Documentation that paired "don't" statements with concrete "do" alternatives consistently outperformed warning-only documentation. Pairing "Don't instantiate HTTP clients directly" with "Use the shared apiClient from lib/http with the retry middleware" tells the agent what to do instead of making it cautious and exploratory.
• Module-Level Documentation: Mid-size modules with around 100 core files and a 100 to 150 line AGENTS.md with a few reference documents delivered 10 to 15 percent improvements across all metrics. Huge, cross-cutting documentation files at the repo root underperformed.

What Documentation Patterns Backfire?

The most common failure mode Augment Code observed was "overexploration," essentially context rot. Two patterns cause it: too much architecture overview and vague descriptions of component responsibilities. When an AGENTS.md included a full service topology covering the event bus, message queues, API gateway routing, and shared middleware layers, agents read 12 documentation files trying to understand the architecture before touching code. They loaded about 80,000 tokens of irrelevant context, got confused about which service owned the configuration, and produced incomplete fixes. Completeness dropped 25 percent.

Files with 15 or more sequential "don't" statements and no "do" alternatives caused agents to over-explore, stay conservative, and do less work. The worst-performing AGENTS.md files were sitting on top of massive surrounding documentation. One module had 37 related documents totaling about 500,000 characters. Another had 226 documents totaling over 2 megabytes. In both cases, removing just the AGENTS.md barely changed agent behavior because the agent kept finding and reading the surrounding documentation sprawl.

How to Write Documentation That Actually Helps Your AI Agent

• Start with Concision: Aim for 100 to 150 lines in your main AGENTS.md file. Keep architecture descriptions concise and isolated. Vague descriptions push agents into exploration mode and load irrelevant context.
• Use Numbered Workflows for Complex Tasks: Break multi-step processes into numbered workflows. Document branching cases in separate reference files. This pattern moved agents from failing to finishing on deployment tasks.
• Create Decision Tables for Ambiguous Choices: When your codebase has multiple reasonable approaches, force the choice up front with a simple table. This resolves ambiguity before the agent writes a single line of code.
• Include Real Code Snippets: Add 3 to 10 line examples from your actual production code. Keep it to a few examples that are most relevant and not duplicative. More than that and agents start pattern-matching on the wrong thing.
• Pair Every Prohibition with a Concrete Alternative: Never just say "don't." Always follow it with "do this instead." This tells the agent what to do and moves on, rather than making it cautious and exploratory.
• Clean Up Surrounding Documentation: If your AGENTS.md is good but your module has 500,000 characters of specs around it, the specs are what the agent is reading. Fix the documentation environment, not just the entry point.

What This Means for Teams Using AI Coding Agents

The research suggests that documentation quality is now a first-order lever for AI agent performance, comparable to model selection itself. Teams running spec-driven development workflows, where structured specifications guide code generation, are particularly affected. Tools like Kiro, GitHub Spec Kit, and BMAD-METHOD all rely on documentation to orchestrate multi-agent workflows across the full software development lifecycle.

For enterprise teams running complex multi-service architectures, context management becomes critical. Augment Code's Context Engine maintains persistent architectural understanding across 400,000 or more files, addressing the cross-repository context gap that breaks most specification workflows at scale in brownfield codebases. The company reports 70.6 percent on SWE-bench, a widely used code generation benchmark, compared to a 54 percent industry average.

The practical implication is clear: if you're investing in AI coding agents, invest equally in documentation quality. A bad AGENTS.md file is worse than having no documentation at all. A good one delivers performance gains that rival upgrading your AI model itself.