CLAUDE.md is 📝Claude Code's project-level instruction file — a 📝Markdown document that loads into every session's context window and steers agent behavior for that project. It lives at the root of a repository (or globally at ~/.claude/CLAUDE.md) and defines rules, constraints, and pointers that the agent follows across all conversations in that scope.
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 docs, data models, implementation status, QA logs — belongs in external systems (like 📝MythOS) and loads on demand via 📝Model Context Protocol (MCP). When CLAUDE.md accumulates reference content, it bloats the context window, dilutes instruction adherence, and burns tokens on every session — including sessions that never need that context.
📝Boris Cherny, who leads Claude Code at 📝Anthropic, benchmarks his team's CLAUDE.md files at ~4,000 tokens (~100-120 lines) with memory files at 76 tokens. Beyond that, the file is doing too much.
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.
Canonical Structure
Every CLAUDE.md, regardless of project, should follow this skeleton:
- About — one paragraph. What the project is, what stack, what matters.
- Rules — branching/deployment constraints, safety rails ("never X", "always confirm before Y"), code style (only non-obvious conventions not enforced by linters).
- Context — pointers to where reference material lives. MythOS memos, project context, external docs. One-liners, not inline content.
- Dev Environment — how to run the project (2-3 lines). Active gotchas only, not historical.
Target: 30-80 lines per project (~2-4k tokens). Global even leaner.
Key Facts
- Location: repo root (
CLAUDE.md) or global (~/.claude/CLAUDE.md) - Loaded: automatically, every session, full content injected into context window
- Token cost: every line costs tokens on every session, whether relevant or not
- Hierarchy: global → project → subdirectory (all three load if present)
- Target size: 30-80 lines per project, global even leaner
- Part of: 📝Claude Code Hooks and Skills extensibility ecosystem
Why It Matters
CLAUDE.md is the highest-leverage file in any Claude Code project. Every token in it competes with conversation content for context window space. A lean, well-curated CLAUDE.md means better instruction adherence, lower token burn, and agents that load detailed context on demand rather than carrying everything everywhere. A bloated one means silent quality degradation — the agent technically has access to the rules but they're drowned out by architecture tables nobody asked about this session.