Trim Your CLAUDE.md Before It Taxes Every Session

Your CLAUDE.md is the most expensive file in your repo. Not because it is long — because it is loaded into every single Claude Code session, then re-sent on every turn of that session. A rule you wrote once and forgot about is a rule you pay for thousands of times.

Why a few stray lines matter

Most teams treat CLAUDE.md like a README: write it once, append forever, never prune. But unlike a README, nobody reads it twice — the model does, constantly. The cost of bloat is not the one-time write; it is the per-turn input tokens, multiplied across every session every developer runs.

The failure modes are predictable, and they accumulate quietly:

• Redundant rules — the same constraint stated twice under different headings.
• Conflicts — one section says “use pnpm”, another says “install with npm”. The model has to guess, and it guesses differently each time.
• Stale pins — version notes and “experimental” caveats that were true a year ago and now just mislead.
• Vague guidance — “write clean code” costs tokens and changes nothing. (Deliberate safety constraints are excluded — those earn their place.)
• Missing sections — the commands to run before commit, the deploy steps, the patterns the model keeps getting wrong.

What the auditor does

The CLAUDE.md Auditor reads your file, grades it A–F, and returns concrete cuts — not “this could be tighter” but “merge these two rules, drop this pin, resolve this conflict.” It also estimates the per-session tokens you would reclaim, so the payoff is a number, not a vibe. A rule-based heuristic pass runs free on its own; the deeper graded audit runs on your own key.

See a worked example below ↓

When to run it

Run it whenever CLAUDE.md crosses a screen or two of scrolling, after any big refactor that retired a library or a workflow, and before you onboard anyone new to the repo — a clean instruction file is the cheapest onboarding you will ever do. Cutting 150–200 tokens off a file that loads every turn pays for itself within a single working session.

Trim it once, save on every turn

You can run the auditor on your own CLAUDE.md right now — the heuristic pass is free. And if you would rather have this kind of instrumentation wired into your real workflow rather than run by hand, tell us what you are building and we will scope it.