5 Counterintuitive Design Principles for Prompt Caching in Claude Code

1 Optimize Prompt Layout

Claude Code keeps the stable part of a prompt cached while the conversation grows. Prompt caching works via prefix matching on the cache_control breakpoint, so the order of tokens is critical. The recommended layout places static content first and dynamic content later, forming four layers:

Static system prompt & tool definitions (global cache)

CLAUDE.md (project‑level cache)

Session context (session‑level cache)

Dialogue messages

This maximizes cross‑session cache hits, but breaking the order—e.g., inserting timestamps, randomising tool order, or changing tool parameters—can invalidate the cache.

2 Use Message Passing to Update Information

When information in the prompt becomes stale (e.g., time changes or a file is edited), editing the prompt directly would break the cache. Instead, Claude Code inserts a <system‑reminder> tag in the next user or tool message to convey the update, preserving cache integrity.

3 Never Switch Model Mid‑Conversation

Prompt caches are model‑specific, making model switches counterintuitive. For example, after using Opus for 100 k tokens, switching to Haiku for a simple query seems cheaper but actually costs more because the entire cache must be rebuilt. If a model switch is required, the recommended approach is to use a sub‑agent that hands off the conversation, as Claude Code's Explore agent does with Haiku.

4 Never Add or Remove Tools Mid‑Conversation

Changing the tool set mid‑dialogue invalidates the cache because tool definitions are part of the prefix. Two sub‑principles address this:

4.1 Use Plan Mode with Fixed Tools

All tools remain defined at all times. EnterPlanMode and ExitPlanMode are themselves tools. When a user enters Plan Mode, the agent receives a system message explaining the mode and the allowed actions, keeping the tool definition unchanged.

4.2 Defer Loading Instead of Deleting Tools

Claude Code may have dozens of MCP tools. Rather than deleting them, it sends lightweight stubs with defer_loading: true. The full tool schema is loaded only when the model selects a tool, preserving the stable prefix order.

5 Compress Context Without Breaking Cache

When the context window fills, Claude Code forks a cache call to summarise the dialogue, replaces the original messages with the summary, and continues the session. Compression occurs only when the request uses the exact same system prompt, user/context, and tool definitions as the parent session, adding only the compression prompt token. A "compression buffer" is kept to ensure enough space for the summary output.

Claude Code now exposes this compression functionality directly in the API, allowing developers to use the built‑in pattern without re‑implementing it.

6 Experience Summary

Prompt cache is prefix matching. Any change anywhere in the prefix invalidates later content; design the whole system around this constraint.

Use messages instead of editing system prompts. Insert updates via <system‑reminder> or similar tags.

Never switch tools or models mid‑conversation. Model switches should be handled by sub‑agents; tools should be kept constant or deferred.

Monitor cache hit rate like uptime. Set alerts for cache miss spikes, as a few percentage points can dramatically increase cost and latency.

Forked operations must share the parent prefix. Parallel tasks such as compression or skill execution should reuse the same cache‑safe parameters to retain cache hits.

Claude Code was built around prompt caching from day one; adopting these patterns yields the best performance when building agents.