Your CLAUDE.md might be making your agent worse
Everyone has a CLAUDE.md now. Almost nobody has checked whether it helps. A 2026 ETH Zurich study found context files often reduce success and add over 20% to inference cost. Here's why config goes net-negative, what good looks like, and a free tool that audits yours.
Sometime in the last two years, the CLAUDE.md became table stakes. Every serious repo has one now — plus an AGENTS.md for Codex, a .cursor/rules, a folder of skills. We all added them because it felt obviously correct: tell the agent how your codebase works, and it'll work better.
Almost nobody went back and checked whether it actually did.
The research is in, and it's not flattering
In February 2026, a team at ETH Zurich published Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?. They ran coding agents on SWE-bench tasks with three setups: no context file, an LLM-generated one, and a human-written one.
The headline finding, in their words: "context files tend to reduce task success rates compared to providing no repository context," while "increasing inference cost by over 20%." Their recommendation is even blunter — "human-written context files should describe only minimal requirements."
The evidence isn't unanimous. A separate 2026 study found AGENTS.md files reduced output tokens in some real-repo setups. But that disagreement is the point, not a footnote: the effect is small, fragile, and entirely dependent on what's in your file. Which means you cannot assume yours is helping. The default assumption — "more context is better" — is the one thing both papers reject.
Why a context file goes net-negative
A bad CLAUDE.md isn't bad because it's wrong. It's bad because of where and when it loads. Four failure modes do most of the damage:
It loads on every single turn. A CLAUDE.md is always-on context. Three hundred lines of "always do X, never do Y" get prepended to every request, whether or not the task has anything to do with X or Y. Multiply by every turn, every engineer, every day — that's a standing tax you pay forever for instructions that are relevant maybe 10% of the time.
It's usually redundant. Your build and test commands are already in the README and package.json. Your architecture is already legible from the directory structure. The agent can read those files. A context file that restates discoverable information is pure token overhead with no new signal.
Over-specification actively makes tasks harder. This is the ETH paper's sharpest point: unnecessary requirements constrain the model down worse paths. Every "you must always..." you add is a rail that can send the agent into a ditch on a task where it didn't apply.
It's pinned to the wrong shape. The single biggest waste: instructions that should be a skill (loaded on demand, only when relevant) sitting in always-on config. And subagents doing mechanical grunt work pinned to your most expensive model because nobody set the tier.
What good actually looks like
The fix isn't "delete your CLAUDE.md." It's to make every line earn its token cost:
- Minimal always-on core. Keep only what's true and load-bearing on most turns. Everything conditional becomes a skill — progressive disclosure, so it costs nothing until it's needed.
- Imperative and specific. "Use the existing error type in
src/errors.ts" beats "try to handle errors well." Vague preferences burn tokens and change nothing. - No redundancy with discoverable docs. If the agent can read it from a file, don't repeat it in context.
- Right model for the job. Mechanical subagents on a fast cheap model; reasoning-heavy work on the frontier one. Defaulting everything to the biggest model is the config equivalent of leaving the lights on.
The test for any line in your config: does this earn its cost on a typical turn? If not, demote it to a skill or cut it.
We ran this on ourselves, and it was worse than we thought
None of this is checkable by eye. You cannot look at a 300-line CLAUDE.md and know which lines are paying rent. So we built a tool that measures it, and the first thing we did was point it at our own machine.
One month of Claude Code: 1,371 sessions, 31.7 days, $6,425 of spend. What it found:
| What we measured | One month, one machine |
|---|---|
| Standing context loaded on every turn | 21,882 tokens |
— of which project CLAUDE.md | 6,429 tokens |
— of which global CLAUDE.md | 1,755 tokens |
| Conditional "read file X when Y" rules | 3 rules, 11,550 tokens |
| Times those rules were actually followed | 0 |
| MCP servers configured | 8 |
| Share of turns that invoked one | 5.4% |
| Subagent spawns per month | 1,032, at 15,527 tokens of prefix each |
| Monthly cost of that prefix alone | $123 |
The line that stings is the zero. Three instructions, confirmed present in the config, weighing 11,550 tokens, telling the agent to go read a file under a condition — measured against what actually happened, they never once fired. We paid for them on every turn for a month and got nothing back. Not because they were wrong. Because nobody checked.
That's the whole argument in one row. This is one developer's corpus, not a benchmark — we don't have a cohort yet and won't pretend otherwise. But it's a developer who thinks about this professionally, and it was still this bad.
The tool is free, and it runs on your machine
cc-audit reads the session transcripts Claude Code already writes to ~/.claude/projects and prints the same breakdown for you:
npx @promptster/cc-audit
No account, no sign-up, nothing installed. It works off token accounting, tool calls, and file paths — never the contents of your files — and it sends nothing anywhere. The audit prints to your terminal and stops there.
If you want it to go further, cc-audit fix reviews your CLAUDE.md and writes proposed patches to a local folder — what to cut, what to demote to a skill, what to sharpen from preference into imperative. It never applies them itself; you read the diff and decide. That one does send your config file for review, which is why it's a separate command you have to type on purpose.
Details, and the rest of what it measures, are at promptster.ai/tools/cc-audit.
It's free for you, and it stays free. The ecosystem is complex and easily bloated. There's no need to quietly pay a context tax that you never agreed to — let alone buy a tool to find out what you're spending.
What we charge for is the other half of the question. Your own habits, on your own machine, you should be able to see for free. Whether the tools your company bought are actually paying off — who's getting leverage, where the cleanup is coming from — is a different problem, and that one's Promptster for Teams.
Either way, you don't need us for this part. Audit your config, cut what's dead weight, and stop paying 20% more for an agent that does slightly worse.
Frequently asked questions
Does a CLAUDE.md file actually make coding agents worse?
Sometimes, yes. A February 2026 ETH Zurich study found that repository-level context files tend to reduce task success rates compared to providing no repository context, while increasing inference cost by over 20%. A separate 2026 study found the opposite effect on output tokens in some real-repo setups. The honest read is that the effect is small, fragile, and entirely dependent on what is in your specific file — which means you cannot assume yours is helping without measuring it.Why would a context file cost money if I only write it once?
Because it is always-on context. A CLAUDE.md is prepended to every request in the session, whether or not the task relates to anything in it. In one real month of Claude Code usage we measured 21,882 tokens of standing context loading on every single turn, of which 6,429 tokens were the project CLAUDE.md and 1,755 were the global one. You pay that on turn one and on every turn after.What makes a CLAUDE.md go net-negative?
Four failure modes do most of the damage. It loads on every turn even when irrelevant. It restates information the agent could simply read from the README, package.json, or the directory structure. It over-specifies, adding requirements that constrain the model down worse paths on tasks where they never applied. And it holds instructions that should be skills — loaded on demand — pinned into always-on config instead.What does a good CLAUDE.md look like?
Keep a minimal always-on core: only what is true and load-bearing on most turns. Move everything conditional into a skill so it costs nothing until it is needed. Write imperatively and specifically rather than as vague preference. Do not repeat anything the agent can discover by reading a file. The test for any line is whether it earns its token cost on a typical turn; if it does not, demote it or cut it.How can I check what my own config costs?
Run npx @promptster/cc-audit. It is a free CLI that reads the session transcripts Claude Code already writes to your local disk and reports what your standing context costs per turn, how much of your bill goes to carrying context rather than generating output, and how often your agent re-reads files it already has. It runs locally, requires no account, and sends nothing anywhere unless you explicitly pass a flag that uploads.