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

## Veille

Erkenntnisse zum Prompt Caching von Claude Code: Cache-Architektur, Plan-Modus, Kompaktierung, Kosten- und Latenzoptimierung

## 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-Präfix, Latenz, API-Kosten, Plan-Modus, Kompaktierung, Tool-Suche, Verzögertes Laden, System-Prompt, Cache-Trefferquote, Kontextfenster, Subagenten, Agenten-Architektur, MCP-Tools, cache-sicheres Forking

## Authors

@trq212 (Anthropic, équipe Claude Code)

## Ton

**Profil**: Perspektive eines internen Ingenieurs (Claude-Code-Team bei Anthropic), technisches und pädagogisches Register, fortgeschrittenes Niveau

**Beschreibung**: Der Autor nimmt einen strukturierten, didaktischen Ton an und teilt Erkenntnisse „von innen“ mit ungewöhnlicher Transparenz über die architektonischen Entscheidungen von Claude Code. Der Stil ist direkt und pragmatisch und wechselt zwischen theoretischen Erklärungen („Prompt Caching funktioniert über Prefix Matching“) und Anekdoten über Fehler, die in der Produktion aufgetreten sind. Der Ansatz gleicht einem technischen Post-Mortem, das zu einem Best-Practices-Leitfaden wird. Jeder Abschnitt folgt einem Muster aus Problem/naiver Intuition/tatsächlicher Lösung, das kontraintuitive Konzepte zugänglich macht. Die Zielgruppe besteht aus Entwicklern, die agentische Produkte auf der Claude-API aufbauen.

## Pense-betes

- **„Cache Rules Everything Around Me“**: Prompt Caching ist DER entscheidende Faktor für die wirtschaftliche Tragfähigkeit und die Leistung lang laufender Agenten. Der gesamte Claude-Code-Harness ist um diese Randbedingung herum aufgebaut.
- **Prefix Matching**: Der Cache funktioniert, indem vom Anfang der Anfrage bis zu Checkpoints abgeglichen wird. Jede Änderung am Präfix macht alles Nachfolgende ungültig. Konsequenz: Die Reihenfolge der Elemente ist entscheidend.
- **Optimale Reihenfolge des System-Prompts**: Statische Inhalte zuerst, dynamische Inhalte zuletzt. Bei Claude Code: (1) System-Prompt + Tools (globaler Cache) → (2) CLAUDE.MD (projektspezifischer Cache) → (3) Sitzungskontext → (4) Konversationsnachrichten.
- **Überraschende Fragilität**: Subtile Fehler brechen den Cache: ein detaillierter Zeitstempel im System-Prompt, eine nicht-deterministische Tool-Reihenfolge, die Aktualisierung von Tool-Parametern.
- **System-Nachrichten statt Prompt-Änderungen**: Für veränderliche Informationen (Datum, geänderte Dateien) `<system-reminder>`-Tags in der nachfolgenden Nutzernachricht verwenden, statt den System-Prompt zu ändern (was den Cache brechen würde).
- **Nie mitten in einer Sitzung das Modell wechseln**: Der Cache ist pro Modell einzigartig. Bei 100k Tokens in einer Opus-Konversation kostet der Wechsel zu Haiku mehr, als bei Opus zu bleiben, weil der Cache neu aufgebaut werden muss. Lösung: Subagenten verwenden (Handoff-Nachricht).
- **Nie mitten in einer Sitzung Tools hinzufügen/entfernen**: Tools sind Teil des zwischengespeicherten Präfixes. Jede Änderung macht den Cache für die gesamte Konversation ungültig. Dies ist der häufigste Fehler.
- **Plan-Modus = Design rund um den Cache aufgebaut**: Anstatt Tools auszutauschen (durch Nur-Lese-Versionen), behält Claude Code ALLE Tools bei und verwendet EnterPlanMode/ExitPlanMode selbst als Tools + eine System-Nachricht. Bonus: Das Modell kann von sich aus in den Plan-Modus wechseln, ohne den Cache zu brechen.
- **Tool-Suche = Verzögern statt Entfernen**: Bei Dutzenden von MCP-Tools werden diese, anstatt entfernt zu werden, als leichtgewichtige Stubs gesendet (Name + `defer_loading: true`). Das Modell „entdeckt“ sie über ToolSearch. Das Präfix bleibt stabil.
- **Cache-sichere Kompaktierung**: Bei der Kompaktierung (Zusammenfassung, wenn das Kontextfenster voll ist) exakt denselben System-Prompt, Kontext und dieselben Tools wie in der übergeordneten Konversation verwenden. Nur der Kompaktierungs-Prompt ist neu. Andernfalls = volle Kosten aller Eingabe-Tokens.
- **Kompaktierungs-Puffer**: Im Kontextfenster muss Platz für die Kompaktierungs-Nachricht UND die Ausgabe-Tokens der Zusammenfassung reserviert werden.
- **Überwachung der Cache-Trefferquote wie der Uptime**: Anthropic löst Warnungen aus und erklärt SEVs (Vorfälle), wenn die Cache-Trefferquote zu niedrig ist. Wenige Prozentpunkte an Cache Misses wirken sich drastisch auf Kosten und Latenz aus.
- **Kompaktierung in der API verfügbar**: Basierend auf den Erkenntnissen aus Claude Code wurde die Kompaktierung direkt in API Anthropic integriert.

## RésuméDe400mots

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.

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