New ETH Zurich Study Proves Your AI Coding Agents are Failing Because Your AGENTS.md Files are too Detailed

“`html

Why Overly Detailed AGENTS.md Files Are Undermining Your AI Coding Agents

By Amr Abdeldaym, Founder of Thiqa Flow

In the rapidly evolving landscape of AI automation, efficient utilization of Large Language Models (LLMs) is critical for accelerating business efficiency. A foundational technique—Context Engineering—has recently emerged as a key to unlocking superior AI coding agent performance. Among the industry’s best practices, using an AGENTS.md file as a centralized context source is widely praised as a “North Star” for guiding agents through complex codebases.

However, a new groundbreaking study from ETH Zurich reveals a counterintuitive reality: the more detailed and auto-generated your AGENTS.md files, the more you risk sabotaging your agent’s success—while inflating computational costs by over 20%.

Understanding the Data: More Tokens, Less Success

Metric	Auto-Generated Context Files	Human-Written Context Files	No Context Files
Success Rate	-3%	+4%	Baseline
Inference Cost Increase	+20%	+20%	Baseline
Reasoning Steps Required	Increased	Moderately Increased	Baseline

The ETH Zurich team evaluated coding agents—including Sonnet-4.5, GPT-5.2, and Qwen3-30B—on both standard benchmarks and a new real-world dataset called AGENTBENCH. Their findings highlight several crucial insights:

Auto-generated context files reduce success rates by about 3%, indicating a net negative impact despite their intended guidance.
Such files inflate inference costs by over 20% and increase the number of reasoning steps needed to complete the same tasks.
Human-authored context files do provide a slight 4% performance boost but still come with increased computational overhead.
Stronger LLMs like GPT-5.2 do not significantly benefit from additional context and often find extra context redundant, since they internally encode common programming knowledge.

Why “Good” Context Often Fails

The study pinpoints a key behavioral trap: AI coding agents exhibit excessive obedience to instructions within context files—even when those instructions are unnecessary. For example:

Directory listings and codebase overviews: These form a staple of many AGENTS.md files but proved redundant, as agents effectively discover file structures on their own without guidance.
Redundant information: When other repository documentation suffices, injecting extra context just becomes overhead token consumption.
Unnecessary constraints: Strict style guides or task-specific rules in context files can hinder general problem-solving by forcing agents to unnecessarily rethink or reverify instructions.

The New Rules of Effective Context Engineering

To truly optimize AI coding agents, firms must reframe how they think about context files. Instead of comprehensive documentation, adopt a model of surgical precision:

1. What to Include (The “Vital Few”)

Technical Stack & Project Intent: Clearly explain what the project is and why—including architecture details such as monorepo layouts.
Non-Obvious Tooling Instructions: Precisely specify build, test, and deployment commands using specific tools (e.g., using uv instead of pip or bun instead of npm), because agents follow these instructions closely.
Multiplier Effect: Explicit instructions can increase tool usage exponentially—for instance, references to the tool uv boosted usage by 160 times.

2. What to Exclude (The “Noise”)

Detailed Directory Trees: Omit them entirely as agents naturally discover relevant files.
Style Guides: Replace human instructions with deterministic formatters and linters to reduce token usage and increase reliability.
Task-Specific Instructions: Avoid including niche rules; keep context broadly applicable.
Unvetted Auto-Generated Content: Never allow agents to self-generate without thorough human review.

3. How to Structure Your Context Files

Keep it Lean: Optimal context files are ideally under 300 lines—and many professional teams maintain files under 60 lines.
Progressive Disclosure: Use a primary file to briefly set direction and link to more detailed, task-specific documents when necessary (e.g., agent_docs/testing.md).
Pointers Over Copies: Rather than embedding static code snippets that become outdated, use pointers like file:line references to relevant sections in the codebase.

Key Takeaways for AI Automation & Business Efficiency

Less is More: Overly verbose context files hinder performance and inflate costs, eroding the value of AI automation investments.
Context Must be Strategic: Inject only the essential instructions that augment an agent’s parametric knowledge and help it navigate tooling nuances.
Human Oversight is Crucial: Auto-generated AGENTS.md files without human curation tend to degrade agent effectiveness.
Optimize Structure: Lean, well-organized context loadouts ensure maximum business efficiency by reducing reasoning overhead and inference latencies.

For organizations leveraging AI for software development and automation, this ETH Zurich study is a critical wake-up call. By prioritizing precision over volume in your AGENTS.md files, you stand to unlock better agent performance while controlling costs—fueling smarter AI-driven business processes.

Explore the full research paper here and stay connected for more insights.

Looking for custom AI automation for your business? Connect with me at https://amr-abdeldaym.netlify.app/.

“`