Prompt Caching Patterns for Claude Agents That Scale

Once you've gotten a single agent to cache its prompt, the next question is how to make caching a habit your whole codebase enforces, not a fragile thing one engineer tuned by hand. The difference between an agent that caches by accident and one that caches by design is a handful of reusable patterns — ways of structuring prompts, tools, and context so that cacheability is the default and breaking it requires effort. This post collects the patterns that hold up as an agentic system grows past a toy and into something teams depend on every day.

Pattern: the prompt is an append-only log

The foundational pattern is treating context as an immutable, append-only log. Earlier turns are never edited, reordered, or deleted in place. New information goes at the end, full stop. This sounds restrictive until you internalize why: cache invalidation cascades forward from the first changed byte, so any in-place edit to history detonates the cache for everything after it. By making append-only a hard rule in your code — for instance, a context object that only exposes an append method and no mutation — you make the cache-safe path the only path.

When you genuinely must shrink a bloated transcript, you don't rewrite it; you summarize the old portion into a fresh block and append that, then continue from the new tail. You eat exactly one cache rewrite, deliberately, and gain a smaller ongoing prefix. The pattern isn't "never compact" — it's "compact by appending a summary, never by editing the past."

Pattern: deterministic prompt assembly

The second pattern is making prompt construction a pure function: same inputs, identical output bytes, every time. Caches match on exact byte prefixes, so any nondeterminism is a silent cache killer. Concretely, that means serializing tool schemas in a fixed, sorted order; freezing dynamic values like timestamps out of the stable region; and using one canonical serializer so the same object never produces two different JSON strings. If two code paths can build "the same" prompt and emit different bytes, you have a latent cache miss waiting to happen.

flowchart TD
  A["Session state"] --> B["Pure assemble() function"]
  B --> C["Layer 1: system prompt (frozen)"]
  C --> D["Layer 2: tools sorted & canonically serialized"]
  D --> E["Layer 3: static project context"]
  E --> F["Layer 4: append-only transcript tail"]
  F --> G{"Bytes identical to last turn's prefix?"}
  G -->|Yes| H["Cache hit on layers 1-3"]
  G -->|No| I["Locate nondeterministic field & freeze it"]

Pattern: order content by volatility

A reusable layout beats ad-hoc placement. Order every prompt by how often each piece changes: invariant system rules at the very top, then tool and MCP schemas, then durable project facts, then the live conversation at the bottom. This volatility-ordering is itself the pattern — encode it as the canonical structure of your prompt builder so no one has to remember it. The payoff is that your longest, most expensive content is also your most stable, so it caches once and rides for free across the whole session.

The anti-pattern to watch for is "helpful" context injected high up — a per-turn summary of recent activity dropped into the system prompt, say. It feels efficient and it quietly invalidates the cache on every turn. If something changes per turn, it belongs in the tail, near the latest message, where churn is already expected and already paid for.

Pattern: cache-stable tool outputs

Tools are part of the context too, so their outputs need the same discipline. A tool that returns deterministic, content-stable results lets those results become durable cached blocks as the conversation moves forward. A tool that stamps every output with a fresh request ID, a wall-clock time, or a randomly ordered result set poisons the prefix downstream, because next turn's prefix now contains a value that will never recur. The pattern is to design tool responses to be content-addressable: same logical input, same output bytes. Where a timestamp is truly needed, isolate it so it sits in the volatile tail rather than baked into a block that should have been cacheable.

This extends to retrieval. If you inject retrieved documents into context, fetch them in a stable order and don't reshuffle them between turns. A retrieval layer that returns the same documents in a different order each call looks harmless but breaks the cache for everything after the injection point.

Pattern: layered breakpoints for independent invalidation

Spend your breakpoint budget to let layers fail independently. Put one breakpoint after the system prompt, one after the tool catalog, one after static project context. Now, connecting a new MCP server mid-session rewrites only the tool layer and below — the system layer stays warm. Without layered breakpoints, that single event rewrites your entire prefix. The pattern is to map breakpoints onto the natural seams where independent change happens, so the blast radius of any one change is as small as possible.

Think of each breakpoint as defining a cache segment with its own lifetime. A change inside segment two invalidates segments two and three but spares segment one. Designing those segments well is most of the art: you want the biggest, most stable content protected behind the earliest, most durable breakpoint.

Pattern: measure, then guard against regressions

The final pattern is operational and cultural. Log cache-read versus cache-write tokens on every turn and surface the read ratio as a first-class metric. Then guard it: a sudden drop in hit rate after a deploy almost always means someone introduced nondeterminism or a high-up per-turn injection. Treat that dip like a failing test. Some teams go further and add an assertion in CI that the prompt builder produces byte-identical output for identical state across two calls — a cheap check that catches the entire class of "oops, the cache stopped hitting" bugs before they ship.

Taken together, these patterns turn caching from a delicate hand-tuned optimization into a structural property of your codebase. Append-only logs, deterministic assembly, volatility ordering, cache-stable tools, layered breakpoints, and a guarded hit-rate metric reinforce each other. Get them in place and your agents cache because the code can't easily do otherwise — which is exactly where you want to be.

Frequently asked questions

What's the single most important caching pattern?

Append-only context. Because invalidation cascades forward from the first changed byte, never editing or reordering earlier turns protects the entire downstream cache. If you adopt only one pattern, make your context object append-only by construction.

How do I keep tool outputs from breaking the cache?

Make them content-addressable: the same logical input should yield the same output bytes. Keep timestamps, random IDs, and unordered result sets out of cacheable blocks, or isolate them into the volatile tail where per-turn churn is already expected.

Can I enforce caching discipline automatically?

Yes. Make prompt assembly a pure function and add a CI assertion that identical session state yields byte-identical output. Surface the cache-read ratio as a metric and alert on regressions. Those two guards catch most nondeterminism before it reaches production.

Does compacting the transcript ruin caching?

Only momentarily, and only if you do it right. Summarize the old portion into a new block appended at the end rather than editing history in place. You pay exactly one rewrite and then enjoy a smaller, cheaper ongoing prefix.

Bringing agentic AI to your phone lines

The same patterns that keep Claude agents cache-friendly keep CallSphere's voice and chat agents responsive — stable context, append-only conversation, tools called mid-call, and bookings made 24/7. Try it at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.