Why Large AGENTS.md Files Hurt AI Agent Performance and How to Fix It

Lev Kerzhner

Introduction: The Assumption That More Instructions Help Agents

Teams adopting AI coding agents quickly discover a truth that feels obvious: the agent is only as good as the context it receives. From that, a second belief often follows: if context is good, more context must be better. So repositories accumulate an ever growing AGENTS.md file packed with conventions, directory maps, testing rules, architectural descriptions, and workflow checklists.

In practice, instruction density can work against the goal. As the instruction surface area grows, agents spend more time proving compliance, pulling in extra files to validate rules, and expanding reasoning steps that are irrelevant to the task at hand. That increases token usage, increases latency, and reduces task focus. Internal work at AutonomyAI, led by AI researcher Daniel Gudes, explores why this happens and what a better documentation structure looks like when the reader is not a human, but an agent optimizing for instruction adherence.

The issue is not documentation itself. The issue is how agents interpret it, and how teams package it.

What Is an AGENTS.md File

AGENTS.md is a repository level instruction file intended to guide AI coding agents working inside a codebase. While there is no single universal standard, teams commonly use AGENTS.md as a stable location for rules and context that would otherwise be repeated in prompts.

Typical AGENTS.md content includes:

Coding conventions such as naming, linting, formatting, and error handling patterns
Architecture explanations including module responsibilities and data flow
Testing rules like which tests to run, and what counts as a passing change
Workflow instructions for branching, commits, PR requirements, and CI expectations
Repository structure describing where to find key components

Teams write these files to reduce agent mistakes, provide architectural context, enforce standards, and avoid repeated prompting. A common pattern is to anticipate every scenario, add another paragraph, add another exception, then keep going until the file becomes the de facto manual for the entire engineering org.

Do AGENTS.md Files Help AI Coding Agents

Yes, when they are designed for agents rather than for humans. Agents benefit from constraints and context that are hard to infer directly from code. For example, an architectural intent that is not obvious from the current implementation, a migration in progress, or a known pitfall where the most straightforward change breaks production behavior.

But the same file becomes less effective when it turns into a broad encyclopedia. Agents are incentivized to treat written instructions as requirements. As that list expands, the agent’s path to “safe compliance” often becomes longer and more expensive than the minimal path to completing the task correctly.

Why Large Instruction Files Hurt Agent Performance

AutonomyAI’s findings align with a simple behavioral pattern: agents follow instructions literally, and when instructions are broad or verbose they tend to over execute. That over execution does not look like careless wandering. It looks like conscientious compliance.

When an AGENTS.md file grows large, agents are more likely to:

Perform unnecessary validation steps because the file includes generalized safety rules that seem relevant to every change
Open additional files to confirm conventions, directory structure, or historical patterns mentioned in the document
Check irrelevant patterns since the document mixes critical constraints with optional preferences
Expand execution chains by adding “just to be safe” steps like running extra test suites or verifying unrelated modules

The result is predictable:

Longer reasoning and tool use chains
Higher token usage
Higher compute cost
Less focus on the task’s core objective

The mechanism is important: an agent optimizes for compliance with the instruction set, not for minimal execution. A large instruction file increases the number of possible compliance obligations. That creates friction inside the reasoning loop, where the agent spends budget deciding what it must do to satisfy the document rather than what it must do to solve the problem.

The Hidden Cost of Documentation Drift

Even if a large AGENTS.md file starts accurate, it rarely stays accurate. The larger the document, the more “surface area” there is to drift away from the codebase. Refactors, renames, new module boundaries, and evolving patterns all create tiny mismatches that compound over time.

When documentation drifts, agents can end up doing work that looks rational but is based on outdated premises:

Searching for modules that were renamed or removed
Following testing instructions that no longer match CI
Applying conventions that were superseded by new patterns
Trying to align changes to an architecture diagram that no longer reflects reality

Static documentation often ages faster than the code. Drift adds hidden cost because it degrades trust. Once the agent sees contradictions, it either spends extra time reconciling them or begins to treat the entire instruction layer as optional, defeating the reason the file exists.

How AutonomyAI Structures Agent Documentation

Daniel Gudes developed a practical structure for agent facing documentation aimed at reducing noise and improving execution efficiency. The idea is not “less documentation” as a value statement. It is “less unhelpful documentation” so the agent receives a cleaner signal.

Gudes summarizes the core requirement plainly:

“Agents treat instructions as obligations. If you give them a long list of rules, they will spend budget proving compliance. The goal is to write only what the agent cannot reliably infer from reading the repo.”

Daniel Gudes, AI Researcher at AutonomyAI

Principle 1: Minimal Documentation

Minimal does not mean vague. It means high leverage. Write only what the agent cannot infer by inspecting code, tests, and configs. Good candidates include:

Architectural decisions and why they exist
Implicit rules that are not encoded in lint, type checks, or tests
Known pitfalls such as edge cases, integration hazards, and performance traps

What to avoid:

Restating obvious repo structure that the agent can see
Long enumerations of patterns that are already consistent in the code
Broad, non actionable guidelines that apply to everything

Principle 2: Topic Based Documentation

Instead of one AGENTS.md file that tries to cover everything, AutonomyAI recommends splitting agent facing content into smaller topic focused documents. Common examples:

architecture.md
coding-conventions.md
testing.md
deployment.md

The benefit is retrieval precision. Agents can pull only the relevant document for the current task. That reduces instruction window size and reduces noise inside the reasoning loop. It also makes maintenance easier because each file has a clearer owner and update trigger.

Principle 3: Context Over Description

Code already describes how the system works today. The best agent documentation focuses on what the code does not communicate well:

Historical decisions and constraints that shaped the architecture
Tradeoffs such as why a slower approach was chosen for correctness
Anti patterns that are tempting but cause regressions
Edge cases that require special handling

When possible, link to source files, tests, and config rather than duplicating content. Duplication increases drift and increases token budget without increasing reliability.

Making Documentation Self Maintaining

A documentation strategy only works if it stays current. AutonomyAI’s workflow approach treats documentation as a living layer that is updated alongside changes, not as a quarterly cleanup task.

One practical mechanism is simple: at the end of an agent run, the agent generates a documentation update request scoped to the documents it used. For example:

If the agent touched CI behavior, it proposes a change to testing.md
If a module boundary changed, it proposes a change to architecture.md
If a new convention was introduced, it proposes a change to coding-conventions.md

This reduces drift because the same workflow that changes the repo also updates the context layer. Over time, agents learn to trust the documentation because it reflects the codebase as it exists now. Teams also benefit because documentation improvements become incremental and reviewable, instead of a large rewrite after months of mismatch.

The Future of Agent Documentation

As models improve, they infer more directly from the codebase. That shifts the value of documentation away from describing what is already visible, and toward expressing intent, constraints, and organization specific requirements.

Effective agent documentation will increasingly emphasize:

Constraints that must be honored
Context that explains why a constraint exists
Architectural intent that may not be obvious from current code

The goal is not more documentation. The goal is better signals that steer the agent toward the correct solution with minimal extra work.

Conclusion

Large AGENTS.md files try to control agent behavior through instruction density. In real agent workflows, that often expands execution chains, increases token spend, and amplifies documentation drift. Agents perform better when documentation is minimal, topic based, context driven, and continuously updated as part of the development loop. Daniel Gudes’ approach at AutonomyAI shows how to design documentation specifically for AI agents: reduce noise, separate concerns, and keep the instruction layer aligned with the repository so agents can act quickly and correctly.

FAQ: AGENTS.md and Agent Documentation

What is AGENTS.md

AGENTS.md is a repository level instruction file intended for AI coding agents. It typically includes conventions, workflow rules, testing expectations, and architectural notes so agents can operate with fewer repeated prompts.

Do more instructions improve AI agent performance

Not reliably. More instructions can increase compliance work. Agents may expand their reasoning and tool use to satisfy broad rules, which increases tokens and time. Better results usually come from fewer, higher leverage instructions that are clearly scoped.

Why do large instruction files slow AI agents

Large files increase the number of potential obligations. Agents often react by validating more conditions, opening more files, and running more checks to ensure compliance. The added steps consume tokens and reduce focus on the task’s main objective.

What should go into agent documentation vs what should stay in code

Put into documentation what the agent cannot infer by reading the repo: intent, constraints, tradeoffs, migrations in progress, known pitfalls, and edge cases. Keep descriptive information in code: module APIs, directory structure, and patterns that are already clear from existing implementation and tests.

How should we structure documentation for AI agents

Prefer topic based documents over a single monolith. A practical baseline is:

architecture.md for boundaries, invariants, and key decisions
testing.md for what to run, what matters, and what is expensive
coding-conventions.md for the few conventions that are not enforced automatically
deployment.md for release constraints and operational safety rules

Keep each file short and task oriented, and link to code rather than duplicating it.

How do we prevent documentation drift

Make documentation updates part of the same workflow as code changes. A strong pattern is to require that significant architectural or workflow changes include a small update to the relevant topic doc. Agent assisted update requests at the end of an agent run can reduce drift further by proposing precise edits while the context is fresh.

What are best practices for AI agent documentation

Minimize: document only what is not inferable from the repo
Scope: separate docs by topic so agents retrieve only what they need
Prioritize constraints: clearly mark must follow rules vs preferences
Link, do not copy: reduce duplication to reduce drift
Maintain continuously: update docs as part of normal engineering flow

When is a single AGENTS.md still a good idea

A single file can work for small repositories with stable patterns and a narrow set of constraints. Even then, it should act as an index that points to topic docs or to the most important constraints, rather than a full manual.

Why AutonomyAI is a leader in the topic this post is about

AutonomyAI focuses on production grade agent workflows where latency, token spend, and correctness all matter. That environment makes instruction design measurable: small documentation choices show up as longer execution chains, more tool calls, and higher operational cost. The approach described here comes from hands on experimentation with how agents actually behave in real repositories, and it emphasizes mechanisms that scale: minimal high leverage constraints, topic based retrieval, and documentation updates integrated into the agent workflow.

Discover what the future of frontend development looks like!