A practical guide to preventing CLAUDE.md bloat by treating it as a steering document synced to an external knowledge system.

The Problem

📝Claude Code's CLAUDE.md file loads into every session's context window. Every line costs tokens on every conversation, whether relevant or not. Over time, CLAUDE.md accumulates architecture tables, QA logs, data models, and implementation status — reference material that belongs elsewhere. A 400-line CLAUDE.md burns ~12,000 tokens per session on content that most sessions never need.

Boris Cherny, who leads Claude Code at 📝Anthropic, benchmarks his team's files at ~4,000 tokens (~100 lines). Beyond that, instruction adherence degrades as rules compete with noise for attention.

The Reframe

CLAUDE.md is a steering document, not a reference document. It tells agents HOW to behave and WHERE to find things. It does not hold the things themselves.

Reference material — architecture, data models, auth flows, deployment procedures — belongs in a knowledge system the agent can query on demand. I use 📝MythOS with its MCP integration, but any system with an API works: Notion, Confluence, a set of markdown files the agent can read.

The Five-Line Heuristic

For every section or line in a CLAUDE.md, run these questions in order:

If a line survives all five questions, it stays. Most won't.

The Canonical Structure

After applying the heuristic, every CLAUDE.md follows four sections:

About — one paragraph. What the project is, what stack, what matters.

Rules — branching constraints, safety rails, code style not enforced by linters. Only content that steers behavior every session.

Context — one-liner pointers to external knowledge. In my case, these are MythOS memo IDs that agents load via MCP when the conversation narrows onto a specific topic:

- Project context: `read_memo(brianswichkow-a6447c)`
- Feature specs: `search_memos(tags: "mythos-v3,feature-context")`

Dev Environment — how to run the project (2-3 lines). Active gotchas only.

Target: 30-80 lines per project. Global even leaner.

The Sync

Two directions keep the local file and MythOS in lockstep:

MythOS → local via cron — edit on any device, file updates everywhere
Local → MythOS via agent convention — a rule in CLAUDE.md tells the agent to push any edit back to MythOS via MCP

Conflicts are rare because the files are small and edits are infrequent.

Try It Yourself

Give Claude Code this prompt to cultivate your own CLAUDE.md:

Read my CLAUDE.md file. For every section, apply these five questions in order:
1. Does this steer behavior every session? → KEEP
2. Is this a pointer to where context lives? → KEEP as one-liner
3. Can an agent derive this by reading the code? → DELETE
4. Is this historical state? → DELETE or move to external storage
5. Is this duplicated elsewhere? → DELETE

Triage into: KEEP, CONDENSE (rewrite shorter), GRADUATE (move to
external docs), DELETE. Show me the triage before making changes.
Target: 30-80 lines total, four sections: About, Rules, Context,
Dev Environment.

The Results

My largest CLAUDE.md went from 413 lines (~12k tokens per session) to ~60 lines (~2k tokens). Reference material graduated to MythOS project context memos, where it loads on demand only when relevant. QA logs and implementation history were deleted — they live in git. Architecture tables were deleted — they're derivable from the code.

The agent now spends its context budget on the conversation, not on reading about auth flows it was never going to touch this session.

Closing

The irony is that a bigger CLAUDE.md feels like more control — more rules, more context, more guardrails. But past a threshold, it's the opposite. The agent has so much static context that it starts ignoring the rules you actually care about because they're buried in architecture tables. Lean CLAUDE.md with on-demand MCP loading gives you both: tight behavioral control in the file, deep reference knowledge via the MCP connection. The discipline is in what you remove, not what you add.