The Tax You Don’t Notice
My workspace CLAUDE.md was 210 lines. It loaded into every session, across every project, every time. That’s roughly 3,500 tokens of instructions Claude reads before I say a word.
I never questioned it. The file grew over months. A gotcha here, a workflow pattern there, a rule I wrote after getting burned once. Each line made sense when it was added. In aggregate, it was mostly noise.
A recent study from ETH Zurich put numbers to what I was feeling. They tested coding agents across hundreds of real GitHub issues and found that LLM-generated context files reduced success rates by 3%. Even developer-written files only helped about 4%, and both increased inference costs by 20%.
The redundancy problem was the big one. Most context files restated things the agent could already figure out from the repository.
So I audited mine.
What I Found
I went through every line of four CLAUDE.md files and asked one question: would Claude get this wrong without this instruction?
The answer was “no” a lot more than I expected.
| Start from project directory | Context matters |
| Prefer editing over creating | Reduce file sprawl |
| Check existing patterns first | Don't reinvent |
Claude Code’s system prompt already says “ALWAYS prefer editing existing files.” It already operates from the working directory. These lines cost tokens and added nothing. They were instructions to a model that was already instructed.
Then there were the workflow patterns. 60 lines documenting where different workflows store their artifacts, how to invoke tmux, where PRD files go. Every one of those was already encoded in the skill that uses it. The /start script knows project type detection. The a-create-prd skill knows where PRDs live. I was paying tokens to tell Claude things it would learn the moment it ran the relevant command.
And the gotchas. 120+ lines in one project. On closer look: bugs that had been fixed months ago, still documented as active warnings. General shell knowledge. Decisions already made and committed. Barnacles.
Three Questions
The filter that worked:
1. Does Claude already know this?
“Prefer editing over creating”: yes, it’s in the system prompt. “Use bun not npm”: no, it would default to npm. Keep the second, cut the first.
2. Is it encoded in a skill that loads on demand?
Workflow artifact paths, tmux patterns, PRD locations. All lived in the skills that use them. If the information loads when the skill is invoked, it doesn’t need to load on every session.
3. Is this gotcha still active and non-obvious?
“git stash destroys unstaged Edit tool changes”: active, silent, catastrophic. Keep it. “EUL values corrected in session 420”: historical. The fix is in the code. Cut it.
The Numbers
| File | Before | After | Cut |
|---|---|---|---|
| Workspace CLAUDE.md | 210 lines | 64 lines | 70% |
| MEAP project | 245 lines | 163 lines | 33% |
| Plugin repo | 115 lines | 79 lines | 31% |
53% fewer words across the board. Not by removing useful information. By removing information that was either already known, loaded on demand, or no longer true.
What Survived
Three categories:
Behavioral overrides. “No sugarcoating” stays because Claude defaults to cheerful validation. “Factual engineering tone” stays because without it, every response starts with “Great question!” These change behavior. They earn their tokens.
Active gotchas. The traps that are silent, destructive, and non-obvious. git stash eating your Edit tool changes. AskUserQuestion crashing if you pass more than 4 options. Syncthing overwriting your task state from another machine. You can’t derive these from defaults. You have to have been burned.
Project-specific architecture. Data models, build commands, deployment paths. The stuff that’s unique to this codebase and can’t be found by reading the repo structure.
Everything else was either Claude teaching Claude what Claude already knows, or documentation pretending to be instruction.
The Uncomfortable Implication
The ETH Zurich research found that agents treated context files as constraints, not guidance. More instructions meant more reasoning tokens spent trying to satisfy all of them, including the ones that conflicted with what the model already knew.
This reframes the whole exercise. A bloated CLAUDE.md isn’t just wasting context window. It’s actively making the model worse. Every redundant instruction is a potential conflict with built-in behavior. Every resolved gotcha is a constraint on a problem that no longer exists.
Your context window is a public good. Every token in it is a cost paid by every session. Treat it like shared infrastructure. Audit it, maintain it, and only put things there that earn their keep on every single load.
I’m building a periodic debloat skill to automate this. Because context files are like any other code: they accumulate cruft, and nobody notices until they audit.
210 lines to 64. Should have done it months ago.
Written with Claude.