Lehren aus der Entwicklung von Claude Code: Prompt Caching ist alles

Es wird in der Technikbranche oft gesagt, dass „Cache alles bestimmt", und das gilt auch für Agents.

Langlaufende, agentische Produkte wie Claude Code werden durch Prompt-Caching ermöglicht, das es uns erlaubt, Berechnungen aus vorherigen Roundtrips wiederzuverwenden und so Latenz und Kosten deutlich zu senken.

Was ist Prompt-Caching, wie funktioniert es und wie setzt man es technisch um? Mehr dazu in @RLanceMartin's Artikel über Prompt-Caching und unseren neuen Auto-Caching-Funktionen.

Bei Claude Code bauen wir unsere gesamte Infrastruktur auf Prompt-Caching auf. Eine hohe Prompt-Cache-Trefferquote senkt die Kosten und hilft uns, großzügigere Limits für unsere Abonnementpläne zu schaffen. Daher überwachen wir unsere Prompt-Cache-Trefferquote und erklären SEVs, wenn sie zu niedrig ist.

Dies sind die (oft unintuitiven) Lektionen, die wir aus der Optimierung von Prompt-Caching in großem Maßstab gelernt haben.

Gestalten Sie Ihren Prompt für das Caching

Prompt-Caching funktioniert durch Präfixabgleich – die API cached alles vom Anfang der Anfrage bis zu jedem cache_control-Breakpoint. Das bedeutet, die Reihenfolge, in der Sie die Dinge anordnen, ist enorm wichtig. Sie möchten, dass so viele Ihrer Anfragen wie möglich ein gemeinsames Präfix haben.

Der beste Weg, dies zu erreichen, ist: statischer Inhalt zuerst, dynamischer Inhalt zuletzt. Für Claude Code sieht das so aus:

1. Statischer System-Prompt & Tools (global gecached)
2. Claude.MD (innerhalb eines Projekts gecached)
3. Sitzungskontext (innerhalb einer Sitzung gecached)
4. Konversationsnachrichten

Auf diese Weise maximieren wir, wie viele Sitzungen Cache-Treffer teilen.

Aber das kann überraschend fragil sein! Beispiele für Gründe, warum wir diese Reihenfolge schon gebrochen haben, sind: das Einfügen eines detaillierten Zeitstempels in den statischen System-Prompt, das nicht-deterministische Durchmischen der Tool-Reihenfolge-Definitionen, das Aktualisieren von Tool-Parametern (z.B. welche Agents der AgentTool aufrufen kann) usw.

Verwenden Sie Nachrichten für Aktualisierungen

Es kann Zeiten geben, in denen die Informationen, die Sie in Ihren Prompt eingefügt haben, veraltet sind, zum Beispiel wenn Sie die Zeit angeben oder der Nutzer eine Datei ändert. Es mag verlockend sein, den Prompt zu aktualisieren, aber das würde zu einem Cache-Fehler führen und könnte für den Nutzer am Ende sehr teuer werden.

Überlegen Sie, ob Sie diese Informationen stattdessen in der nächsten Runde über Nachrichten übermitteln können. In Claude Code fügen wir im nächsten Nutzer-Beitrag oder Tool-Ergebnis einen <system-reminder>-Tag mit den aktualisierten Informationen für das Modell hinzu (z.B. „es ist jetzt Mittwoch"), was hilft, den Cache zu erhalten.

Wechseln Sie nicht mitten in der Sitzung das Modell

Prompt-Caches sind modellspezifisch, und das kann die Mathematik des Prompt-Cachings ziemlich unintuitiv machen.

Wenn Sie 100k Token tief in einer Konversation mit Opus sind und eine Frage stellen möchten, die relativ einfach zu beantworten ist, wäre es tatsächlich teurer, zu Haiku zu wechseln, als Opus antworten zu lassen, weil wir den Prompt-Cache für Haiku neu aufbauen müssten.

Wenn Sie das Modell wechseln müssen, ist der beste Weg dies mit Sub-Agents zu tun, bei denen Opus eine „Übergabe"-Nachricht an ein anderes Modell für die zu erledigende Aufgabe vorbereitet. Wir machen das oft mit den Explore-Agents in Claude Code, die Haiku verwenden.

Fügen Sie niemals Tools mitten in der Sitzung hinzu oder entfernen Sie sie

Das Ändern des Tool-Sets mitten in einer Konversation ist eine der häufigsten Arten, wie Leute das Prompt-Caching zerstören. Es erscheint intuitiv – Sie sollten dem Modell nur die Tools geben, von denen Sie denken, dass es sie gerade braucht. Aber da Tools Teil des gecachten Präfixes sind, macht das Hinzufügen oder Entfernen eines Tools den Cache für die gesamte Konversation ungültig.

Planungsmodus – Entwurf auf den Cache abgestimmt

Der Planungsmodus ist ein großartiges Beispiel für die Gestaltung von Funktionen unter Berücksichtigung von Caching-Einschränkungen. Der intuitive Ansatz wäre: Wenn der Nutzer in den Planungsmodus wechselt, tauschen Sie das Tool-Set gegen ein Set aus, das nur Lese-Tools enthält. Aber das würde den Cache zerstören.

Stattdessen behalten wir alle Tools jederzeit in der Anfrage und verwenden EnterPlanMode und ExitPlanMode selbst als Tools. Wenn der Nutzer den Planungsmodus aktiviert, erhält der Agent eine Systemnachricht, die erklärt, dass er sich im Planungsmodus befindet und welche Anweisungen gelten – erkunde die Codebasis, bearbeite keine Dateien, rufe ExitPlanMode auf, wenn der Plan fertig ist. Die Tool-Definitionen ändern sich nie.

Das hat einen zusätzlichen Vorteil: Da EnterPlanMode ein Tool ist, das das Modell selbst aufrufen kann, kann es autonom in den Planungsmodus wechseln, wenn es ein schwieriges Problem erkennt, ohne den Cache zu unterbrechen.

Tool-Suche – Verschieben statt Entfernen

Das gleiche Prinzip gilt für unsere Tool-Suche-Funktion. Claude Code kann Dutzende von MCP-Tools geladen haben, und alle in jede Anfrage aufzunehmen, wäre teuer. Aber sie mitten in der Konversation zu entfernen, würde den Cache zerstören.

Unsere Lösung: defer_loading. Anstatt Tools zu entfernen, senden wir leichte Platzhalter – nur den Tool-Namen, mit defer_loading: true – die das Modell bei Bedarf über ein ToolSearch-Tool „entdecken" kann. Die vollständigen Tool-Schemata werden nur geladen, wenn das Modell sie auswählt. Dies hält das gecachte Präfix stabil: dieselben Platzhalter sind immer in derselben Reihenfolge vorhanden.

Glücklicherweise können Sie das Tool-Suche-Tool über unsere API verwenden, um dies zu vereinfachen.

Kontextverzweigung – Kompaktierung

Kompaktierung tritt ein, wenn der Kontextfenster voll ist. Wir fassen die bisherige Konversation zusammen und setzen eine neue Sitzung mit dieser Zusammenfassung fort.

Überraschenderweise hat die Kompaktierung viele Randfälle mit Prompt-Caching, die unintuitiv sein können.

Insbesondere müssen wir bei der Kompaktierung die gesamte Konversation an das Modell senden, um eine Zusammenfassung zu erstellen. Wenn dies ein separater API-Aufruf mit einem anderen System-Prompt und ohne Tools ist (was die einfache Implementierung wäre), stimmt das gecachte Präfix aus der Hauptkonversation überhaupt nicht überein. Sie zahlen den vollen Preis für all diese Eingabe-Token, was die Kosten für den Nutzer drastisch erhöht.

Die Lösung – Cache-sichere Verzweigung

Wenn wir eine Kompaktierung durchführen, verwenden wir exakt denselben System-Prompt, Nutzerkontext, Systemkontext und dieselben Tool-Definitionen wie die Eltern-Konversation. Wir stellen die Konversationsnachrichten der Eltern voran und hängen den Kompaktierungs-Prompt als neue Nutzernachricht am Ende an.

Aus Sicht der API sieht diese Anfrage fast identisch mit der letzten Anfrage der Eltern aus – gleiches Präfix, gleiche Tools, gleicher Verlauf –, sodass das gecachte Präfix wiederverwendet wird. Die einzigen neuen Token sind der Kompaktierungs-Prompt selbst.

Das bedeutet jedoch, dass wir einen „Kompaktierungspuffer" speichern müssen, damit wir genügend Platz im Kontextfenster haben, um die kompaktierte Nachricht und die Zusammenfassungs-Ausgabe-Token unterzubringen.

Kompaktierung ist knifflig, aber zum Glück müssen Sie diese Lektionen nicht selbst lernen – basierend auf unseren Erfahrungen mit Claude Code haben wir Kompaktierung direkt in die API integriert, sodass Sie diese Muster in Ihren eigenen Anwendungen anwenden können.

Gelernte Lektionen

1. Prompt-Caching ist ein Präfixabgleich. Jede Änderung irgendwo im Präfix macht alles danach ungültig. Entwerfen Sie Ihr gesamtes System unter Berücksichtigung dieser Einschränkung. Wenn Sie die Reihenfolge richtig hinbekommen, funktioniert das meiste Caching von selbst.
2. Verwenden Sie Nachrichten anstelle von System-Prompt-Änderungen. Sie könnten versucht sein, den System-Prompt zu bearbeiten, um Dinge wie das Aktivieren des Planungsmodus oder das Ändern des Datums zu tun, aber es wäre besser, diese im Laufe der Konversation in Nachrichten einzufügen.
3. Wechseln Sie nicht mitten in der Konversation Tools oder Modelle. Verwenden Sie Tools, um Zustandsübergänge zu modellieren (wie den Planungsmodus), anstatt das Tool-Set zu ändern. Verschieben Sie das Laden von Tools anstelle sie zu entfernen.
4. Überwachen Sie Ihre Cache-Trefferquote wie die Betriebszeit. Wir alerten auf Cache-Brüche und behandeln sie als Vorfälle. Ein paar Prozentpunkte an Cache-Fehlern können Kosten und Latenz drastisch beeinflussen.
5. Verzweigungsoperationen müssen das Präfix der Eltern teilen. Wenn Sie eine Nebenberechnung (Kompaktierung, Zusammenfassung, Skill-Ausführung) durchführen müssen, verwenden Sie identische cache-sichere Parameter, damit Sie Cache-Treffer auf dem Präfix der Eltern erzielen.

Claude Code wurde von Anfang an auf Prompt-Caching aufgebaut. Das sollten Sie auch tun, wenn Sie einen Agenten bauen.