In 1998 I wrote a README for a build system and printed it, because that is what you did then. It went into a ring binder beside the machine. It cost me an afternoon to write and nothing at all to be read, ever again, by anybody.
Last month I wrote an AGENTS.md. No human has read it. It is loaded in full at the start of every agent session, and every one of those loads is billed to me.
Thirty years of writing software and I have never had a document charge rent before.
The file is a purchase
The agent context file is not documentation. It is a line item with a per use price, the price is measurable, and almost nobody has measured it. The evidence we have says you are paying a certain cost for an uncertain gain, and you are paying it on every run for the life of the repository.
That is a procurement decision. It is currently being made by whoever had a spare hour.
Why this one is different
A README is pull. Somebody wants it, somebody opens it, the cost of the read is their attention. A context file is push. It is prepended to the working context every time an agent starts, every time a session compacts, every time a subagent spawns. The cost does not scale with how many people find it useful. It scales with how many times you run.
So the economics invert. A long README written once and read rarely is cheap. A long context file written once and read constantly is expensive, and it gets more expensive the more successful your agent programme becomes.
In February 2026 a group out of ETH Zurich put a number on it. Thibaud Gloaguen and colleagues built a benchmark they call CTXbench: 138 task instances drawn from 12 Python repositories that already had a developer committed AGENTS.md or CLAUDE.md at the root. They screened 5,694 pull requests to get there. They ran four agent configurations over it: Claude Code on Sonnet 4.5, Codex on GPT-5.2, Codex on GPT-5.1 mini, and Qwen Code on Qwen3-30b-coder served locally. Then they ran each task three ways: no context file, a model generated one, and the real one the developers had written.
The results are not what the file is sold on.
A model generated context file moved task success by about minus 0.5% on SWE-bench Lite and minus 2% on CTXbench. Neither result was significant. A developer written file moved it by plus 2.4% on average, p equal to 0.21, also not significant. The one comparison that cleared the bar was developer written against model generated, where the human file won by a margin the paper puts at 7%. Their own summary sentence is flat: “providing context files does not generally improve task success rates.”
The cost side was not ambiguous at all. Model generated files raised inference cost by roughly 20% on SWE-bench and 23% on CTXbench. Developer written files raised it by at most 19% and added 3.34 steps per task on average. The agents were not ignoring the files. The paper is explicit that “instructions in context files are well followed.” They read the instructions, then went and did more work: more tests, more greps, more files opened, more quality checks, much of it beside the point of the task in hand.
And the single most common section in these files, the repository overview, is the one the paper singles out as useless: “repository overviews, although popular and recommended by model providers, are not helpful.” Overviews did not meaningfully reduce the number of steps an agent took before it touched the file it actually needed to change.
What that costs in money
Gartner Peer Insights found in June 2026 that 23% of technology leaders are spending $200 to $500 per developer per month on tokens for coding agents, and 6% are spending over $2,000. DX puts enterprise Claude Code deployments at about $13 per active developer day, or $150 to $250 a month. Gartner’s Nitish Tyagi expects per developer token cost to go from $20 to $200 and in some cases to $2,000, and Gartner forecasts that by 2028 AI coding cost will exceed the average developer salary.
Take the conservative end. Call it $300 a month per developer. A 19% context tax is $57 per developer per month. Across forty engineers that is $27,360 a year, recurring, for a gain the measurement could not distinguish from zero.
That is my arithmetic, not Gartner’s. Run it on your own numbers. The point is that the number exists and it is not small, and I have not once seen it on a budget line or in an AI programme business case.
Three things the field data says
First, almost nobody has one. Research presented at the 23rd Mining Software Repositories conference in 2026 scanned 10,000 active repositories and found roughly 5% carried any AI context file at all. 466 had an AGENTS.md. So the practice everyone is writing about is a minority practice being adopted at speed, before anybody measured it.
Second, the files are written once and abandoned. In the deep analysis of that sample, 50% of the files had not been modified after the commit that created them. Another 23% were modified exactly once. A context file is a set of imperative instructions that an agent follows well. An abandoned one is a set of wrong instructions that an agent follows well. That is not a neutral state, it is worse than having no file, and the failure is silent because the agent never tells you it obeyed something false.
Third, the maintenance is real work and it compounds. An experience report published in February 2026 documents one developer building a 108,256 line C# simulation with Claude Code over 283 sessions and 70 days. The supporting context layer ended up at 54 files and about 26,200 lines, which is 24.2% of the line count of the product itself. Maintenance ran one to two hours a week. The author names the main failure mode without hedging: stale specifications produced conflicting code at least twice.
A quarter of your codebase, in prose, that nobody compiles and no test covers.
Where this breaks
The honest objections are good ones.
The ETH sample is 12 repositories and 138 tasks, Python only, and the repositories are small and recent by construction, because they had to already have a context file to qualify. A twenty year old monorepo with genuinely non obvious conventions is exactly the case where a file should earn its keep, and it is exactly the case the benchmark could not include. I would not call this settled.
A 2.4% lift that fails a significance test is not the same as no lift. It is an underpowered result. If a single failed agent run on a critical path costs you a day of senior time, paying 19% more per task to shift the odds is a trade most operators would take without blinking, and the benchmark has no way to price that asymmetry.
And the strongest objection is the one the paper cannot measure at all. Writing the file forces someone to write down the knowledge that was only in three people’s heads. That is worth doing whether or not an agent benefits, and the humans who join next year will benefit from it more than the model does.
I accept all three. None of them makes the file free. They change the answer to “is this worth buying”, which is a question you can only ask once you admit you are buying something.
What I would do on Monday
Measure your own tax before you argue about mine. Take ten representative tasks, run them twice with the same agent and model, once with the context file and once with it removed, and compare token cost per completed task. An afternoon of work and you will never have to take a blog post’s word for it again, including this one.
Delete the repository overview. It is the most common section in the corpus and the one section the research specifically found does not help. The agent can read your directory tree. It is faster at it than your prose is.
Put a hard ceiling on the file and make every new line compete for space. The observed average for AGENTS.md is 142 lines. CLAUDE.md averages 287 and Copilot instruction files average 310. Length here is a cost, not thoroughness.
Put an owner and a review date in the first three lines. Half of all these files are never touched again after the day they are born, and the instruction that was true in March is being executed with full confidence in October.
Move anything checkable out of prose. If the rule is “always run the linter before committing”, that belongs in a pre commit hook where it is enforced, not in a paragraph where it is re read and re billed a thousand times and still only sometimes obeyed.
The general rule I now apply: a line earns its place in the file only if the agent cannot infer it from the repository and it will still be true in ninety days. Everything else is a script, a test, or nothing.
The binder
That printed README is probably still in a cupboard somewhere. It was a bad document by any modern standard. It was out of date within a year and nobody noticed, because nobody opened it.
The new one gets opened every few minutes, forever, by something that believes every word.
Write it like it costs money. It does.
Most of what I write here started as somebody’s build cost going somewhere nobody forecast. If that is your week, grab a time.