How do you design an application's prompts so prompt caching actually works?

Put everything that stays the same at the start of the request and everything that changes at the end, mark the end of the stable part as a cache breakpoint, and make sure nothing inside that stable part varies between requests (timestamps, user names, shuffled tool lists). Then check the cache-read tokens in the usage data to confirm it is working.

How the cache works (Claude API)

• The cache covers the whole prefix of the request, in the order tools → system → messages, up to the block marked with cache_control.
• A later request reuses the cache only if its prefix is identical. Anthropic's documentation says a change at one level invalidates that level and everything after it: change a tool definition and nothing is reused.
• There is a minimum cacheable length, which depends on the model: for example 512 tokens on the newest Claude models and 1,024 or more on several older ones.
• Entries live 5 minutes by default, refreshed each time they are read; a 1-hour lifetime costs more to write.
• Reads cost about a tenth of normal input on most models; writes cost more than normal input, so caching pays once a prefix is reused.

Design rules

1. Order: tools, then the system prompt, then long shared documents, then the conversation, then the new user message.
2. Keep the prefix byte-identical. No "Today is 2026-10-16 14:32" at the top; put the date near the end, or at day granularity. Keep tool order fixed. Avoid per-user text in the system prompt.
3. Multi-turn chat: move the breakpoint to the latest turn each time, so each request reuses all earlier turns.
4. Several breakpoints when parts change at different rates: tools and system (rarely change), a document (changes per session), the conversation (grows every turn).
5. Match the lifetime to traffic. If requests for the same prefix come less often than every 5 minutes, the default cache expires between them; consider the 1-hour option or batching related requests.

Check it

Each response reports cache-creation and cache-read input tokens. If cache reads stay at zero, something in the prefix is changing. Compare two raw requests to find it. Track the cache-hit share as a production metric.

Where it pays most

• Agents, which resend tools and a growing history every turn.
• Question answering over the same long document.
• Long system prompts with many examples.

Common mistakes: a timestamp or request id in the system prompt, tools generated in a different order each time, and a prefix shorter than the model's minimum, which silently is not cached.

Summary: "Stable first, variable last, nothing random in the prefix, and I check the cache-read numbers instead of assuming."