Skip to main content
← TurnTwoMISSION CONTROL0.4812655050996505

§5.5 · Code

CLAUDE.md — the file every Claude Code project pays for forever

This file gets read on every session. Keep it short, focused, and pruned.

CLAUDE.md (and ~/.claude/CLAUDE.md) is the file every Claude Code session reads as context before doing anything else. If it's 8,000 tokens and full of stale instructions, every single session pays that tax — and you usually never see the bill until your monthly Anthropic invoice arrives.

Three rules

  1. One source of truth, not five. Don't keep an outdated CLAUDE.md plus a new CLAUDE.local.md plus a half-finished notes.md referenced from inside both. Pick one, prune the rest.
  2. Keep it under 2,000 tokens. That's roughly 2–3 pages of prose. Sessions that don't need a particular section won't suffer; sessions that do can re-read the relevant bay docs on demand.
  3. State invariants, not history. "We use Next.js 16 App Router with Tailwind v3" is useful forever. "We tried Pages Router in May 2025 and abandoned it" is history — that goes in BUILD-LOG.md or DECISIONS.md, not in the file Claude reads on every session.

What belongs in CLAUDE.md

  • Project stack — language, framework, key libraries, build commands.
  • Critical conventions — naming patterns, file structure, never-do rules (e.g. "Never commit .env.local").
  • Authentication or permission patterns that an unaware Claude would get wrong.
  • External integrations with their connection patterns (API keys' env-var names, expected response shapes).

What does NOT belong

  • Session-by-session changelog entries (those go in BUILD-LOG.md).
  • Open bug lists or TODOs (those go in an issues file or your tracker).
  • Past architectural debates that are already resolved.
  • Anything Claude can read from package.json, tsconfig.json, or the file tree itself.

Audit cadence

Every 30 days, run the CLAUDE.md Auditor (web or /mc-claude-md-check inside Claude Code). It'll flag:

  • Sections over 400 tokens that could be sub-pages
  • Repeated content (two paragraphs saying the same thing)
  • Stale references (a file path that no longer exists)
  • Hedge / wordy phrasing

A clean CLAUDE.md pays for itself within a week of normal session activity.