Lehren aus dem Aufbau von Claude Code: Prompt Caching ist alles

• In Produkten mit lang laufenden Agenten ist Prompt Caching die Schlüsseltechnik, die Latenz und Kosten drastisch senkt, indem Berechnungen aus vorherigen Roundtrips wiederverwendet werden; die gesamte Architektur von Claude Code wurde darum herum entworfen
• Caching funktioniert über Präfix-Matching, daher entscheidet die Reihenfolge – statische Inhalte nach vorn, dynamische Inhalte nach hinten – über Kosten und Performance
• Wenn während einer Sitzung Tools oder Modelle gewechselt werden, wird der Cache ungültig, daher sind Umgehungsdesigns mit leichten Stubs und Tools für Zustandswechsel unverzichtbar statt Tools zu entfernen
• Auch die bei Überschreitung des Kontextfensters ausgeführte Kompaktierung (Zusammenfassung/Verkleinerung) muss das Cache-Präfix des Elterndialogs teilen, um eine Kostenexplosion zu vermeiden
• Die Cache-Trefferquote sollte wie Uptime überwacht werden; schon wenige Prozent Cache-Misses haben gravierende Auswirkungen auf Kosten und Latenz und sollten als Incident behandelt werden

---

• „Cache Rules Everything Around Me“ gilt auch für Agenten
• Prompt Caching macht Produkte mit lang laufenden Agenten wie Claude Code überhaupt erst möglich
• Es reduziert latency und cost erheblich, indem Berechnungen aus vorherigen Roundtrips wiederverwendet werden

Wie Prompt Caching funktioniert und wie der System-Prompt angeordnet werden sollte

• Prompt Caching arbeitet mit Präfix-(Prefix-)Matching; die API cached ab dem Beginn der Anfrage alles bis zu jedem cache_control-Haltepunkt
• Entscheidend ist, gemeinsame Präfixe zwischen Anfragen zu maximieren; dafür müssen statische Inhalte zuerst und dynamische Inhalte später platziert werden
• Die Reihenfolge in Claude Code:
  • Statischer System-Prompt und Tools (globales Caching)
  • Claude.MD (Caching innerhalb des Projekts)
  • Sitzungskontext (Caching innerhalb der Sitzung)
  • Dialognachrichten
• Diese Reihenfolge ist überraschend fragil; eine Cache-Invalidierung kann entstehen durch
  detaillierte Zeitstempel im statischen System-Prompt,
  nicht deterministisches Shuffling der Tool-Reihenfolge,
  Aktualisierungen von Tool-Parametern
  usw.

Update-Strategie mit System Messages

• Es gibt Situationen, in denen Informationen im Prompt veralten, etwa durch veränderte Zeitangaben oder Dateiänderungen des Nutzers
• Den Prompt direkt zu aktualisieren führt zu Cache-Misses und kann die Kosten für Nutzer erhöhen
• Stattdessen wird die Information im nächsten Turn als Nachricht übermittelt
  • Claude Code fügt Aktualisierungen in der nächsten User Message oder im nächsten Tool Result mit dem Tag <system-reminder> ein
  • So kann zum Beispiel ein Zeit-Update wie „Jetzt ist Mittwoch“ übermittelt werden
• Mit solchen system messages lässt sich der Cache erhalten

Warum man das Modell nicht mitten in der Sitzung wechseln sollte

• Der Prompt-Cache ist modellspezifisch, daher kann die Kostenberechnung beim Caching kontraintuitiv ausfallen
• Beispiel: Wenn in einem 100k-Token-Dialog mit Opus für eine einfache Frage zu Haiku gewechselt wird, muss der Cache für Haiku von Grund auf neu aufgebaut werden; das kann teurer sein, als einfach mit Opus zu antworten
• Wenn ein Modellwechsel nötig ist, ist ein Subagenten-Ansatz am besten: Opus bereitet eine „Handoff“-Nachricht für das andere Modell vor und übergibt sie
  • Der Explore-Agent von Claude Code nutzt diesen Ansatz bei Haiku

Während einer Sitzung keine Tools hinzufügen oder entfernen

• Änderungen an der Tool-Menge sind eine der häufigsten Ursachen für Cache-Invalidierungen
• Da Tools Teil des gecachten Präfixes sind, invalidiert schon das Hinzufügen oder Entfernen eines einzigen Tools den Cache des gesamten Dialogs

• Plan Mode — cache-zentriertes Design

  • Intuitiver Ansatz: Wenn der Nutzer in den Plan Mode wechselt, nur noch Read-only-Tools übrig lassen → zerstört den Cache
  • Tatsächliches Design: Alle Tools bleiben immer in der Anfrage enthalten, und EnterPlanMode sowie ExitPlanMode werden als Tools implementiert
    • Beim Eintritt in den Plan Mode werden per System Message Anweisungen gegeben: nur die Codebasis erkunden, keine Dateien bearbeiten, nach Abschluss ExitPlanMode aufrufen
    • Die Tool-Definitionen ändern sich niemals
  • Zusätzlicher Vorteil: Da EnterPlanMode ein Tool ist, das das Modell selbst aufrufen kann, kann es beim Erkennen schwieriger Probleme autonom in den Plan Mode wechseln, ohne den Cache zu zerstören

• Tool Search — Lazy Loading statt Entfernen

  • Claude Code kann Dutzende MCP-Tools laden; alle einzubeziehen ist teuer, sie zu entfernen zerstört den Cache
  • Lösung: ein defer_loading-Ansatz, bei dem statt des Entfernens nur leichte Stubs mit Namen (defer_loading: true) gesendet werden
    • Falls nötig, lädt das Modell das vollständige Schema über das ToolSearch-Tool
    • Da dieselben Stubs immer in derselben Reihenfolge vorhanden sind, bleibt das gecachte Präfix stabil
  • Mit der tool search-Funktion der API lässt sich das vereinfachen

Kontext-Forking — Kompaktierung (Compaction)

• Wenn das Kontextfenster überschritten wird, wird eine Kompaktierung durchgeführt: Der Dialog wird zusammengefasst und eine neue Sitzung gestartet
• Eine intuitive Implementierung (Zusammenfassung in einem separaten API-Aufruf mit anderem System-Prompt und anderen Tools) stimmt überhaupt nicht mit dem Cache-Präfix des Hauptdialogs überein, sodass für alle Input-Tokens der volle Preis anfällt

• Cache-Safe-Forking-Lösung

  • Bei der Kompaktierung werden derselbe System-Prompt, derselbe User-Kontext, derselbe System-Kontext und dieselben Tool-Definitionen wie im Elterndialog verwendet
  • Die Dialognachrichten des Elterndialogs werden vorne platziert, der Kompaktierungs-Prompt wird am Ende als neue User Message angehängt
  • Aus Sicht der API sieht diese Anfrage fast genauso aus wie die letzte Anfrage des Elterndialogs; dadurch kann das gecachte Präfix wiederverwendet werden, und neu sind nur die Tokens des Kompaktierungs-Prompts
  • Innerhalb des Kontextfensters muss ein „Kompaktierungs-Puffer“ für die kompakte Nachricht und die Output-Tokens der Zusammenfassung reserviert werden
  • Auf Basis dieses Musters hat Anthropic Compaction direkt in die API integriert, sodass Entwickler es selbst anwenden können

Zusammenfassung der wichtigsten Lehren

• Prompt Caching ist Präfix-Matching; wenn sich irgendwo im Präfix etwas ändert, wird alles danach ungültig → das gesamte System muss auf diese Einschränkung hin entworfen werden
• Statt den System-Prompt zu ändern, ist es für den Erhalt des Caches vorteilhafter, während des Dialogs System Messages einzufügen
• Tools oder Modelle nicht mitten im Dialog wechseln → Zustandswechsel als Tools modellieren und statt Tool-Entfernung Lazy Loading nutzen
• Die Cache-Trefferquote muss wie Uptime überwacht werden; schon wenige Prozent Cache-Miss-Rate wirken sich dramatisch auf Kosten und Latenz aus
• Fork-Operationen (Kompaktierung, Zusammenfassung, Skill-Ausführung) müssen das Präfix des Elterndialogs teilen, damit Cache-Treffer möglich sind

• Wenn du einen Agenten baust, musst du von Tag eins an um Prompt Caching herum designen