# Your AGENTS.md Might Be Making Your Agents Worse
There is exactly one file every agent vendor agrees on. Claude Code wants a CLAUDE.md. Copilot wants its instructions file. Cursor, Codex, the open-source frameworks — all of them tell you the same thing: write a context file at the root of your repository, describe your project, your conventions, your tooling, and the agent will work the way your team works. It became the closest thing agentic coding has to a ritual. Repositories that disagree about everything else agree about this.
In February, researchers at ETH Zurich did the thing rituals hate most: they measured it. The study ("Evaluating AGENTS.md," arXiv:2602.11988) ran coding agents against 438 real tasks in two arms — established SWE-bench issues with context files generated the way vendors recommend, and a new benchmark built from repositories whose developers had hand-written and committed their own files. Three conditions per task: developer file, generated file, no file at all.
The result, in the paper's own careful language: context files do not generally improve task success — in the stronger arm they tend to reduce it — while increasing inference cost by more than 20% on average. And the finding held across models, across agents, and — this is the uncomfortable half — for both kinds of file. The machine-dumped one and the lovingly hand-committed one. A README for robots, often written by robots, read expensively by robots, to no measurable benefit.
Why the file backfires
The trace analysis is where it gets genuinely instructive. The agents were not ignoring the files. They were obeying them. Given a context file, agents ran more tests, traversed more of the repository, read more files, and reached for every repo-specific tool the file mentioned. Obedience is the product working as designed — and it is exactly the problem. A context file is not advice an agent may weigh; it is a standing order the agent will execute. Every paragraph of repository tour, every "we generally prefer," every stale convention from two refactors ago becomes mandatory exploration, billed at full token price, on every single task. The researchers' conclusion says it plainly: unnecessary requirements make tasks harder, and human-written context files should describe only minimal requirements.
“The study didn’t kill the context file. It killed the lazy one.”
This is Delta's Law 4 wearing a lab coat. The law says context not provided is context invented — leave a blank, and the model fills it from the internet's average. The study exposes the law's less famous corollary: context provided indiscriminately is context obeyed — at full price, whether or not it helps. The failure mode isn't silence anymore. It's noise with authority.
The supporting evidence points the same direction from three angles. Anthropic's own context-engineering guidance defines the goal as the smallest set of high-signal tokens that maximizes the outcome — smallest is doing real work in that sentence. Benchmark work on context retrieval finds over-stuffing degrades results even when every added item is individually "relevant." And the first large empirical survey of these files in the wild — 2,303 of them across 1,925 repositories — reads like a study of sediment: files that grow, drift, and get maintained the way all documentation gets maintained, which is to say occasionally and after the damage.
What the file is actually for
None of this argues for deleting your context file. It argues for specifying it — which is a different discipline than describing your project. A context file built on the book's frame carries constraints, not scenery:
Invariants and prohibitions, not narration. "All monetary values use the decimal Money type; binary floating point is prohibited" earns its tokens forever. "This service handles our payment flows and talks to several downstream systems" earns nothing — the agent can see that from the code, faster and more accurately than your prose.
The deletion test. For every line, ask: would a capable agent get this right from the repository alone? If yes, the line is rent without shelter. Delete it. The study's generated files failed precisely because generation optimizes for coverage, and coverage is the enemy — a model summarizing your repo produces the tour; the tour is what costs 20% and returns nothing.
Verification over vibes. The single highest-value content is executable: the exact test command, the lint gate, the "done means these checks pass" block. It converts the file from opinion into oracle — the agent generates toward your checks instead of exploring around your descriptions.
Small enough to stay true. Practitioner guidance converges on keeping these files well under a few hundred lines; the deeper reason is maintenance physics. A one-screen file gets read, challenged, and pruned. A twelve-screen file gets appended to. Only one of those stays honest.
Treat it as code — because it is. The book's Law 10 puts it in three words: "Prompts are code." A context file is a prompt with a commit history. Version it, review it in pull requests, and — the step almost nobody does — prune it on failure evidence. When an agent goes wrong, the post-mortem question isn't only "what was missing from the file?" It's equally "what in the file sent it there?"
The uncomfortable audit
Open yours right now and score it. Was it generated by a model and committed unedited? Is it longer than one screen? Does it contain a paragraph beginning "This repository…"? Does it describe things any reader of the code could see? Has it been edited down even once since it was created? If you're wincing, the arithmetic from Zurich applies: you are plausibly paying a fifth more per task for output that measures the same or worse — and unlike most technical debt, this one compounds on every agent invocation, forever, silently.
I ran the audit on my own files the night I read the paper. Two survived. One was rewritten to a third of its length. One — a generated file I'd committed in a hurry and never reopened — was deleted outright, and nothing noticed.
The study didn't kill the context file. It killed the lazy one. What's left standing is the version the book has been arguing for all along: a small, versioned, ruthlessly maintained set of constraints that the code itself cannot express — a specification, not a summary. Write that file, and the agent finally reads something worth the price of obeying.
Sources: Gloaguen, Mündler, et al. (ETH Zurich SRI Lab), Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, arXiv:2602.11988 (2026); Agent READMEs: An Empirical Study of Context Files for Agentic Coding, arXiv:2511.12884; Anthropic, Effective Context Engineering for AI Agents (2025–26).