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

## Veille

Lezioni sul prompt caching da Claude Code: architettura della cache, modalità plan, compaction, ottimizzazione di costi e latenza

## 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, latenza, costi API, plan mode, compaction, tool search, defer loading, system prompt, cache hit rate, context window, subagent, architettura degli agenti, MCP tools, cache-safe forking

## Authors

@trq212 (Anthropic, équipe Claude Code)

## Ton

**Profilo**: prospettiva di un ingegnere interno (team Claude Code di Anthropic), registro tecnico e pedagogico, livello avanzato

**Descrizione**: l'autore adotta un tono strutturato e didattico, condividendo lezioni apprese "dall'interno" con una trasparenza inusuale sulle scelte architetturali di Claude Code. Lo stile è diretto e pragmatico, alternando spiegazioni teoriche ("il prompt caching funziona tramite prefix matching") ad aneddoti su bug riscontrati in produzione. L'approccio è quello di un post-mortem tecnico trasformato in una guida di best practice. Ogni sezione segue uno schema problema/intuizione ingenua/soluzione effettiva che rende accessibili concetti controintuitivi. Il pubblico di riferimento è composto da sviluppatori che costruiscono prodotti agentici sull'API Claude.

## Pense-betes

- **"Cache Rules Everything Around Me"**: il prompt caching è IL fattore determinante per la fattibilità economica e le prestazioni degli agenti di lunga durata. L'intero harness di Claude Code è costruito attorno a questo vincolo.
- **Prefix matching**: la cache funziona confrontando dall'inizio della richiesta fino ai checkpoint. Qualsiasi modifica al prefisso invalida tutto ciò che segue. Conseguenza: l'ordine degli elementi è critico.
- **Ordine ottimale del system prompt**: contenuto statico per primo, contenuto dinamico per ultimo. Per Claude Code: (1) System prompt + Tools (cache globale) → (2) CLAUDE.MD (cache per progetto) → (3) Contesto di sessione → (4) Messaggi della conversazione.
- **Fragilità sorprendente**: errori sottili rompono la cache: un timestamp dettagliato nel system prompt, un ordine non deterministico dei tool, l'aggiornamento dei parametri di un tool.
- **Messaggi di sistema anziché modifiche al prompt**: per informazioni variabili (data, file modificati), usare tag `<system-reminder>` nel messaggio utente successivo anziché modificare il system prompt (il che romperebbe la cache).
- **Mai cambiare modello a metà sessione**: la cache è specifica per ciascun modello. A 100k token in una conversazione con Opus, passare a Haiku costa di più che restare su Opus perché la cache deve essere ricostruita. Soluzione: usare subagent (messaggio di handoff).
- **Mai aggiungere/rimuovere tool a metà sessione**: i tool fanno parte del prefisso in cache. Qualsiasi modifica invalida la cache per l'intera conversazione. È l'errore più comune.
- **Modalità plan = progettazione costruita attorno alla cache**: invece di sostituire i tool (con versioni di sola lettura), Claude Code mantiene TUTTI i tool e utilizza EnterPlanMode/ExitPlanMode come tool essi stessi + un messaggio di sistema. Bonus: il modello può entrare autonomamente in modalità plan senza rompere la cache.
- **Tool Search = differire anziché rimuovere**: per decine di tool MCP, invece di rimuoverli, si inviano stub leggeri (nome + `defer_loading: true`). Il modello li "scopre" tramite ToolSearch. Il prefisso resta stabile.
- **Compaction cache-safe**: durante la compaction (sintesi quando la finestra di contesto è piena), usare esattamente lo stesso system prompt, contesto e tool della conversazione originale. Solo il prompt di compaction è nuovo. Altrimenti = costo pieno di tutti i token di input.
- **Buffer di compaction**: occorre riservare spazio nella finestra di contesto per il messaggio di compaction E i token di output della sintesi.
- **Monitorare il tasso di cache hit come l'uptime**: Anthropic attiva alert e dichiara SEV quando il tasso di cache hit è troppo basso. Pochi punti percentuali di cache miss impattano drasticamente costi e latenza.
- **Compaction disponibile nell'API**: sulla base delle lezioni apprese da Claude Code, la compaction è stata integrata direttamente nell'API Anthropic.

## RésuméDe400mots

Questo articolo tecnico del team Claude Code di Anthropic rivela come il prompt caching costituisca il fondamento architetturale di Claude Code, rendendo economicamente sostenibile un prodotto agentico con sessioni di lunga durata. Il principio fondamentale: la cache funziona tramite prefix matching, per cui qualsiasi modifica al prefisso invalida tutto ciò che segue. Questo unico vincolo determina la progettazione dell'intero sistema.

L'architettura del system prompt segue un ordine rigoroso: prima il contenuto statico e i tool (cache globale), poi CLAUDE.MD (cache per progetto), il contesto di sessione e infine i messaggi della conversazione. Questa gerarchia massimizza la condivisione della cache tra le sessioni. Il team ha scoperto che questo ordine è sorprendentemente fragile: un semplice timestamp, un ordine non deterministico dei tool o l'aggiornamento dei parametri di un tool bastano a rompere la cache.

Dall'esperienza del team emergono diverse regole controintuitive. Primo, mai modificare il system prompt per informazioni variabili (data, file modificati), bensì utilizzare tag `<system-reminder>` nei messaggi successivi. Secondo, mai cambiare modello a metà sessione: a 100k token in una conversazione con Opus, usare Haiku per una domanda semplice costa di più perché la cache deve essere interamente ricostruita. La soluzione: subagent con un messaggio di handoff. Terzo, mai aggiungere o rimuovere tool, poiché fanno parte del prefisso in cache.

La **modalità plan** illustra perfettamente una progettazione vincolata dalla cache. Invece di sostituire i tool con versioni di sola lettura (il che romperebbe la cache), Claude Code mantiene tutti i tool e utilizza EnterPlanMode/ExitPlanMode come tool aggiuntivi, insieme a un messaggio di sistema esplicativo. Questa progettazione consente al modello di entrare autonomamente in modalità plan senza rompere la cache. La **tool search** applica lo stesso principio: invece di rimuovere i tool MCP non utilizzati, degli stub leggeri con `defer_loading: true` mantengono stabile il prefisso.

La **compaction** (sintesi quando la finestra di contesto viene superata) presenta insidie rilevanti. L'implementazione naïve, che utilizza una chiamata API separata (system prompt diverso, nessun tool), comporta il costo pieno di tutti i token. La soluzione: utilizzare esattamente gli stessi parametri della conversazione originale per riutilizzare il prefisso in cache, pagando solo i token del prompt di compaction.

L'articolo conclude che il tasso di cache hit deve essere monitorato come l'uptime, con alert e incidenti dichiarati quando scende. Questi pattern sono ora integrati direttamente nell'API Anthropic, permettendo a qualsiasi sviluppatore di agenti di beneficiare di queste ottimizzazioni.

## 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/it/fiches/trq212-anthropic-claude-code-prompt-caching-lessons-2026-02/