# trq212-anthropic-claude-code-prompt-caching-lessons-2026-02

## Veille

Prompt caching lessons from Claude Code: cache architecture, plan mode, compaction, cost and latency optimization

## Titre Article

Lessons from Building Claude Code: Prompt Caching Is Everything

## Date

2026-02

## URL

https://x.com/trq212/status/2024574133011673516

## Keywords

prompt caching, Claude Code, cache prefix, latency, API costs, plan mode, compaction, tool search, defer loading, system prompt, cache hit rate, context window, subagents, agent architecture, MCP tools, cache-safe forking

## Authors

@trq212 (Anthropic, équipe Claude Code)

## Ton

**Profile**: Internal engineer's perspective (Claude Code team at Anthropic), technical and pedagogical register, advanced level

**Description**: The author adopts a structured, didactic tone, sharing lessons learned "from the inside" with unusual transparency about Claude Code's architectural choices. The style is direct and pragmatic, alternating between theoretical explanations ("prompt caching works through prefix matching") and anecdotes about bugs encountered in production. The approach is that of a technical post-mortem turned into a best-practices guide. Each section follows a problem/naive intuition/actual solution pattern that makes counterintuitive concepts accessible. The target audience consists of developers building agentic products on the Claude API.

## Pense-betes

- **"Cache Rules Everything Around Me"**: Prompt caching is THE determining factor for the economic feasibility and performance of long-running agents. The entire Claude Code harness is built around this constraint.
- **Prefix matching**: The cache works by matching from the start of the request up to checkpoints. Any change to the prefix invalidates everything that follows. Consequence: the order of elements is critical.
- **Optimal system prompt order**: Static content first, dynamic content last. For Claude Code: (1) System prompt + Tools (global cache) → (2) CLAUDE.MD (per-project cache) → (3) Session context → (4) Conversation messages.
- **Surprising fragility**: Subtle errors break the cache: a detailed timestamp in the system prompt, non-deterministic tool ordering, updating tool parameters.
- **System messages rather than prompt modifications**: For changing information (date, modified files), use `<system-reminder>` tags in the following user message rather than modifying the system prompt (which would break the cache).
- **Never switch models mid-session**: The cache is unique per model. At 100k tokens into an Opus conversation, switching to Haiku costs more than staying on Opus because the cache must be rebuilt. Solution: use subagents (handoff message).
- **Never add/remove tools mid-session**: Tools are part of the cached prefix. Any modification invalidates the cache for the entire conversation. This is the most common mistake.
- **Plan mode = design built around the cache**: Instead of swapping tools (for read-only versions), Claude Code keeps ALL tools and uses EnterPlanMode/ExitPlanMode as tools themselves + a system message. Bonus: the model can enter plan mode on its own without breaking the cache.
- **Tool Search = defer instead of remove**: For dozens of MCP tools, instead of removing them, send lightweight stubs (name + `defer_loading: true`). The model "discovers" them via ToolSearch. The prefix stays stable.
- **Cache-safe compaction**: During compaction (summarization when the context window is full), use exactly the same system prompt, context, and tools as the parent conversation. Only the compaction prompt is new. Otherwise = full cost of all input tokens.
- **Compaction buffer**: Space must be reserved in the context window for the compaction message AND the summary's output tokens.
- **Monitoring cache hit rate like uptime**: Anthropic triggers alerts and declares SEVs when the cache hit rate is too low. A few percentage points of cache miss dramatically impact costs and latency.
- **Compaction available in the API**: Based on lessons from Claude Code, compaction was integrated directly into API Anthropic.

## RésuméDe400mots

This technical article from the Claude Code team at Anthropic reveals how prompt caching forms the architectural foundation of Claude Code, making an agentic product with long-running sessions economically viable. The fundamental principle: the cache works through prefix matching, where any modification to the prefix invalidates everything that follows. This single constraint dictates the design of the entire system.

The system prompt architecture follows a strict order: static content and tools first (global cache), then CLAUDE.MD (per-project cache), session context, and finally conversation messages. This hierarchy maximizes cache sharing across sessions. The team discovered that this order is surprisingly fragile: a simple timestamp, a non-deterministic tool order, or updating tool parameters is enough to break the cache.

Several counterintuitive rules emerge from their experience. First, never modify the system prompt for changing information (date, modified files) but instead use `<system-reminder>` tags in subsequent messages. Second, never switch models mid-session: at 100k tokens into an Opus conversation, using Haiku for a simple question costs more because the cache must be entirely rebuilt. The solution: subagents with a handoff message. Third, never add or remove tools, since they are part of the cached prefix.

**Plan mode** perfectly illustrates cache-constrained design. Instead of replacing tools with read-only versions (which would break the cache), Claude Code keeps all tools and uses EnterPlanMode/ExitPlanMode as additional tools, along with an explanatory system message. This design lets the model enter plan mode on its own without breaking the cache. **Tool search** applies the same principle: instead of removing unused MCP tools, lightweight stubs with `defer_loading: true` keep the prefix stable.

**Compaction** (summarization when the context window is exceeded) presents major pitfalls. The naive implementation, using a separate API call (different system prompt, no tools), incurs the full cost of all tokens. The solution: use exactly the same parameters as the parent conversation to reuse the cached prefix, paying only for the compaction prompt's tokens.

The article concludes that the cache hit rate must be monitored like uptime, with alerts and incidents declared when it drops. These patterns are now integrated directly into API Anthropic, allowing any agent developer to benefit from these optimizations.

## GrapheDeConnaissance

- Claude Code —est_basé_sur→ Prompt caching (CONCEPT, 0.98)
- Cache —est_basé_sur→ correspondance de préfixe (CONCEPT, 0.99)
- System prompt —utilise→ ordre statique puis dynamique (METHODOLOGIE, 0.97)
- Modification du system prompt —réduit→ cache de la conversation (CONCEPT, 0.98)
- System-reminder —remplace→ modification du system prompt (CONCEPT, 0.95)
- Plan mode —permet→ stabilité du cache (CONCEPT, 0.96)
- Plan mode —utilise→ EnterPlanMode/ExitPlanMode comme outils (TECHNOLOGIE, 0.95)
- Tool search —utilise→ stubs avec defer_loading (TECHNOLOGIE, 0.94)
- Changement de modèle —réduit→ cache de la session (CONCEPT, 0.97)
- Compaction —utilise→ même system prompt et outils (CONCEPT, 0.96)
- @trq212 —travaille_chez→ Anthropic (ORGANISATION, 0.95)
- Anthropic —mesure→ cache hit rate (CONCEPT, 0.93)
- Compaction —fait_partie_de→ API Anthropic (TECHNOLOGIE, 0.92)
- Ajout/retrait d'outils —réduit→ cache de la conversation (CONCEPT, 0.97)

---
Canonical: https://www.thekb.eu/en/fiches/trq212-anthropic-claude-code-prompt-caching-lessons-2026-02/