Prompt-Caching meistern, in 10 Schritten von Cache-Miss zu 80 Prozent Hit-Rate

Cache-Hits sind der billigste Token den Du je bezahlst. Cache-Read kostet etwa 10 Prozent vom Normalpreis, Cache-Write 25 Prozent mehr. Wenn Du eine Session zwei Stunden offen hast und der Cache feuert nicht, verbrennst Du das Zehnfache für denselben System-Prompt. Das ist der häufigste versteckte Kosten-Treiber bei Claude Code. In diesem Playbook gehe ich durch wie ich Caching im Daily Driver, in eigenen Skripten und in MCP-Servern auf 80 Prozent Hit-Rate hochfahre. Wenig Theorie, viel was Du sofort kopieren kannst.

1. Versteh in einem Satz was Caching macht

Du markierst eine Stelle in Deinem Prompt mit cache_control. Anthropic speichert alles bis zu dieser Stelle (tools, system, messages in der Reihenfolge) für 5 Minuten. Beim nächsten Request mit demselben Praefix bekommst Du das Stück als Cache-Read zurück statt es neu zu prozessieren. Das ist alles.

Was viele uebersehen, der Cache-Breakpoint läuft nach 5 Minuten ab, wird aber bei jedem Hit verlängert. Solange Du innerhalb von 5 Minuten erneut feuerst, bleibt der Cache warm und kostet weiter nichts. Lange Pausen können mit dem 1-Stunden-Cache abgefangen werden, dazu gleich.

2. Cache messen, sonst optimierst Du im Blindflug

Jede Anthropic-API-Response liefert vier Token-Counter zurück. input_tokens ist alles was neu prozessiert wurde. cache_creation_input_tokens ist das was diesmal in den Cache geschrieben wurde. cache_read_input_tokens ist das was aus dem Cache geholt wurde. output_tokens ist die Antwort.

In Claude Code zeigt /usage aggregiert pro Session. Was Du im Auge behalten musst, das Verhältnis cache_read zu input_tokens. Wenn das über 4 zu 1 ist, läufst Du gut. Wenn input_tokens jedes Mal in den Tausenden ist und cache_read winzig bleibt, hast Du irgendwo einen Cache-Buster sitzen, meist ein dynamisches Datum oder eine Counter-Variable die in den System-Prompt geleakt ist.

Für eigene Skripte, log diese vier Zahlen pro Request mit. Eine kleine Tabelle in Postgres oder eine JSONL-Datei reicht. Ohne diese Messung optimierst Du auf Vermutungen.

3. Mit Automatic Caching anfangen, nicht mit Explicit Breakpoints

Anthropic empfiehlt das im Doku-Top und ich auch. Setz cache_control ein einziges Mal auf den letzten cacheable Block (also vor der dynamisch wechselnden User-Message). Beispiel in Python,

response = client.messages.create(
    model="claude-sonnet-4-5",
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[{"role": "user", "content": user_message}]
)

Das deckt 80 Prozent der Faelle ab. Erst wenn Du klare Schichten hast die unterschiedlich oft wechseln (Tools selten, System mittel, Conversation oft), gehst Du auf Explicit Breakpoints.

4. Den Stable-Prefix-Trick anwenden, alles Stabile nach vorne

Der Cache funktioniert nur wenn der Praefix Byte-für-Byte identisch ist. Ein einziges geaendertes Zeichen am Anfang invalidiert alles dahinter. Sortiere Deinen Prompt also so,

1. Tools zuerst, die ändern sich fast nie
2. Dann der große statische System-Prompt
3. Dann projekt-spezifischer Kontext (CLAUDE.md, geladene Dateien)
4. Dann erst die wechselnde User-Message am Ende

Klassischer Fehler, ein Timestamp oder eine Session-ID im System-Prompt. Das killt jeden Cache. Wenn Du sowas brauchst, pack es ans Ende in die User-Message, nicht in den System-Block.

5. Vier Breakpoints clever nutzen, nicht alle auf einmal

Du hast pro Request bis zu vier cache_control-Markierungen frei. Die sinnvolle Aufteilung,

• Breakpoint 1 nach den Tools
• Breakpoint 2 nach dem statischen System-Prompt
• Breakpoint 3 nach dem geladenen Projekt-Kontext
• Breakpoint 4 nach den letzten paar Conversation-Turns (rolling)

Jeder Breakpoint kostet einmalig Cache-Write-Praemie (25 Prozent extra). Wenn Du nur einen Layer hast der wirklich stabil ist, brauchst Du nicht vier Markierungen. Faustregel, lieber einen guten Breakpoint als vier halbgare.

6. CLAUDE.md ist Dein groesster Cache-Kandidat

Claude Code lädt CLAUDE.md am Anfang jeder Session in den Context. Wenn Du dort konstante Anweisungen hast (Coding-Style, Test-Regeln, verbotene Commands), wird das bei jedem einzelnen Request mitgeschickt. Cache-Treffer reduziert die Kosten dramatisch.

Was Du vermeiden musst, dynamische Daten in CLAUDE.md. Kein Today is 2026-05-26, kein Stand-Counter, keine "letzte Session war ...". Das lässt sich elegant per Sub-Skill lösen, das dynamische Datum als Slash-Command oder Tool-Output anziehen, nicht statisch ins File schreiben.

7. Tool-Definitionen schlank halten, sie sind im Cache-Praefix

MCP-Tool-Definitionen landen in tools und damit ganz vorne. Ein 80-Tool-MCP-Server pumpt 15.000 Tokens in jeden einzelnen Request, jedes Mal aufs Neue cachen. Das ist okay solange Du diese Tools dauerhaft brauchst.

Wenn Du sie aber selten brauchst, deaktivier den Server in .mcp.json und schalt ihn nur situativ ein. Oder nutz pickMcp-Pattern wenn Du einen eigenen Agent baust, jeder Agent bekommt nur die Tools die er wirklich braucht. Das Playbook tool-sprawl-vermeiden geht das tiefer.

8. 1-Stunden-Cache für lange Pausen, aber bewusst

Anthropic bietet zusätzlich zum 5-Minuten-Default einen 1-Stunden-Cache. Setzen mit,

{"type": "ephemeral", "ttl": "1h"}

Kostet mehr beim Schreiben, lohnt sich wenn Du Sessions hast wo Du länger weg bist (Meeting, Lunch). Mein Pattern, 1h-Cache nur für den ganz stabilen Layer (Tools plus globaler System-Prompt). 5min-Default für alles andere. Wenn ich weiß ich bin in 90 Minuten wieder am Laptop, spar ich mir den ganzen System-Prompt-Rebuild.

Wenn Du jede Session frisch startest und immer im Flow bist, lass den 1h-Cache weg. Die 25-Prozent-Praemie auf den Write rechnet sich nicht wenn der Cache sowieso permanent warm gehalten wird.

9. Cache-Diagnostics nutzen wenn der Hit ausbleibt

Anthropic hat Cache-Diagnostics im Beta. Du schickst zwei aufeinanderfolgende Requests und die API sagt Dir an welcher Stelle der Praefix divergiert ist. Goldwert wenn Du nicht verstehst warum der Cache nicht feuert.

Aktiviert wird das per Beta-Header anthropic-beta: prompt-caching-diagnostics-2025-XX-XX (die genaue Versionsnummer schau Dir in der aktuellen Doku an, die wechselt). In der Response bekommst Du dann ein zusaetzliches Feld mit dem Divergenz-Punkt.

Wenn Diagnostics zeigt dass die Divergenz schon auf Token 50 sitzt, hast Du sehr wahrscheinlich einen dynamischen Header oder ein Timestamp im Praefix. Wenn sie erst auf Token 8000 divergiert, lebt dort wahrscheinlich Dein letzter Tool-Output.

10. Mein Daily-Driver-Pattern, eine konkrete Routine

So sieht meine Claude-Code-Session aus, Caching-mässig optimiert.

Start, ich drücke /usage um zu sehen wo ich stehe. CLAUDE.md ist statisch (kein Datum, keine Counter). Mein MCP-Setup hat genau die fünf Server die ich diese Session brauche, der Rest ist disabled.

Erster Request läuft, cache_creation_input_tokens ist hoch (etwa 20.000), cache_read ist null. Normal, erster Request schreibt den Cache. Zweiter Request, cache_read springt auf 20.000, input_tokens sind nur die paar hundert neuer User-Input. Das ist der Punkt wo ich weiß alles läuft.

Nach 90 Minuten Pause kommt mein Cache-Reset. Statt erneut 20.000 Tokens zu prozessieren nutze ich /resume und einen 1h-Breakpoint auf den Tools-Layer. Cache hält warm, Wiedereinstieg kostet etwa die Haelfte.

Themenwechsel, ich drücke /clear und gehe in eine frische Session. Cache wird verworfen, aber das spart auf der nächsten Stunde mehr als der einmalige Rebuild kostet. Verschmutzter Cache mit irrelevantem Kontext ist teurer als ein frischer.

Was als nächstes

Wenn Caching sitzt, kommen die nächsten Hebel in claude-code-cost-controls-für-daily-driver (Modell-Routing, /compact, Spend-Limits) und context-window-managen-claude-code. Wer eigene Skripte baut, sollte das Cache-Logging-Pattern in eine Postgres-Tabelle giessen und nach zwei Wochen auswerten welche Praefixe wirklich Hits liefern. Da liegen oft die letzten 20 Prozent Optimierung.

Source

• platform.claude.com/docs/en/build-with-claude/prompt-caching (offiziell, abgerufen 2026-05-26)
• platform.claude.com/docs/de/build-with-claude/prompt-caching (DE-Mirror, abgerufen 2026-05-26)
• code.claude.com/docs/en/costs (offiziell, für /usage Mechanik, abgerufen 2026-04-27)