Your AGENTS.md File Is Making Your AI Worse

Remember when Anthropic and OpenAI told everyone to add context files to their repos? AGENTS.md, CLAUDE.md, those helpful guides that tell AI coding agents how your project works?

Turns out they're backfiring.

New research from ETH Zurich tested this on 60,000+ GitHub repos. The results? AI-generated context files reduce task success rates by 3%. Human-written ones only improve success by 4%, barely above statistical noise. Both jack up your inference costs by over 20%.

The thing everyone rushed to implement is actively making AI agents worse at their jobs.

The Problem Nobody Saw Coming

Here's what's happening. You write an AGENTS.md file explaining your project structure, coding standards, testing requirements, deployment process. Seems helpful, right? Give the agent context, it performs better.

Except the opposite happens.

The research team tracked agent behavior across multiple LLMs and coding assistants. Agents WITH context files explored more code. They ran more tests. They looked busier. But they solved fewer problems.

Why? Because context files add requirements the agent wouldn't have thought of on its own. Your helpful "run all tests before committing" instruction means the agent now has to pass tests it would have ignored. Your "follow our naming conventions" note means it rewrites working code to match style guides.

You gave it more hoops to jump through. So it fails more often.

The LLM-Generated Context Trap

It gets worse with AI-generated context files. A bunch of tools popped up to auto-generate AGENTS.md files by analyzing your codebase. Sounds efficient. Let the AI write instructions for the AI.

Those performed the worst. Three percent drop in success rates.

The AI doesn't know what's actually important versus what's just... there. It documents everything. File structures. Dependency chains. Historical decisions that don't matter anymore. The agent reads all of it, treats it as gospel, and ties itself in knots trying to satisfy requirements that were never requirements in the first place.

Human-written context files do slightly better because humans have judgment. We know what to leave out. But even then, the improvement is tiny. Four percent. That's one extra task solved out of every 25.

And you're paying 20% more in API costs for that marginal gain.

What Actually Works

The researchers had a clear recommendation: keep context files minimal. Don't explain your entire project. Don't document every convention. Don't try to teach the agent your team's way of doing things.

Include only the stuff that's truly non-obvious. Specific tooling requirements the agent can't figure out from your package.json. Authentication flows that don't follow standard patterns. The weird build script you inherited from three engineers ago that breaks if you look at it wrong.

That's it. Two or three critical details. Not a user manual.

Think about how humans onboard to a new codebase. You don't read a 47-page design document before writing your first line of code. You ask "where's the thing I need to change?" and figure out the rest as you go. Agents work the same way.

Give them the map to the treasure, not a guided tour of the entire island.

Why This Matters Now

Over 60,000 GitHub repositories have added context files in the past year. Most of them following best practices from Anthropic, OpenAI, and other AI companies. Everyone did the thing they were told would help.

And it didn't help. In aggregate, it hurt.

This isn't a "well actually" moment. It's a pattern we're going to see more of as AI development matures. The first-wave advice won't always survive contact with real data. What sounded right in theory doesn't always work in practice.

The good news? This is an easy fix. You don't need to delete your AGENTS.md file. Just trim it. Cut everything that's not absolutely critical. Remove the nice-to-knows. Keep the must-knows.

Your agent will thank you by actually solving the problem you gave it.

The Bigger Lesson

This research highlights something important about working with AI. More context isn't always better context. Sometimes less information leads to better results because it reduces constraints.

Humans do this too. Ever notice how the most helpful code review comments are the short ones? "This function has a memory leak" beats a paragraph explaining your team's entire memory management philosophy. The agent just needs to know there's a leak. It'll figure out how to fix it.

Same principle applies to prompt engineering, RAG systems, and agent architectures. The instinct is to give the model everything. Full documentation. Complete history. All the context. But every extra token is a chance to add conflicting instructions, unnecessary requirements, or outdated assumptions.

Minimalism isn't just aesthetic. It's practical.

What To Do Right Now

If you have an AGENTS.md file in your repo:

Open it. Read it like you're the agent. Every instruction you see is a constraint the agent has to satisfy. Every "please follow this convention" is a potential failure point. Every "our project uses this pattern" is a test the agent has to pass.

Ask yourself: does the agent actually need this to complete tasks? Or am I just being thorough?

Cut everything in the second category. You'll get better results and lower costs.

If you don't have a context file yet? Don't rush to add one. Try working without it first. Only add instructions when the agent repeatedly fails in a specific way that context would solve.

Turns out the best AGENTS.md file might be the shortest one.

---

Source: Gros, D., Ma, H., Müller, M. & Vechev, M. (2026). Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? Proceedings of the 43rd International Conference on Machine Learning (ICML). ETH Zurich. https://arxiv.org/abs/2602.11988