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.