CLAUDE.md Edits Break Prompt Caching: A 10x Worked Example

CLAUDE.md sits at the front of your prompt cache prefix, so one mid-session edit re-bills everything after it at full input price.

That mechanism is the subject of a new guide from a developer who builds token tooling, and who calls a bloated CLAUDE.md "the single most common own-goal I see." The argument is worth following even if you never read another token-optimization post, because the cost is invisible in the place most teams look.

Why the file is re-sent every turn

CLAUDE.md enters the context as part of the instruction layer that prefixes the conversation, and the agentic loop re-processes that prefix on every turn. The guide's framing: a 4,000-token CLAUDE.md across a 40-turn session is not 4,000 tokens, it is 4,000 tokens times forty turns of input processing, modulated by how well the cache holds.

Caching is the whole game. By the guide's account, prompt caching gives a discounted cache-read rate of about 10% of normal input price, but only on the longest identical prefix across requests — and the moment the prefix changes, the cache breaks at that point and everything after it re-bills at full input price. Because CLAUDE.md sits near the very front, the guide's conclusion is blunt: a transient note you bury in it does not cost you the note, it costs you the cache discount on the entire rest of the prompt.

The worked example

The guide quotes these as published list prices at the time of writing, per million tokens. Treat them as the author's figures, not verified current pricing:

Model	Input / MTok	Output / MTok	Cache read
Claude Opus 5	$5	$25	≈ $0.50
Claude Opus 4.8	$5	$25	≈ $0.50
Claude Sonnet 5	$2	$10	≈ $0.20
Claude Haiku 4.5	$1	$5	≈ $0.10
GPT-5.5	$5	$30	≈ $0.50

Run a 4,000-token file across a 40-turn Sonnet 5 session and you get 160,000 token-reads. Fully cached, at the cache rate, the guide computes roughly $0.032. Never cached — you edited the file mid-session — the same 160,000 tokens at $2/MTok come to about $0.32. Ten times more for the same file.

Thirty-two cents is not a crisis, and the guide says so plainly. Its scaling claim is the part to weigh: per session, on one file, on a cheaper-than-Opus model, multiplied across a team running dozens of sessions a day. That is the author's extrapolation rather than a measurement, so size it against your own session count before acting on it.

What to actually cut

The guide's heuristic for "too big" is the point where the file stops being durable rules and becomes a knowledge base: if you cannot justify a section as a convention that will still be true in three months, it does not belong. The named offenders are pasted documentation, transient task state, long enumerations of directories or environment variables, and defensive over-instruction. What earns its place: build and test commands, style rules the linter misses, architectural decisions, and the two or three gotchas that bite newcomers.

Note the asymmetry the guide flags — the cost is almost entirely input-side, so telling the model to be concise does nothing for it.

The cheapest change is a scheduling one: stop editing the file mid-session and batch changes between sessions, so you pay one cold start instead of a per-turn penalty. If you want to check any of this rather than take it on faith, token-count your own CLAUDE.md and compare a session's cache-read against full-price input before and after a trim — the guide's numbers are arithmetic from list prices, not instrumented from a bill.