Dieser technische Artikel des Claude-Code-Teams von Anthropic zeigt, wie Prompt Caching das architektonische Fundament von Claude Code bildet und ein agentisches Produkt mit lang laufenden Sitzungen wirtschaftlich tragfähig macht. Das Grundprinzip: Der Cache funktioniert über Prefix Matching, wobei jede Änderung am Präfix alles Nachfolgende ungültig macht. Diese einzige Randbedingung bestimmt das Design des gesamten Systems.
Die Architektur des System-Prompts folgt einer strikten Reihenfolge: zuerst statische Inhalte und Tools (globaler Cache), dann CLAUDE.MD (projektspezifischer Cache), Sitzungskontext und schließlich die Konversationsnachrichten. Diese Hierarchie maximiert die Cache-Weitergabe über Sitzungen hinweg. Das Team stellte fest, dass diese Reihenfolge überraschend fragil ist: Ein einfacher Zeitstempel, eine nicht-deterministische Tool-Reihenfolge oder die Aktualisierung von Tool-Parametern genügen, um den Cache zu brechen.
Aus ihrer Erfahrung ergeben sich mehrere kontraintuitive Regeln. Erstens: Den System-Prompt niemals wegen veränderlicher Informationen (Datum, geänderte Dateien) modifizieren, sondern stattdessen <system-reminder>-Tags in nachfolgenden Nachrichten verwenden. Zweitens: Nie mitten in einer Sitzung das Modell wechseln: Bei 100k Tokens in einer Opus-Konversation kostet die Verwendung von Haiku für eine einfache Frage mehr, weil der Cache vollständig neu aufgebaut werden muss. Die Lösung: Subagenten mit einer Handoff-Nachricht. Drittens: Niemals Tools hinzufügen oder entfernen, da sie Teil des zwischengespeicherten Präfixes sind.
Der Plan-Modus veranschaulicht dieses cache-beschränkte Design in Reinform. Anstatt Tools durch Nur-Lese-Versionen zu ersetzen (was den Cache brechen würde), behält Claude Code alle Tools bei und verwendet EnterPlanMode/ExitPlanMode als zusätzliche Tools, zusammen mit einer erklärenden System-Nachricht. Dieses Design erlaubt es dem Modell, von sich aus in den Plan-Modus zu wechseln, ohne den Cache zu brechen. Die Tool-Suche wendet dasselbe Prinzip an: Anstatt ungenutzte MCP-Tools zu entfernen, halten leichtgewichtige Stubs mit defer_loading: true das Präfix stabil.
Die Kompaktierung (Zusammenfassung bei Überschreitung des Kontextfensters) birgt erhebliche Fallstricke. Die naive Implementierung, bei der ein separater API-Aufruf verwendet wird (anderer System-Prompt, keine Tools), verursacht die vollen Kosten aller Tokens. Die Lösung: exakt dieselben Parameter wie in der übergeordneten Konversation verwenden, um das zwischengespeicherte Präfix wiederzuverwenden, sodass nur die Tokens des Kompaktierungs-Prompts bezahlt werden.
Der Artikel kommt zu dem Schluss, dass die Cache-Trefferquote wie die Verfügbarkeit (Uptime) überwacht werden muss, wobei bei einem Rückgang Warnungen ausgelöst und Vorfälle (Incidents) gemeldet werden. Diese Muster sind mittlerweile direkt in API Anthropic integriert, sodass jeder Entwickler von Agenten von diesen Optimierungen profitieren kann.