How to Prevent CLAUDE.md Rot: Treat Rules Like Code
After running Claude Code on production projects for 18 months, u/mm_cm_m_km identified the single most common failure point: the CLAUDE.md file rots. Not because Claude ignores it, but because developers keep adding rules without ever cleaning them up. The result is a bloated 500-line file that costs tokens every turn and drifts out of sync with the actual codebase.
1. CLAUDE.md as an Index, Not a Manual
Keep CLAUDE.md to 30–50 lines. It should act as a table of contents pointing to specific files for specific concerns — not a wall of every preference you have ever set. Claude rereads the file on every turn; short files are cheap, long files waste tokens and attention.
2. Every Section Answers One of Two Questions
- What behavior do you want? (the rule) — belongs in
CLAUDE.md. - Where do you find the current truth? (the source) — belongs as a fetchable URL or file path Claude can re-read at task time.
Mixing rules and sources is how files grow without bound. Keep the rule short, the source external.
3. Audit Before Merge, Not After
Rules silently drift as you rename things, refactor hooks, or drop features. The fix is not "be more careful" — it is a CI step. The author built a GitHub App called agentlint (agentlint.net) that audits the rules surface on every PR: contradictions across files, references to deleted paths, rules describing harness features your version does not support.
4. Delete More Than You Add
Almost every CLAUDE.md gains one new rule per week and deletes zero. After six months you have a Frankenstein. The discipline: for every new rule, find one to delete. This has kept the author's file under 100 lines.
The core pattern: treat your rules surface like code. Code has tests, review, and drift detection. Rules need the same.
📖 Read the full source: r/ClaudeAI
👀 See Also
Why Most Claude Pipeline Failures Trace Back to Prompts, Not Models — and How to Fix with Skills
A Reddit post argues that the root cause of pipeline failures in Claude workflows is treating prompts like skills. The fix: define input contracts, output schemas, and a learnings file — making a skill what you promote to v1.
OpenClaw API Budget Drain: Settings to Change Immediately
OpenClaw's default Heartbeat feature can drain API budgets by checking tasks every 30 minutes and loading full context files, memory, and chat history each time. The source recommends changing Active Hours, using cheaper base models, manually switching to premium models only when needed, and using /new to reset sessions.
Using the Dispatcher Pattern to Reduce Claude API Costs by 95%
A developer reduced Claude API costs from $800-$2,000/month to $215/month by implementing a dispatcher pattern that delegates heavy work to Claude Code CLI on a $200/month Max subscription, with API overhead costing only $5-15/month.
Reddit User Warns: When Using Claude for Complex Projects, Tackle the Hardest Part First
A developer on r/ClaudeAI reports that letting the AI plan incrementally for a complex document editor led to 'complexity soup' and failures. The user advises forcing the model to solve the most complicated use case first, as its performance degrades with more context.