"A 5,000-token CLAUDE.md is a 5,000-token tax per turn." Half of that is true.

There is a sentence circulating in prompt-optimisation advice, and it is specific enough to be worth checking: “It injects into every request as system context. A 5,000-token CLAUDE.md is a 5,000-token tax per turn.”

It is in no vendor document. It is the reason people are told to keep CLAUDE.md under 200 lines. And it is two claims wearing one coat:

• the file is re-sent on every turn, which is a claim about context
• that costs you 5,000 tokens’ worth every turn, which is a claim about money

Those come apart, because a re-sent prefix that is cached bills at a fraction of a fresh one. So I measured them separately.

The measurement

One session, four turns, resumed with --resume so it is genuinely one conversation rather than four cold starts. Two arms differing only by whether a CLAUDE.md exists: 18,000 bytes of ordinary engineering prose, sized to land near the 5,000 tokens the claim names. Four rounds. Every turn asks for a different marker word and the reply has to contain it, so a turn that silently did nothing gets scored as failed rather than as a cheap turn.

The file measured 4,967 tokens.

Turn	No CLAUDE.md	With CLAUDE.md	Context added	Cost added
1	22,287	27,254	+4,967	+$0.04966
2	21,772	26,739	+4,967	+$0.04967
3	21,793	26,760	+4,967	+$0.00248
4	21,813	26,780	+4,967	+$0.00248

The context claim is true, and it is exactly true

4,967 tokens on turn one. 4,967 on turn four. Not approximately: the same integer on all four turns, in all four rounds, with zero spread in either arm. The file does not decay, does not get summarised, and does not get dropped once the model has “seen” it. Whatever is in your CLAUDE.md is in front of the model on every single turn.

If your concern is the context window, the advice is right and you can stop reading. A 5,000-token CLAUDE.md costs you 5,000 tokens of window, permanently, for the whole session.

The cost claim is true for about two turns

Then the same 4,967 tokens get 20 times cheaper, and the reason is visible in the billing split:

Turn	Cache write	Cache read
1	+4,967	0
2	+4,967	0
3	0	+4,967
4	0	+4,967

The tokens do not go anywhere. They move billing tier. On turns one and two the file is being written into the cache; from turn three it is being read out of it, and reads are a twentieth of the price of a one-hour write.

The nice part is that I did not have to assume any of that. Dividing the measured cost difference by the measured token difference gives $10.00 per Mtok on turns one and two and $0.50 per Mtok on turns three and four, which lands exactly on the published rates for one-hour cache writes and cache reads without either number being fed in. The measurement recovers the price list rather than being told it.

Why two turns and not one

This is the bit I would most expect to get wrong by reasoning, so I am not going to reason about it. It is cited, not inferred. This site previously measured that the first --resume always writes a new cache breakpoint over the grown conversation, identically at 5-second, 60-second and 480-second gaps, in cache-ttl.json. Fifteen scored runs cover the 60 and 480-second gaps; the 5-second figure is a single diagnostic run, published there as one.

This run reproduces that independently, and in the one place that owes nothing to the treatment: the arm with no CLAUDE.md at all writes 5,759 tokens to cache on turn two and 21 on turn three. The two-turn shape is a property of the session, not of the file. Your CLAUDE.md is just along for the ride.

What this actually means for your CLAUDE.md

The cost is front-loaded, so short sessions are where a big CLAUDE.md hurts. Over the four turns here, this file cost $0.1043 in total and 95.2% of that was spent before turn three. Ten further turns would have added 2.5 cents between them. If you open a session, ask one question and close it, you pay the expensive version every time; if you work in long sessions, you pay it once and then it is nearly free.

Trimming CLAUDE.md is a context-window optimisation much more than a cost optimisation. Halving this file would save roughly 2,483 tokens of window on every turn, which is real and permanent. Roughly, because only one file size was measured here and that figure assumes the cost is linear in bytes; this site’s own skills model carries a fixed per-item term that does not halve, so treat it as an estimate rather than a second measurement. What it saves in money is 2.5 cents on each of the first two turns and an eighth of a cent per turn after that. On a 20-turn session that is 7 cents. Optimise the file because you want the room back, not because of the bill.

“Keep it under 200 lines” is not what any of this establishes. The measurement says a file costs its own size in window, every turn, forever. Whether a shorter file makes the model behave better is a separate question about attention, and this site has already measured it: in claude-md-rule-count.json, a target rule at the top of the file and another at the bottom were both obeyed in every run at every count from 2 rules to 500. Compliance did not decay with length there at all. So the length advice is well founded on window and, on the evidence this site has, not yet founded on obedience.

What this does not settle

One file shape. Ordinary English prose. This site has measured the byte-to-token rate moving between 0.26 and 0.37 depending on content, so a CLAUDE.md full of tables, code blocks or checklists will not cost the same per byte. This one came out at 0.276.

Four turns. Nothing here says what happens on turn 20, after a compaction, or after an idle gap long enough for the cache to expire. The cache TTL work is separate and linked above.

Trivial turns. Every turn is a two-word reply. A turn doing real work adds its own tokens on top. What is isolated here is the marginal contribution of the CLAUDE.md, not a session’s total cost.

Nothing about behaviour. This is a cost measurement. It does not tell you whether the model follows a longer file better or worse.

The per-Mtok rates are derived, not quoted. The $10.00 and $0.50 figures above are the measured cost difference divided by the measured token difference. That they land on the published prices is a check on the measurement, and it is worth exactly that: it is not a price list, it is not used to compute anything else here, and it should not be read as one.

One machine, one model. Opus on Claude Code 2.1.233, project scope, --setting-sources project asserted onto the command line so this machine’s own configuration could not leak into either arm.

Controls

Same session, proved. The session id returned by turn one is fed to --resume, asserted onto the command line, and every turn’s returned id is published, so you can check all four turns really were one conversation rather than four.

Arrival, per turn. Each turn demands a distinct marker (ALPHA, BRAVO, CHARLIE, DELTA) and the reply must contain it. All 32 arrived. A turn that quietly failed would otherwise look like a very cheap turn, which is the exact way this measurement could have flattered itself.

Fixture proved both ways. The CLAUDE.md byte count is read back off disk on every run of the treatment arm, and the control arm asserts the file is absent. Both sides of the treatment are measured rather than assumed.

Billing split kept separate. Input, cache creation and cache read are never summed into one number. Summing them is precisely what makes the two claims in that circulating sentence look like one claim.

Arithmetic identities asserted in code. The build fails rather than publishes if any turn’s context is not input plus cache-creation plus cache-read, if the context difference is not identical across turns, or if the two arms overlap on cost.

One estimator, with its one exception disclosed. Median across rounds per cell, and the assembler refuses to build if a median is a value no round produced. That check is waived for cost alone, because cost is a continuous float and an even round count interpolates it by construction. That is a real weakening, so: every cost cell publishes all four rounds, and the headline does not lean on the estimator anyway, because the arms are fully disjoint on every turn.

Cross-version. The same fixture on 2.1.232 measured 4,969 tokens against 4,967 now, a difference of 2.

No exclusions. All 32 runs are scored.

Every run is published in claudemd-per-turn-2-1-233.json.