Prompt caching w Claude Code
Każda wiadomość w Claude Code wysyła nowe żądanie API, a do żądania ponownie trafia pełny kontekst: instrukcja systemowa, kontekst projektu, wcześniejsze wiadomości i wyniki narzędzi. Cache promptów ogranicza ponowne przetwarzanie tej części żądania, która się nie zmieniła.
Żeby zwiększyć szansę trafienia w cache, Claude Code umieszcza najpierw treści, które rzadko zmieniają się między turami: prompt systemowy, kontekst projektu, a na końcu rozmowę. Zmiana w rozmowie pozostawia prompt systemowy i kontekst projektu w cache. Zmiana promptu systemowego unieważnia wszystko, co znajduje się za nim w prefiksie.
Model warto wybrać na początku sesji, ponieważ każdy model ma osobny cache, a przełączenie przez /model sprawia, że następne żądanie odczytuje całą historię bez trafień w cache. Na większości modeli zmiana poziomu effort w trakcie sesji również przelicza całe żądanie, choć dla wskazanych modeli i metod uwierzytelniania cache domyślnie pozostaje zachowany. Dla głównej rozmowy można ustawić TTL przez promptCacheTtl albo zmienną CLAUDE_CODE_PROMPT_CACHE_TTL; akceptowane wartości to 5m i 1h. Te ustawienia wymagają Claude Code v2.1.242 lub nowszego, a godzinny TTL przy kluczu API lub dostawcy chmurowym można włączyć przez promptCacheTtl ustawione na 1h.
Wybór TTL zależy od przerw w pracy: godzinowy cache pomaga po dłuższym bezruchu, ale przy krótkich seriach pracy oznacza wyższą stawkę zapisu bez wykorzystania dłuższego czasu życia. Kompaktowanie tworzy nową, krótszą historię, więc unieważnia warstwę rozmowy; warstwy promptu systemowego i kontekstu projektu mogą pozostać w cache. Po odpowiedzi polecenie /usage pokazuje wiersz Prompt cache (main) z hit ratio, liczbą chybień i informacją, czy cache jest obecnie ciepły.
CLAUDE_CODE_PROMPT_CACHE_TTL=1h
FORCE_PROMPT_CACHING_5M=1
usage.cache_creation, czy zapis użył TTL jednogodzinnego czy pięciominutowego.claude -p "hello" --output-format json
Zastosowanie w praktyce
W długiej sesji, po której planujesz przerwę, ustaw głównemu cache TTL 1h; dłuższy TTL pomaga uniknąć ponownego przetwarzania wygasłego prefiksu po powrocie. Podczas diagnozowania cache wymuś FORCE_PROMPT_CACHING_5M=1, żeby porównywać zachowanie przy pięciominutowym TTL lub nadpisać dłuższy TTL ustawiony w konfiguracji zarządzanej. Po odpowiedzi sprawdź /usage, aby ocenić hit ratio, liczbę chybień i bieżący stan cache głównej rozmowy.
/compact zostaw na naturalną przerwę między zadaniami; ograniczysz zmiany prefiksu i zwiększysz hit rate cache.