Context rot and stale rules in CLAUDE.md

What is context rot?

Chroma's “Context Rot: How Increasing Input Tokens Impacts LLM Performance” (Kelly Hong, Anton Troynikov, Jeff Huber, July 14, 2025) ran 18 models on tasks that should not get harder with length, such as finding a fact in a long document or copying out a run of repeated words. Their summary: “LLMs do not maintain consistent performance across input lengths.” Three findings matter for instruction files:

• Distractors hurt. “Even a single distractor reduces performance relative to the baseline,” and four distractors compound it.
• Loose matches rot faster. Performance “degrades more quickly in input length with lower similarity needle-question pairs.” A rule worded differently from the task it governs is the low-similarity case.
• Coherent filler is worse than shuffled filler. Models did better when the surrounding text was shuffled. A well-organised file of irrelevant rules is not harmless because it reads well.

Does context rot affect Claude Code?

Anthropic uses the term itself. Its 2025 essay on context engineering puts it plainly: “as the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases.” The Claude Code memory docs (checked 2026-09-23, release 2.1.280) say the same about your files: past about 200 lines, a CLAUDE.md will “consume more context and reduce adherence.”

There is also rot inside a session. McMillan's arXiv:2605.10039 ran 1,650 Claude Code sessions and found each additional function the agent generated came with about 5.6 percent lower odds of compliance with the instruction file. The file had not changed. The context around it had grown.

What is a stale rule?

A rule that was true when someone wrote it and is not now. Length is measured in lines; staleness is not measured at all, because nothing in a markdown file expires. The research on how rule files change points the same way. arXiv:2606.12231 mined 7,310 Cursor rules from 83 projects and found that 1,540 rule changes were driven mostly by expansion (29.17 percent) and enrichment (26.59 percent). Files grow. The same study found that when rules were updated, compliance rose from 49.14 to 72.13 percent on average, so keeping a rule current is worth something measurable.

Why is a stale rule worse than a long file?

A distractor in Chroma's sense is merely irrelevant. A stale rule is relevant and wrong. It is sent on the exact task it misleads, and it looks as authoritative as the true rules around it.

The docs say that when two rules contradict each other, “Claude may pick one arbitrarily.” A rule that contradicts the code gets no better treatment. Anthropic's July 2026 post on context engineering adds that conflicting messages make Claude “think more carefully” before acting. Either it follows the stale rule and writes wrong code, or it follows the code and looks like it ignored your CLAUDE.md. Both are charged to the model. Both are the file's fault.

How do I find stale rules in CLAUDE.md?

Start with what the repo can answer. Paths the file names that no longer exist:

grep -ohE '`[^`]*/[^`]*`' CLAUDE.md .claude/rules/*.md \
  | tr -d '`' | sort -u \
  | while read -r p; do [ -e "$p" ] || echo "gone: $p"; done

Expect some noise from globs and URLs. Then the renames since the file was last touched, and the age of every line:

git log -1 --format=%cs -- CLAUDE.md
git log --diff-filter=R --summary --since="6 months ago" | grep rename
git blame --date=short CLAUDE.md

The repo cannot answer the reversed decisions. A rule that says “retry three times” is still syntactically fine after your team chose a dead-letter queue in #eng-payments. For those, the only check is a person: for each rule older than a quarter, name who owns it and ask whether it is still what you decided. A rule nobody can name an owner for is a rule to question first.

How do I retire a rule?

• Delete it. Do not append a correction below the old line. Two versions of a rule is a contradiction you wrote on purpose.
• Put the why in the commit. “Retry rule removed: webhooks go to the DLQ since the payments migration” is the history the next person needs.
• Keep a human note for free. The docs say block-level HTML comments in CLAUDE.md are stripped before the content reaches Claude, so a <!-- ... --> note for maintainers costs no context.
• Watch auto memory too. Claude Code stamps a modified time on memory files and tells Claude to drop stale entries as the index nears its limit. Your own /memory review is still the only check on what it kept.

How often should you review CLAUDE.md?

A calendar review catches little, because rules do not go stale on a schedule. They go stale on events. Tie the review to those:

• A PR that moves or renames a directory the file mentions. Make the path check above part of that review.
• A decision reversed in a thread. Whoever reverses it deletes the old rule in the same week, or names who will.
• A model upgrade. Anthropic cut most of its own prompt for the Claude 5 generation. Rules written to correct an older model are the likeliest to be dead weight.
• A dependency removed from the manifest.

Can you tell which rules are unused?

Not from the file. Every line is sent on every turn, so every line looks used. What you need per rule is two counts: how often it was sent, and how often an answer referred back to it. A rule sent for months and never cited is a candidate to cut. It is not proof the rule did nothing, since an uncited rule may still have shaped a turn. That distinction is the whole of served vs cited.