Day 12: When your CLAUDE.md starts to drift

A CLAUDE.md file that no longer matches your repo is worse than no CLAUDE.md at all. Stale context doesn't just fail to help — it actively misdirects.

What we tried

CLAUDE.md files grow. A 60-line project contract that was accurate on day one becomes 300 lines of mixed signal by month six — old run commands, removed dependencies, renamed directories, workflows that no longer exist. Claude Code reads all of it every session. That means every stale line competes with the accurate ones for attention.

We ran a drift audit. First, we asked Claude Code to read the file and flag anything that didn't match the current repo:

Read CLAUDE.md and check every command, path, package name, and workflow reference against what's actually in this repo. List anything that looks outdated, removed, or no longer accurate.

It found eleven issues in a 280-line file. We hadn't run a deliberate review in four months.

The most common categories of drift we found:

• Removed packages still referenced in setup steps
• Run commands for scripts that had been renamed or deleted
• Directory paths for folders that had been reorganized
• Workflow descriptions for processes that no longer matched how the team worked
• Database and infrastructure references from an old stack that no longer existed

We deleted aggressively. When in doubt about a line, we removed it. You can always add guidance back. You cannot un-confuse a session that started with contradictory context.

What happened

The surprising thing was how much the file shrank. We went from 280 lines to 94 lines without losing anything the team actually relied on. Most of the deleted content was context that had been accurate once and then silently stopped being accurate. Nobody had deleted it because nobody was sure it was wrong — it just never came up until something broke.

After the audit, Claude Code's suggestions became noticeably cleaner. The "mostly right but occasionally wrong" pattern we'd been living with stopped. The cost we'd been paying turned out to be larger than we'd estimated.

We also discovered a useful secondary signal: sections of CLAUDE.md that nobody could explain confidently were the sections most likely to be stale. If a team member can't articulate why a rule exists, the rule either predates their knowledge or predates the current codebase. Either way, it deserves scrutiny.

What we learned

• Drift signal: Claude Code starts suggesting commands or patterns you haven't used in months — that's the file talking, not hallucination
• Ask Claude Code itself to audit CLAUDE.md: "What in this file no longer matches the repo?" is a surprisingly effective prompt that takes two minutes and catches things human reviewers miss
• One rule per line is easier to delete than paragraphs — dense prose makes drift invisible because the outdated part blends into the valid part
• Date-stamp major CLAUDE.md rewrites with a comment at the top; if a section predates a major dependency upgrade or infrastructure migration, it's a candidate for review

Next

• Day 13 — CLAUDE.md split patterns.