CLAUDE.md files accumulate rules over time. Some become outdated as the codebase changes. Others contradict each other. Dead rules waste context tokens and can actively confuse Claude.
Common Problems
- Stale references: “Use the helper in
src/utils/old-thing.ts” (file was deleted months ago) - Contradictions: “Always use Jest” in one section, “We use Vitest” in another
- Redundancy: same instruction phrased three different ways
- Over-specificity: rules about files or patterns that no longer exist
Ask Claude to Audit
Read my CLAUDE.md and .claude/rules/ directory. For each rule:
1. Check if the referenced files/patterns still exist
2. Flag any contradictions between rules
3. Identify rules that duplicate each other
4. Suggest which rules can be removed or mergedAutomate It
The claude-rules-doctor tool scans your CLAUDE.md and flags dead references automatically.
How Often
Audit your CLAUDE.md:
- After major refactors that change file structure
- When switching frameworks or test runners
- Monthly, as part of project hygiene
- Whenever Claude does something unexpected (it might be following a stale rule)