Creating an AGENTS.md file to make your AI coding agent smarter may be doing the opposite, according to new research. In experiments run by researchers at ETH Zurich on 138 real-world projects, success rates were lower when a context file was present.

What is AGENTS.md?

AGENTS.md is an instruction sheet that tells an AI coding agent about a project's structure and rules. It holds guidance like "This project uses FastAPI, so launch it with uvicorn" or "Run the tests with pytest."

Companies such as OpenAI and Anthropic strongly recommend it, and more than 60,000 open-source projects now keep one of these files. Among developers, it had become a "of course you should add it" kind of thing.

The results: performance actually dropped

The researchers tested four AI models, including Claude, GPT, and Qwen. The results were the exact opposite of what anyone expected.

LLM-generated AGENTS.md: success rate dropped by an average of 3%

Developer-written AGENTS.md: a mere 4% improvement

Even more striking is the cost. When a context file was present, the AI consumed more than 20% additional tokens. So you pay more and get worse performance.

Why does this happen?

When the researchers traced the AI's behavior, they found a telling pattern: with an AGENTS.md in place, the AI does too much.

Without a context file, it heads straight for the key files. With one, it combs through the entire project and runs tests excessively—as if seized by a compulsion to "do this perfectly."

GPT-5.2 in particular "thought" 22% more when a context file was present. The AI was treating the task as harder than it was.

If documentation already exists, why bother?

The researchers reran the experiment after stripping out all existing documentation. This time, the LLM-generated context file actually helped. In other words, AGENTS.md had only been supplying information that duplicated the existing README and docs.

So what should you do? A practical guide

1. Don't use an LLM-generated AGENTS.md

Ignore the advice, even from OpenAI or Anthropic. The findings are clear: auto-generated files drag performance down.

2. If a human writes it, keep it minimal

If you truly need one, a developer should write it by hand—but don't go on at length. Just three things:

• Unusual build tools ("Please use uv")
• A distinctive way to run tests ("Run it with make test")
• Files that must never be touched ("Do not edit config.prod.json")

3. The only exception: projects with weak documentation

For a project with no README and a mess of docs, an AGENTS.md can help. But if it comes to that, you're better off cleaning up the existing documentation first.

The takeaway

This research shows that the intuition "more information yields better results" may not hold in the age of AI. The same is true in publishing. Explaining an author's every intention to an editor can actually get in the way of good editing.

AI agents are built to get the most out of the least context. It's worth remembering that, unlike humans, they don't necessarily do better the more context they're given.

If your project has an AGENTS.md, it may be worth a second look. Do you really need it?