How a Bloated CLAUDE.md Inflates Your Bill

Why does CLAUDE.md cost so much?

CLAUDE.md costs so much because it sits in the part of the prompt that gets re-sent on every single turn, and it sits at the front of the cache prefix — so a fat or unstable file gets re-billed on every request for the entire session, and a file that changes between sessions quietly invalidates prompt caching so you pay full freight instead of the ≈10% cache-read rate. It is the highest-leverage file in your repo for token cost, and almost nobody treats it that way. I spend my days building token tooling, and CLAUDE.md is the single most common own-goal I see. People obsess over whether to read a file with head or cat, then paste a 900-line house style guide into CLAUDE.md and wonder where the bill went. The big lever isn't hiding. It's the file you wrote on purpose. This is a spoke off How to reduce Claude Code token usage. If you want the full set of levers — file reads, output filtering, MCP pruning — start there. This piece goes deep on one of them, because it deserves its own treatment.

How does CLAUDE.md actually enter the context?

CLAUDE.md enters the context as part of the system/instruction layer that prefixes the conversation, and crucially it is not read once and forgotten — its content participates in the prefix that the model re-processes on every turn of the agentic loop. That matters because of how agentic coding works. On each step, the agent re-sends the accumulated history plus the standing instructions, and the model re-reads all of it to produce the next action. So anything pinned near the front — your CLAUDE.md included — is paid for again on every turn. A 4,000-token CLAUDE.md across a 40-turn session isn't 4,000 tokens. It's 4,000 tokens times forty turns of input processing, modulated by how well your cache holds. Which brings us to the part most people miss: the cache.

What does CLAUDE.md have to do with prompt caching?

CLAUDE.md is part of the cache prefix, so its stability is the difference between paying full input price and paying roughly a tenth of it. Prompt caching gives you a discounted cache-read rate — about 10% of the normal input price — but only on the longest identical prefix across requests. The moment your prefix changes, the cache breaks at that point and everything after it is re-billed at full input price. CLAUDE.md lives near the very front of that prefix. So two things follow, and they pull in the same direction:

A stable CLAUDE.md is a cache asset. If the file is byte-identical session to session, it stays inside the cached prefix and re-charges at the cache-read rate. Cheap.
An unstable CLAUDE.md is a cache wrecking ball. Edit it — add a "remember to run the migration" note, paste today's task list — and you've changed the prefix. The cache now misses at CLAUDE.md, and everything downstream of it re-bills at full price, not just the bytes you changed.

Put differently: a transient note you bury in CLAUDE.md doesn't cost you the note. It costs you the cache discount on the entire rest of the prompt. That is a genuinely bad trade, and it's invisible unless you're watching a savings dashboard. Let's make the trade concrete with real prices.

What's the actual dollar cost?

The actual cost depends on the model, the file size, the turn count, and your cache-hit rate — but a worked example makes the order of magnitude obvious. These are the published list prices at the time of writing (per million tokens, MTok):

Model	Input / MTok	Output / MTok	Cache read (≈10% of input)
Claude Opus 4.8	$5	$25	≈ $0.50
Claude Sonnet 4.6	$3	$15	≈ $0.30
Claude Haiku 4.5	$1	$5	≈ $0.10
GPT-5.5	$5	$30	≈ $0.50

Now take a CLAUDE.md of 4,000 tokens and a fairly ordinary 40-turn session on Sonnet 4.6, with the file present on every turn.

Fully cached (stable file, cache hits every turn): 4,000 tokens × 40 turns = 160,000 token-reads at the ≈$0.30/MTok cache rate ≈ $0.048. Rounding error. Ignore it.
Never cached (you edited the file mid-session, or it changed since last time, so it's full-price input): 160,000 tokens at $3/MTok ≈ $0.48. Ten times more, for the same file.

Forty-eight cents isn't going to bankrupt anyone. But it's per session, on one file, on the cheaper-than-Opus model — and the lesson scales. Run that on Opus 4.8 ($5/MTok input) across a team doing dozens of sessions a day, and the gap between "stable, cached CLAUDE.md" and "everyone edits it constantly" turns into real monthly money. The file is small; the multiplier is not. (Token-count any candidate CLAUDE.md with a token counter before you commit it.) And notice the asymmetry: the cost lives almost entirely on the input side. Trimming the model's output — "be concise" — does nothing here. CLAUDE.md is pure input, re-sent forever. That's why it's such a clean lever.

How big is too big?

Too big is the point where CLAUDE.md stops being durable rules and starts being a knowledge base. There's no magic line, but a useful heuristic: if you can't justify each section as "a convention that will still be true in three months," it doesn't belong there. The files that blow up tend to accumulate the same junk:

Pasted documentation. API references, framework docs, library changelogs. The agent can fetch these on demand; pinning them to every turn is the expensive way to be lazy.
Transient task state. "Currently migrating the auth module." "TODO: fix the flaky test." This is session-specific, it changes constantly, and every edit nukes your cache.
Long enumerations. A 60-line list of every directory in the repo, or every environment variable. The agent can discover structure with semantic code search; it does not need a hand-maintained map re-sent forty times.
Defensive over-instruction. Paragraph after paragraph of "always do X, never do Y, be careful about Z." Past a point this stops steering behavior and just inflates the prefix.

Compare that to what earns its place: build and test commands, the code-style rules your linter doesn't catch, architectural decisions ("we use server components by default"), and the two or three gotchas that genuinely bite newcomers. That's a tight file. It's also a stable one, which is the whole game.

What should I actually do about it?

Treat CLAUDE.md as a cache-stable contract, not a scratchpad. Concretely:

Audit length. Run your CLAUDE.md through a token counter. If it's north of a few thousand tokens, that number is your per-turn surcharge — go cut it.
Evict the transient. Anything that's true today but not next month leaves the file. Task state goes in your issue tracker or the chat itself, not the standing instructions.
Stop editing it mid-session. Every save during an active session breaks the cache for the rest of that session. Batch CLAUDE.md changes between sessions, where the cost is a single cold start instead of a per-turn penalty.
Push discovery to retrieval. Replace "here is the entire repo layout" with letting the agent find things on demand. That's what context engineering is really about — supplying the right context per turn instead of all context every turn.
Measure, don't guess. Watch your input-token and cache-hit numbers before and after. A leaner, stabler CLAUDE.md should show up as a higher cache-hit rate, immediately.

If you'd rather not police a markdown file by hand forever, this is exactly the kind of thing Tokenade handles automatically — it applies semantic retrieval, output filtering, skeleton compression and lazy MCP loading across Claude Code, Cursor, Codex, Copilot, Windsurf and the rest, and shows you the savings on a dashboard so the cache wins stop being invisible. It's source-available (MIT), free up to about 10M tokens a month, and $19.90/mo (excl. tax) for Pro with unlimited machines if you outgrow that. The CLAUDE.md discipline above is free regardless — the tooling just stops you from having to remember it.

Frequently asked questions

Does CLAUDE.md get re-read on every turn?

Effectively, yes. CLAUDE.md is loaded into the standing instruction layer, and that layer is part of the prefix the model re-processes on every turn of the loop. It isn't a one-time read whose cost you pay once — its tokens participate in every turn's input, which is exactly why size and stability both matter so much. The mitigating factor is prompt caching: if the prefix is identical turn to turn, those re-reads bill at roughly 10% of full input price.

Why does editing CLAUDE.md cost more than the edit itself?

Because caching keys on the longest identical prefix, and CLAUDE.md sits near the front of that prefix. When you change it, the cache stops matching at the point of the change, so not only the edited bytes but everything after them in the prompt re-bills at full input price for the rest of the session. The edit is cheap; the cache invalidation it triggers is the real cost. That's the case for batching CLAUDE.md changes between sessions rather than mid-flight.

Should I just delete CLAUDE.md to save tokens?

No — that throws away the signal with the noise. A good CLAUDE.md saves you tokens elsewhere: it stops the agent from rediscovering your build command, your test runner and your conventions through trial and error, each of which costs more than a tight instruction line. The goal is a lean, stable file, not an empty one. Keep the durable rules; evict the documentation dumps and the task-of-the-day notes.

Does this apply to Cursor, Copilot and other agents?

Yes. The mechanism is universal to any agent that pins standing instructions to a re-processed prefix and uses prefix caching — Cursor's rules files, Copilot's instructions, and similar. The names differ; the math doesn't. Any token-billed agent that re-reads its instruction layer every turn rewards a small, stable file and punishes a sprawling, churning one. See agentic coding for why the per-turn re-read is structural rather than incidental.

See also:

How to reduce Claude Code token usage — the pillar this article branches from.
Context engineering for AI coding agents — supplying the right context per turn, not all of it.
Prompt caching — the mechanic that makes a stable CLAUDE.md cheap.
AI coding agent token costs — the pricing math behind the examples above.