Mastering prompt caching, from cache miss to an 80 percent hit rate in 10 steps

Cache hits are the cheapest token you will ever pay for. A cache read costs roughly 10 percent of the normal price, a cache write 25 percent more. If you keep a session open for two hours and the cache never fires, you burn ten times as much for the same system prompt. That is the most common hidden cost driver in Claude Code. In this playbook I go through how I push caching to an 80 percent hit rate in the daily driver, in my own scripts and in MCP servers. Little theory, a lot you can copy straight away.

1. Understand in one sentence what caching does

You mark a spot in your prompt with cache_control. Anthropic stores everything up to that spot (tools, system, messages, in that order) for 5 minutes. On the next request with the same prefix you get that chunk back as a cache read instead of having it processed again. That is all there is to it.

What a lot of people miss is that the cache breakpoint expires after 5 minutes but gets extended on every hit. As long as you fire again within 5 minutes, the cache stays warm and keeps costing nothing. Long breaks can be covered with the 1 hour cache, more on that shortly.

2. Measure the cache, otherwise you are optimizing blind

Every Anthropic API response returns four token counters. input_tokens is everything that was processed fresh. cache_creation_input_tokens is what got written into the cache this time. cache_read_input_tokens is what was pulled out of the cache. output_tokens is the answer.

In Claude Code, /usage shows this aggregated per session. What you have to keep an eye on is the ratio of cache_read to input_tokens. If that is above 4 to 1, you are running well. If input_tokens is in the thousands every time and cache_read stays tiny, you have a cache buster sitting somewhere, usually a dynamic date or a counter variable that leaked into the system prompt.

For your own scripts, log those four numbers per request. A small table in Postgres or a JSONL file is enough. Without that measurement you are optimizing on guesses.

3. Start with automatic caching, not with explicit breakpoints

Anthropic recommends this at the top of the docs and so do I. Set cache_control exactly once on the last cacheable block (so before the user message that changes every time). Example in Python,

response = client.messages.create(
    model="claude-sonnet-4-5",
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": user_message}]
)

That covers 80 percent of cases. Only once you have clear layers that change at different rates (tools rarely, system moderately, conversation often) do you move to explicit breakpoints.

4. Apply the stable prefix trick, everything stable goes to the front

The cache only works if the prefix is byte for byte identical. A single changed character at the start invalidates everything behind it. So sort your prompt like this,

1. Tools first, they almost never change
2. Then the big static system prompt
3. Then project specific context (CLAUDE.md, loaded files)
4. And only then the changing user message at the end

Classic mistake, a timestamp or a session ID in the system prompt. That kills every cache. If you need something like that, put it at the end in the user message, not in the system block.

5. Use four breakpoints cleverly, not all at once

You have up to four cache_control markers per request. The sensible split,

• Breakpoint 1 after the tools
• Breakpoint 2 after the static system prompt
• Breakpoint 3 after the loaded project context
• Breakpoint 4 after the last few conversation turns (rolling)

Every breakpoint costs a one-off cache write premium (25 percent extra). If you only have one layer that is genuinely stable, you do not need four markers. Rule of thumb, one good breakpoint beats four half-baked ones.

6. CLAUDE.md is your biggest cache candidate

Claude Code loads CLAUDE.md into the context at the start of every session. If you keep constant instructions there (coding style, test rules, forbidden commands), that gets sent along with every single request. A cache hit reduces the cost dramatically.

What you have to avoid is dynamic data in CLAUDE.md. No Today is 2026-05-26, no status counter, no "the last session was ...". That can be solved elegantly with a sub-skill, pull the dynamic date in as a slash command or tool output instead of writing it statically into the file.

7. Keep tool definitions lean, they sit in the cache prefix

MCP tool definitions land in tools and therefore right at the front. An 80 tool MCP server pumps 15,000 tokens into every single request, to be cached again each time. That is fine as long as you need those tools permanently.

But if you only need them rarely, disable the server in .mcp.json and switch it on situationally. Or use the pickMcp pattern when you are building your own agent, so each agent only gets the tools it actually needs. The playbook tool-sprawl-vermeiden goes into that more deeply.

8. The 1 hour cache for long breaks, but deliberately

On top of the 5 minute default, Anthropic offers a 1 hour cache. You set it with,

{"type": "ephemeral", "ttl": "1h"}

It costs more to write and pays off when you have sessions where you are away for a while (meeting, lunch). My pattern, the 1h cache only for the truly stable layer (tools plus global system prompt). The 5 minute default for everything else. If I know I will be back at the laptop in 90 minutes, I save myself the whole system prompt rebuild.

If you start every session fresh and are always in the flow, leave the 1h cache out. The 25 percent premium on the write does not pay off when the cache is being kept permanently warm anyway.

9. Use cache diagnostics when the hit fails to appear

Anthropic has cache diagnostics in beta. You send two consecutive requests and the API tells you at which point the prefix diverged. Worth gold when you do not understand why the cache is not firing.

You switch it on with the beta header anthropic-beta: prompt-caching-diagnostics-2025-XX-XX (look up the exact version number in the current docs, it changes). In the response you then get an extra field with the divergence point.

If diagnostics shows that the divergence already sits at token 50, you very likely have a dynamic header or a timestamp in the prefix. If it only diverges at token 8000, that is probably where your last tool output lives.

10. My daily driver pattern, one concrete routine

This is what my Claude Code session looks like, optimized for caching.

At the start I hit /usage to see where I stand. CLAUDE.md is static (no date, no counters). My MCP setup has exactly the five servers I need for this session, the rest is disabled.

The first request runs, cache_creation_input_tokens is high (around 20,000), cache_read is zero. Normal, the first request writes the cache. Second request, cache_read jumps to 20,000, input_tokens is only the few hundred of new user input. That is the point where I know everything is running.

After a 90 minute break comes my cache reset. Instead of processing 20,000 tokens again I use /resume and a 1h breakpoint on the tools layer. The cache stays warm and getting back in costs about half.

Change of topic, I hit /clear and go into a fresh session. The cache gets discarded, but that saves more over the next hour than the one-off rebuild costs. A polluted cache full of irrelevant context is more expensive than a fresh one.

What comes next

Once caching is in place, the next levers are in claude-code-cost-controls-für-daily-driver (model routing, /compact, spend limits) and context-window-managen-claude-code. If you build your own scripts, pour the cache logging pattern into a Postgres table and evaluate after two weeks which prefixes really deliver hits. That is often where the last 20 percent of optimization sits.

Source

• platform.claude.com/docs/en/build-with-claude/prompt-caching (official, retrieved 2026-05-26)
• platform.claude.com/docs/de/build-with-claude/prompt-caching (DE mirror, retrieved 2026-05-26)
• code.claude.com/docs/en/costs (official, for the /usage mechanics, retrieved 2026-04-27)