Add prompt caching to an existing Claude app without rewriting it

TL;DR

Check the minimum cacheable length in the docs: short prefixes below it will not cache at all. Prompt caching cuts cost and latency by reusing the cached prefix of your prompt. Measure the repeatable prefix first. Enable caching on one call site, confirm the hit rate, then move to the next.

When to use

You are seeing this: Roll it out onto an existing app in this order. Use this skill when you run into "Add prompt caching to an existing Claude app without rewriting it".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Prompt caching cuts cost and latency by reusing the cached prefix of your prompt. Roll it out onto an existing app in this order.

1. Measure the repeatable prefix first. Find the part of your requests that is identical across calls: system instructions, few-shot examples, retrieved documents. If nothing repeats, caching buys you nothing, stop here.
2. Choose automatic or explicit. Automatic caching: add a single cachecontrol field at the top level of the request and the system caches the last cacheable block, moving the breakpoint forward as the conversation grows. Best for multi-turn chats with growing history. Explicit breakpoints: place cachecontrol directly on individual content blocks for fine-grained control. Start with automatic; switch to explicit only if you need to cache a middle section and not the tail.
3. Reorder so stable content comes first. Put the unchanging blocks (system instructions, tool definitions, documents) at the front of the request and the variable content (the latest user message) last. Any change to an early block invalidates everything after it, so one dynamic block placed first kills the whole cache.
4. Pick the TTL that matches your rhythm. cache_control supports a 5-minute or 1-hour TTL. Multi-turn chats inside an hour-long session want the 1-hour TTL; bursty background jobs want 5 minutes. Check the minimum cacheable length in the docs: short prefixes below it will not cache at all.
5. Verify with cache usage fields. On the response, read the usage object: cachecreationinputtokens and cachereadinputtokens tell you whether the cache actually hit. If read tokens stay zero, your prefix is not stable, go back to step 3 and diff two requests byte by byte.
6. Roll out per endpoint, not all at once. Enable caching on one call site, confirm the hit rate, then move to the next. Cache behavior interacts with temperature and tool definitions, so re-run your evals after enabling it.

Claims verified against Anthropic's official docs (platform.claude.com) on 2026-09-26. Evidence URLs in public_references.