Context Rot: Why Your CLAUDE.md Is Making Your AI Dumber

If you use Claude Code on a real codebase, you have a CLAUDE.md file. Probably more than one. You started with a few rules. Then you added code style guidance. Then testing instructions. Then deployment quirks, environment variables, architectural decisions, common gotchas. Someone on the team ran /init and pasted the output. Six months later the file is 800 lines long, and Claude is ignoring half of what you wrote.

I noticed it gradually. Claude would miss instructions I knew were in the file. It would re-introduce patterns I had explicitly banned. Tasks that used to take one attempt started taking three. I added more instructions to compensate, which made it worse. The file grew. The quality dropped. The file grew again.

One of my repositories has five nested CLAUDE.md files:

Path	Lines	Estimated Tokens
`CLAUDE.md` (root)	1,007	~9,702
`src/CLAUDE.md`	710	~5,627
`e2e/CLAUDE.md`	696	~6,338
`supabase/CLAUDE.md`	247	~2,414
`supabase/functions/CLAUDE.md`	818	~7,033
Total	3,478	~31,114

When I work in supabase/functions/, Claude loads three of these files: root, supabase, and supabase/functions. That is roughly 19,000 tokens of instructions consumed before my actual task even enters the context window. Nearly 10% of the 200K token budget, gone.

Anthropic’s own documentation puts it plainly:

“Keep it concise. For each line, ask: ‘Would removing this cause Claude to make mistakes?’ If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!”

GitHub Issue #16073 on the Claude Code repository documents the same experience from multiple users: instructions consistently disregarded, unapproved changes requiring reversion, tasks taking three to five times longer. This is not a bug. It is a documented consequence of how attention works in language models. The term for it is context rot.

#What the Research Actually Says

Chroma tested 18 frontier models in 2025 and found that every single one gets worse as input length increases. Focused prompts of around 300 tokens significantly outperformed full conversation histories of 113,000 tokens across every model family they tested. The degradation is not hypothetical. It is measurable and consistent.

The “Lost in the Middle” paper from Stanford and Berkeley (published in TACL, 2024) documented a U-shaped attention curve: performance is highest when relevant information sits at the beginning or end of context, and drops significantly when it sits in the middle. “Same Task, More Tokens” (ACL 2024) pushed this further, measuring substantial accuracy degradation (from 0.92 to 0.68) at just 3,000 tokens, well below any model’s advertised context window.

The distractor finding is the most counterintuitive. Even a single irrelevant piece of information in the context significantly hurts performance. Four distractors compound the damage further. Among the most harmful distractors are those topically similar to the task: they look relevant, so the model attends to them, and they pull the output off course. A CLAUDE.md full of verbose instructions about authentication patterns is exactly this kind of distractor when the actual task is writing a database migration.

Research from Distyl AI adds a structural dimension: the best frontier reasoning models maintain near-perfect instruction-following through approximately 150 instructions before performance begins to decay, with even top models falling to 68% accuracy at 500 instructions. Reasoning models show a threshold pattern (steady, then cliff). Mid-tier models show linear decay. Smaller models show exponential decay.

There is one more detail that most practitioners miss. Claude Code injects CLAUDE.md content with a system reminder that states the content “may or may not be relevant.” The model is explicitly permitted to dismiss your instructions as irrelevant to the current task. The larger and noisier the file, the more likely it is that individual rules get dismissed. The instructions you spent time writing are competing for attention with every other token in the context, and they are losing.

#Compression Is Not About Whitespace

When I started thinking about how to fix this, my first instinct was wrong. I assumed compression meant removing blank lines and tightening formatting. Structural cleanup. The kind of thing a script could do in ten lines.

The real problem is semantic. A CLAUDE.md section that explains the same authentication pattern in three different places is not a formatting issue. A “What NOT To Do” list that restates rules already expressed positively in earlier sections is not a whitespace issue. An inline code example that duplicates the boilerplate template shown two sections above is not a whitespace issue. These are entropy problems. The information density per token is low, and every redundant token acts as a distractor.

Microsoft Research’s LLMLingua demonstrated that prompts can be compressed by a factor of 20 with only a ~1.5 percentage point performance loss on reasoning benchmarks. Their follow-up, LongLLMLingua, found something more striking: reducing context to one quarter of the original tokens produced up to a 21.4% improvement in multi-document QA performance. Removing distractors does not just save tokens. It actively improves output quality.

Less context, done right, produces better results than more context done carelessly.

#Building the Compressor

I had been compressing CLAUDE.md files by hand. Reading each section, deciding what was essential, rewriting the rest. It worked, but it did not scale across five files and 3,000 lines. So I built a plugin.

The question was whether this should be a skill or a plugin. Skills are passive instruction sets. Claude reads them and follows the principles. But a compressor needs a command to trigger it, an iterative loop that processes each section, two distinct agent roles, and user interaction at every step. That requires orchestration. A plugin was the right abstraction.

The architecture has one design decision that matters more than the rest. The pipeline uses two agents, not one:

“The compressor needs to be aggressive: remove everything non-essential. The reviewer needs to be adversarial: find what was lost. Combining these into one agent creates a conflicting prompt. You can’t be both aggressive and conservative. Separating them mirrors how human editing works: writer then editor.”

The compressor agent rewrites a section to minimize tokens. The reviewer agent checks the result against the original and flags information loss using a severity scale. The user sees the diff, the review, and decides: approve, edit, or skip. Then the approved section is written back to the file immediately. No deferred assembly. If the session crashes mid-file, everything approved so far is already on disk, and git diff shows the progress in real time.

The build produced twelve files: a manifest, a skill with compression principles and technique references, two agents, a /compress command, before-and-after examples, and a SessionStart hook that injects awareness of the compressor when Claude detects large instruction files. Two validation agents (a skill reviewer and a plugin structure validator) ran in parallel against the finished plugin. Both passed.

Two modes: lossless (structural cleanup only, always safe) and lossy (semantic rewriting, where the compressor-reviewer loop does its real work). Sections process in batches of five with parallel agent dispatch for roughly a 4x wall-time speedup over sequential processing. An --auto flag skips the per-section approval gate for hands-off operation.

#What 44% Actually Looks Like

The first real test was supabase/functions/CLAUDE.md: 818 lines, 17 sections, approximately 4,031 tokens. One of the nested files in the repository I described earlier, the one that loads 19,000 tokens of instructions before the actual task begins.

The reviewer’s verdict:

“This is a good lossy compression. Deduplication is the biggest win. The validation pattern, standard auth pattern, and import warnings all appeared in multiple places, correctly collapsed to single occurrences. All specific values preserved: port numbers, URLs, env var names, timeout limits, error codes, function signatures. All prohibitions survived.”

Four examples of what the compression actually did, generalized from the real diff:

Utility documentation collapsed into a reference table. Four separate subsections, each with full code blocks showing imports and usage examples for shared modules, became a single table with export names, signatures, and return types. Roughly 80 lines to 8.

Bullet formatting to single-line rules. A five-line bulleted list with blank lines between items became a single sentence. Five times fewer tokens. Identical semantic content. An LLM parses both representations the same way.

Redundant negations eliminated. A “What NOT To Do” section had eight items. Three of them restated rules already expressed positively in earlier sections (“Don’t use CommonJS” when the imports section already showed the correct ESM pattern). Reduced to five.

Testing rules compressed into prose. A ten-item checklist became a single paragraph. This is where the reviewer earned its keep. The reviewer flagged this specific compression as potentially reducing instruction-following reliability:

“This is the most concerning compression. While all ten rules are technically present, they are jammed into a run-on sentence. An LLM following these instructions is more likely to miss one of the middle items. The bullet list was structurally superior for a checklist of rules.”

That review changed the skill’s reference files. Not every compression is an improvement, and the adversarial reviewer exists precisely to catch the cases where aggressive rewriting crosses the line from concise to lossy-in-the-wrong-way.

Net result: 818 lines to 433. Approximately 4,031 tokens to 2,250. A 44% token reduction across 16 of 17 sections.

#What the Build Taught the Tool

The live test surfaced two gaps in the compression technique catalog that I had not anticipated.

The first was deduplication orphaning. When the compressor removes content from a section because it duplicates an earlier section, the heading can survive with nothing meaningful under it. A section titled “Authentication” that now just says “see above” is worse than no section at all. It confuses both humans and models scanning headings. The rule added: never leave headless sections. Either remove the heading entirely, add a one-line cross-reference, or merge the remnant into an adjacent section.

The second was the distinction between operational and illustrative examples. A curl command that a developer copies and runs verbatim is not the same as a code snippet that demonstrates a pattern. Operational examples earn their tokens. Illustrative examples are compressible. The compressor needed to distinguish these, and it had not been instructed to.

Both gaps were small additions to the technique reference files. The compressor learned them, and subsequent runs handled both cases correctly. This is the feedback loop the two-agent architecture enables: the reviewer catches a problem, the skill absorbs the lesson, and future compressions are better.

The final feature closed the loop on the original problem. Instead of running /compress on each file individually, /compress-all points at a repository and compresses every matching file recursively. Auto-approve mode, batched processing. Five files, 3,478 lines, one command.

#Use It

The markdown-compressor is part of fractional-cto, an open-source Claude Code plugin collection. Install the plugin and run /compress on any CLAUDE.md file. Add --lossless for structural-only cleanup, --auto for hands-off operation, or use /compress-all to sweep an entire repository.

If your CLAUDE.md is over 300 lines, context rot is already costing you. The research is clear: removing low-value tokens does not just save context. It makes the remaining instructions more likely to be followed. The best compression for your AI’s instructions is the same as for any writing: say less, mean more.

#Sources

All sources below are cited as they appear in the underlying research documents produced during this project. They were not independently re-verified for this post, which, given the subject matter, felt worth stating.

Chroma Research. “Context Rot: How Increasing Input Tokens Impacts LLM Performance.” Jul 2025. https://research.trychroma.com/context-rot
Liu, N. F. et al. “Lost in the Middle: How Language Models Use Long Contexts.” TACL, 2024. https://aclanthology.org/2024.tacl-1.9/
Levy, M., Jacoby, A., Goldberg, Y. “Same Task, More Tokens: the Impact of Input Length on the Reasoning Performance of Large Language Models.” ACL, 2024. https://arxiv.org/abs/2402.14848
Shi, F. et al. “Large Language Models Can Be Easily Distracted by Irrelevant Context.” ICML, 2023. https://arxiv.org/abs/2302.00093
Jaroslawicz, S. et al. “How Many Instructions Can LLMs Follow at Once?” 2025. https://arxiv.org/abs/2507.11538
Anthropic. “Claude Code Best Practices.” https://code.claude.com/docs/en/best-practices
GitHub Issue #16073. “Claude Code Quality Degradation: Ignoring Instructions, Excessive Token Usage.” https://github.com/anthropics/claude-code/issues/16073
Jiang, H. et al. “LLMLingua: Compressing Prompts for Accelerated Inference of Large Language Models.” EMNLP, 2023. https://github.com/microsoft/LLMLingua
Jiang, H. et al. “LongLLMLingua: Accelerating and Enhancing LLMs in Long Context Scenarios via Prompt Compression.” ACL, 2024. https://llmlingua.com/longllmlingua.html