Prefix Stability

Build every request so that its cached prefix is byte-identical to the previous one. Prompt Caching is the provider-side mechanism; Prefix Stability is the caller-side discipline that decides whether the mechanism ever produces a hit. A cache can be switched on and still hit 0% of the time if a timestamp sits at the top of the system prompt.

How It Works

A cache read requires an exact byte match of the prefix, on the same model, within the TTL. Any byte that differs invalidates everything after it. So the request is laid out by volatility: the most stable content first, the most volatile last.

1. Tool definitions (rendered first by the Claude Messages API)
2. System prompt and static reference context
3. The growing conversation, with the cache breakpoint moving to its last block

Common Cache Breakers

• Volatile values in the prefix — a current timestamp, request ID, or session ID interpolated into the system prompt changes every call.
• Non-deterministic tool order — tool lists built from a dict, set, or plugin registry can reorder between calls; since tools render at the top, the whole prefix is lost.
• Editing the system prompt mid-conversation — rewrites the top of the prefix.
• Changing effort or thinking settings mid-conversation — these render ahead of your content on most models, so they are part of the prefix.
• Forks with a slightly different prefix — a subagent or branch shares the parent's cache only if its prefix is byte-identical, on the same model, at the same effort.
• Adding a tool mid-session — the tool block changes, invalidating everything behind it.

Techniques

• Move dynamic values (date, user ID) out of the system prompt and into the latest user message.
• Sort tool definitions deterministically, and serialize them with stable key order.
• Declare all tools up front and mark rare ones defer_loading: they stay out of the prefix and are appended only when tool search finds them.
• Deliver mid-conversation instruction changes as a system message appended to the conversation instead of editing the system prompt (where the model supports it).
• Batch unavoidable prefix changes (model, effort) to moments where the cache is already lost, such as right after compaction.
• Pre-warm the cache: send a max_tokens: 0 request with an explicit breakpoint at session start, using the same effort as real traffic, so the first real request hits a warm cache.
• Use a 1-hour TTL on the prefix when tool calls or subagents block the parent for longer than the 5-minute default (the TTL counts from the start of the request).

Measuring It

Track cache hit rate (cache_read_input_tokens over total input tokens) per request type. An unexpected drop points to a prefix change; diffing two consecutive requests byte-by-byte finds where they diverged. Claude Console and the cache diagnostics API report miss reasons and the divergence point directly.

Limitations

• Byte-exactness is fragile: a library upgrade that changes JSON serialization or whitespace silently breaks the cache.
• Pushing volatile values to the end of the prompt can slightly change model behavior compared to having them in the system prompt.
• Pre-warming pays a cache write that is wasted if no real request follows within the TTL.

See Also

• Prompt Caching — the mechanism that prefix stability makes effective.
• Cache-aware Routing — the same discipline applied to model switches: only change the prefix at natural cache boundaries.
• Dynamic Tool Loading — deferred tool definitions keep the top of the prefix fixed.
• Provider Pinning — prefix stability is necessary but not sufficient behind an aggregator; the backend must also stay the same.
• Subagents as Context Firewalls — forks trade cache sharing for a clean context; a byte-identical fork gets both.

Tools

• Reducing cost and improving performance with Claude Platform (ClaudeDevs, 2026) — lists the cache breakers and fixes above: volatile values, tool reordering, forks, pre-warming, TTL.
• Anthropic prompt caching — automatic caching, explicit breakpoints, 1-hour TTL.
• /claude-api cost-optimize (Claude Code) — profiles token spend and fixes cache breakpoint placement in application code.