Przejdź do głównej zawartości

Optymalizacja wydajności Claude Code: kontekst, cache i effort

Optymalizacja wydajności Claude Code polega na tym, by każda sesja była tańsza i szybsza dzięki kontroli nad tym, co model czyta ponownie: rozmiarem kontekstu, trafieniami w cache promptów, poziomem effort i wyborem modelu. Każde zapytanie wysyła całą rozmowę od nowa, więc zawężanie odczytów, ciepły cache i strojenie effort przed zmianą modelu obniżają koszty bez obniżania poprzeczki, której pilnują testy projektu.

Ta strona jest dla programisty, którego sesje zrobiły się wolne i drogie. Jedna sesja przeczytała pół repozytorium, żeby poprawić błąd lintera. Inna jest otwarta od rana, więc jednolinijkowe pytanie wysyła teraz sześć godzin historii. Dwa razy zmieniłeś model, żeby „zaoszczędzić”, i po każdej zmianie następna tura była wolniejsza. Rozwiązaniem jest zmiana tego, co niesie każde zapytanie, a nie rzadsze używanie Claude Code. Jeśli jesteś tech leadem i potrzebujesz wydatków w podziale na zespoły oraz twardych limitów, zacznij od kontroli kosztów Claude Code, a tu wróć po nawyki dla pojedynczej sesji. Jeśli wolna jest twoja aplikacja, a nie agent, potrzebujesz analizy wydajności aplikacji.

  • Dwuminutową procedurę pomiaru, która mówi, za którą dźwignię pociągnąć
  • Działania, które unieważniają cache promptów, i te, które tylko na to wyglądają
  • Regułę wyboru między /clear, /compact i /rewind oraz ustawienia effort i modelu we właściwej kolejności
  • Cztery prompty do skopiowania i sposób, by pokazać, że tańsza sesja wciąż przechodzi te same bramki

Claude Code wysyła całą rozmowę z każdym zapytaniem: prompt systemowy, CLAUDE.md, definicje narzędzi, każdą wcześniejszą wiadomość i każdy wynik narzędzia. Każde wywołanie narzędzia to kolejne zapytanie z tą samą historią. Koszt zależy od czterech rzeczy:

CzynnikCo się dziejeDźwignia
Rozmiar kontekstuDługa sesja płaci za swoją historię w każdej turze, po stawce cache, gdy cache jest ciepłyZawężaj odczyty, /clear między zadaniami, deleguj rozwlekłą pracę do subagentów
Trafienia w cacheChybienie przetwarza cały kontekst po pełnej cenie wejścia, a tura jest wolniejszaUnikaj zmiany modelu w trakcie zadania, trzymaj stały zestaw MCP i pluginów, pilnuj czasu życia cache
Effort i modelTokeny myślenia są rozliczane jak tokeny wyjściowe; wyższy effort to więcej myślenia w każdym zapytaniuNajpierw dostrój effort, model zmieniaj tylko na granicy zadań
Agenci, których nie obserwujeszSubagenci, workflow, zadania cykliczne i sprawdzenia celu wysyłają własne zapytaniaPrzypinaj tanie modele pomocnikom, anuluj bezczynne pętle

Dwa fakty ze strony Anthropic o cache promptów w Claude Code (sprawdzone 2026-09-26) zmieniają typowe rady. Po pierwsze, czas życia cache zależy od sposobu płatności. W subskrypcji Claude, w ramach limitu planu, główna rozmowa dostaje cache na godzinę. Przy rozliczaniu z dodatkowych kredytów (usage credits), kluczu API lub dostawcy chmurowym dostaje pięć minut. Po drugie, edycja plików w repozytorium ani edycja CLAUDE.md w trakcie sesji nie unieważnia cache. Odczyty dopisują się do rozmowy; nic wcześniejszego nie jest przepisywane. Rada, by „nie przestawiać plików, żeby cache przetrwał”, to mit.

Jako punkt odniesienia: dokumentacja kosztów Anthropic (sprawdzona 2026-09-26) podaje, że we wdrożeniach firmowych średnia to „around $13 per developer per active day and $150-250 per developer per month, with costs remaining below $30 per active day for 90% of users”. Ceny modeli są w hubie modeli, nie na tej stronie.

Zmierz jedną sesję Claude Code, zanim cokolwiek zmienisz

Dział zatytułowany „Zmierz jedną sesję Claude Code, zanim cokolwiek zmienisz”
  1. Uruchom /usage. Blok Session pokazuje szacowany koszt sesji, rozbicie tokenów na modele oraz, od v2.1.251, wiersz Prompt cache (main) z odsetkiem trafień, liczbą chybień i informacją, czy cache jest teraz ciepły. Od v2.1.260 wiersz podaje też prawdopodobną przyczynę ostatniego chybienia, na przykład likely cause: tool definitions changed. /cost i /stats to aliasy /usage. W subskrypcji kwota w dolarach to cena katalogowa, a nie twój rachunek.

  2. Uruchom /context. Polecenie rysuje okno jako kolorową siatkę: prompt systemowy, pliki pamięci, narzędzia, serwery MCP i rozmowa. Jeśli pliki pamięci lub narzędzia zajmują dużą część, zanim cokolwiek napiszesz, popraw konfigurację (następna sekcja). Jeśli dominuje rozmowa, wybierz między /clear, /compact i /rewind.

  3. Wyświetl kontekst i cache na pasku statusu. Skonfiguruj pasek statusu tak, by pokazywał zajętość kontekstu i pola prompt_cache. Wtedy rosnące okno albo serię chybień zauważysz w tej samej turze, a nie pod koniec tygodnia.

  4. Wklej oba wyniki do promptu poniżej. /usage i /context to polecenia lokalne, które uruchamiasz tylko ty; Claude czyta ich wynik, ale nie może ich wywołać. Podział /usage na serwery, skille i pętle pojawia się tylko w planach Pro, Max, Team i Enterprise.

  5. Zapisz jedną liczbę. Zanotuj metrykę, którą chcesz ruszyć (koszt sesji, odsetek trafień w cache albo sekundy na turę). Bez wartości „przed” spokojny dzień wygląda jak oszczędność.

Najtańszy token to ten, którego Claude nigdy nie przeczyta.

Wskaż punkt wejścia, a nie całe drzewo. Ogólny prompt w stylu „przejrzyj aplikację pod kątem bezpieczeństwa” uruchamia szerokie skanowanie. Wskaż plik lub katalog i pozwól Claude eksplorować od niego. --add-dir działa odwrotnie niż zawężanie: dodaje katalogi, do których Claude ma dostęp, na przykład sąsiedni pakiet w monorepo. Claude Code nie przyjmuje katalogów jako argumentów pozycyjnych; argumentem pozycyjnym jest prompt.

Okno terminala
# Terminal: wskaż punkt startowy w prompcie
claude "Trace session validation starting from src/auth/core.ts. Read only files it imports."
# Terminal: świadomie poszerz dostęp, gdy zadanie obejmuje dwa pakiety
claude --add-dir ../shared-logger "Update the logger API and every call site in this app."

Linia „najpierw wypisz, potem otwieraj” ujawnia plan, więc możesz go przyciąć, zanim tokeny zostaną wydane.

Pilnuj, by CLAUDE.md był krótki, a procedury przenieś do skilli. Główny plik CLAUDE.md projektu i plik użytkownika ładują się do każdej sesji. Anthropic zaleca, by CLAUDE.md miał mniej niż 200 linii. Reguły dla poddrzewa umieść w CLAUDE.md wewnątrz tego poddrzewa: załaduje się dopiero, gdy Claude przeczyta tam jakiś plik. Procedury krok po kroku (checklista wydania, runbook migracji) przenieś do skilli, które ładują się dopiero po wywołaniu. Przewodnik po systemie pamięci pokazuje, jak podzielić pliki.

Deleguj rozwlekłą pracę do subagentów. Uruchomienia testów, analiza logów i przeglądanie dokumentacji produkują długie wyniki. Własny subagent trzyma ten wynik we własnym kontekście i zwraca podsumowanie. Do prac mechanicznych ustaw model: haiku we frontmatterze subagenta, bo subagent dziedziczący model sesji płaci stawkę tego modelu.

Filtruj wynik, zanim zobaczy go Claude. Hook PreToolUse może przepisać polecenie testów tak, by wracały tylko błędy. To utwardzona wersja wzorca z dokumentacji kosztów Anthropic (niezakotwiczone wyrażenie regularne oryginału zatwierdzałoby automatycznie polecenia łańcuchowe). Zapisz go jako ~/.claude/hooks/filter-test-output.sh z prawem wykonywania:

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')
safe='^(npm test|pytest|go test)([[:space:]][^;&|`$<>()]*)?$'
if [[ "$cmd" != *$'\n'* && "$cmd" =~ $safe ]]; then
filtered_cmd="( set -o pipefail; $cmd 2>&1 | { grep -A 5 -E '(FAIL|ERROR|[Ee]rror)' || true; } | sed -n '1,100p' )"
echo "$input" | jq --arg filtered "$filtered_cmd" \
'{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: (.tool_input + {command: $filtered})}}'
else
echo "{}"
fi

Zarejestruj go w hooks.PreToolUse z "matcher": "Bash" w ~/.claude/settings.json (format opisuje przewodnik po automatyzacji hookami), a potem uruchom /hooks, by sprawdzić, że jest na liście. Podpowłoka z pipefail zachowuje kod wyjścia testów, więc nieudany przebieg nadal wygląda na nieudany, nawet gdy żadna linia nie pasuje do filtra; przy sukcesie wynik jest pusty. Wzorzec jest zakotwiczony z obu stron i odrzuca znaki nowej linii oraz metaznaki powłoki (;, &, |, $, backticki, przekierowania), bo permissionDecision: "allow" pomija pytanie o zgodę dla wszystkiego, co pasuje: luźniejsze ^(npm test|pytest) zatwierdziłoby automatycznie także pytest && rm -rf build.

Wybieraj CLI lub serwer językowy zamiast kolejnych serwerów MCP. Definicje narzędzi MCP są domyślnie odraczane (tool search), więc do kontekstu trafiają tylko nazwy narzędzi i instrukcje serwera, dopóki Claude nie wywoła narzędzia; gh, aws czy sentry-cli nie dodają nic. W językach typowanych plugin code intelligence zastępuje „grep, a potem odczyt pięciu plików” jednym wywołaniem go-to-definition. Zainstaluj plugin dla swojego języka na początku sesji, na przykład /plugin install typescript-lsp@claude-plugins-official (wymaga typescript-language-server w PATH). Uruchom /mcp, by wyłączyć serwery, których w tej sesji nie używasz.

Które działania unieważniają cache promptów w Claude Code?

Dział zatytułowany „Które działania unieważniają cache promptów w Claude Code?”

Chybienie w cache kosztuje raz: jedną wolniejszą turę, która czyta historię po pełnej cenie wejścia, po czym nowy prefiks trafia do cache. Drogi wzorzec to powtarzanie chybień w trakcie zadania. Tabela streszcza dokumentację cache promptów Claude Code według stanu na v2.1.283:

Unieważnia cache przy następnym zapytaniuZachowuje cache
Zmiana modelu przez /model, w tym każde przełączenie trybu planowania przy opusplan, skill, którego frontmatter wskazuje inny model, oraz automatyczne przełączenie na model zapasowy, gdy klasyfikator bezpieczeństwa oznaczy zapytanieEdycja plików w repozytorium
Zmiana effort, z wyjątkiem Opus 5.5 i Fable 5.1 na kluczu API lub w subskrypcji ClaudeEdycja CLAUDE.md (zmiana działa po /clear, /compact lub restarcie)
Pierwsze włączenie fast mode w rozmowieZmiana trybu uprawnień lub stylu wyjścia; późniejsze wyłączenie i ponowne włączenie fast mode
Przy wyłączonym tool search: podłączenie serwera MCP, celowe usunięcie narzędzia, plugin z serwerami MCP albo reguła deny na całe narzędzie, np. BashPodłączanie serwerów MCP przy domyślnym tool search; skille, polecenia, agenci i hooki z pluginów
/compact (z założenia: historia zostaje zastąpiona)Wywołanie skilli i poleceń, /recap, /rewind, uruchomienie subagenta
Aktualizacja Claude Code (pierwsza sesja po restarcie); wiele zrzutów ekranu, gdy najstarsze zostają usunięte partiąRównoległe sesje w tym samym katalogu, które czytają nawzajem swój cache

Wynikają z tego trzy nawyki. Model, effort i fast mode wybieraj na początku zadania, nie w jego środku. Pluginy instaluj i serwery podłączaj, zanim zaczniesz. A jeśli pracujesz w kilku worktree, licz się z tym, że każdy buduje własny cache: katalog roboczy jest częścią prefiksu, więc worktree tego samego repozytorium go nie współdzielą. Subagenci też budują własny cache, a ten żyje pięć minut nawet w subskrypcji, chyba że ustawisz subagentPromptCacheTtl.

Jeśli używasz klucza API i często odchodzisz na dłużej niż pięć minut, ustaw w ustawieniach "promptCacheTtl": "1h" (v2.1.242 lub nowszy). Zapisy do cache godzinnego są droższe niż pięciominutowe, więc opłaca się to tylko przy częstych przerwach. Żeby sprawdzić, jakiego TTL użył przebieg, uruchom claude -p "hello" --output-format json i odczytaj usage.cache_creation.

Wszystkie trzy polecenia zmniejszają to, co niesie następne zapytanie. Kosztują różnie.

SytuacjaPolecenieDlaczego
Skończyłeś zadanie i zaczynasz niepowiązane/clear auth-refactor (nazwa oznacza starą rozmowę w /resume)Nic nie kosztuje; następne zadanie startuje z czystym prefiksem, który trafi do cache
Zadanie trwa, ale historia jest pełna ślepych uliczek/compact z instrukcjamiZachowuje ciągłość. Przy ciepłym cache zapytanie podsumowujące czyta prefiks z cache; po długiej przerwie przetwarza całą historię od nowa, więc kompaktuj przed przerwą, nie po niej
Ostatnie tury poszły w złą stronę/rewind (albo dwa razy Esc) do tury przed objazdemPrzycina do prefiksu, który już jest w cache, i może też przywrócić checkpointy kodu
Chcesz tylko przypomnienia, co się działo/recapDopisuje podsumowanie bez naruszania historii w cache

Autokompakcja nadal działa jako zabezpieczenie. Na modelach z natywnym oknem 1M w Anthropic API Claude Code domyślnie kompaktuje przy około 967K tokenów. Jeśli długie sesje tracą jakość wcześniej, ustaw mniejsze okno przez /autocompact 400k; wartość zapisuje się w ustawieniach użytkownika.

Żeby te same wskazówki obowiązywały przy autokompakcji, dodaj do projektowego CLAUDE.md sekcję # Compact instructions z jedną lub dwiema liniami, na przykład „When compacting, keep test output and code changes.”

Zasada, której trzyma się ten serwis: zacznij od domyślnego modelu narzędzia, dostrój effort, zanim zmienisz model, a model zmieniaj tylko wtedy, gdy każą ci to twoje własne ewaluacje.

Na kanale wydań latest (v2.1.280 i nowsze) Claude Code domyślnie używa Claude Opus 5.5 z effort medium na każdym płatnym planie i w Anthropic API. Anthropic twierdzi, że „Opus 5.5 at medium matches or exceeds Opus 5 at high” w swoich ewaluacjach programistycznych. Kanał stable (v2.1.274 na 2026-09-26) nadal daje części planów starsze domyślne modele, więc uruchom /model i sprawdź, na czym jesteś. Aktualne nazwy i ceny są w hubie modeli.

  1. Ustawiaj effort pod zadanie, nie pod cały dzień. /effort low do zawężonych edycji, w których liczy się czas odpowiedzi; medium do zwykłej pracy; /effort high lub xhigh, gdy zadanie nie przechodzi na domyślnym poziomie. Na Opus 5.5 i Fable 5.1 z kluczem API lub w subskrypcji zmiana zachowuje cache, więc korekta w trakcie zadania jest tam tania. Na Amazon Bedrock i w Agent Platform w Google Cloud zmiana kosztuje chybienie w cache.

  2. Użyj ultrathink na jedną trudną turę. Słowo kluczowe dodaje w kontekście instrukcję głębszego rozumowania tylko dla tej tury; poziom effort wysyłany do API się nie zmienia. „think” i „think hard” to zwykły tekst promptu.

  3. Zmieniaj model na granicy zadań. Każdy model ma własny cache, więc /model w trakcie zadania czyta całą historię od nowa. /model zapisuje też wybór jako domyślny dla nowych sesji; w selektorze naciśnij s na wierszu, żeby zmienić model tylko w tej sesji. Wybierz model, zanim zaczniesz: Claude Sonnet 5 lub Claude Haiku 4.5, gdy dominuje koszt, i świadomie Claude Fable 5.1 (/model fable) do rozumowania o najdłuższym horyzoncie. Fable nigdy nie jest modelem domyślnym i zależnie od planu i typu licencji (seat) może być rozliczany z kredytów użycia. Jeśli chcesz stałego wyboru na terminal, uruchamiaj claude --model sonnet albo ustaw ANTHROPIC_MODEL.

  4. Przypnij pomocników do taniego modelu. Ustaw model: haiku w subagentach, które uruchamiają testy lub streszczają logi, albo CLAUDE_CODE_SUBAGENT_MODEL=haiku dla subagentów bez własnego modelu. Pole model w definicji ma pierwszeństwo przed zmienną.

Na Opus 5.5 i modelach Fable myślenia nie da się wyłączyć; obniż effort. MAX_THINKING_TOKENS dotyczy tylko modeli ze stałym budżetem myślenia, na przykład Opus 4.6 i Sonnet 4.6, po ustawieniu CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1. Modele działające z adaptacyjnym rozumowaniem, w tym Opus 5.5, Sonnet 5 i modele Fable, ignorują wartości niezerowe.

Fast mode sprawia, że Opus jest „up to 2.5x faster at a higher cost per token” (strona Anthropic o fast mode, sprawdzona 2026-09-26). Działa na Opus 5.5, Opus 5 i Opus 4.8, wyłącznie w Anthropic API lub w subskrypcji Claude, a w subskrypcji jest rozliczany z kredytów użycia, nawet gdy w planie zostało jeszcze użycie. Używaj go przy debugowaniu na żywo, gdy czekasz na każdą odpowiedź. Włącz go przez /fast na początku sesji: pierwsza szybka tura czyta historię bez cache po stawkach fast mode, więc włączenie go głęboko w długiej sesji kosztuje najwięcej. Gdy jest włączony, obok promptu widać ikonę ↯, a ustawienie domyślnie przechodzi na kolejne sesje, więc po skończonej pracy wyłącz je przez /fast off.

Grupuj powiązaną pracę w jednym przebiegu Claude Code

Dział zatytułowany „Grupuj powiązaną pracę w jednym przebiegu Claude Code”

Dziesięć małych promptów, z których każdy odbudowuje kontekst, kosztuje więcej niż jeden zaplanowany przebieg. Najpierw wylicz cele, potem pracuj partiami z bramką testów, żeby regresja zatrzymała partię, zanim się rozleje. Analizę kodu zapisz raz do pliku, na przykład docs/api-analysis.md, i zaczynaj od niego kolejne sesje.

Przy dużej mechanicznej zmianie w dziesiątkach plików wbudowany skill /batch dzieli pracę na 5 do 30 jednostek, każdą we własnym git worktree; zobacz operacje wsadowe.

Do jednorazowych zadań tryb print pomija sesję interaktywną: claude -p "Convert this JSON to YAML" < config.json > config.yaml. Dodaj --max-budget-usd 2.00, by zatrzymać się na limicie wydatków, i --output-format json, by logować usage i total_cost_usd; limity w CI opisuje kontrola kosztów.

Skąd wiesz, że tańsza sesja nie kosztowała jakości?

Dział zatytułowany „Skąd wiesz, że tańsza sesja nie kosztowała jakości?”

Oszczędność, która daje kod odrzucany przez testy, tylko przesuwa koszt na poprawki. Traktuj każdą zmianę ustawień jak eksperyment z bramką jakości:

  1. Nie ruszaj bramek. Ten sam zestaw testów, sprawdzanie typów, lint i agent recenzujący muszą przechodzić z tą samą częstością przed i po obniżeniu effort czy przeniesieniu pomocnika na Haiku. Jeśli brakuje bramki, dodaj ją przed strojeniem; strojenie bez niej to zgadywanie.
  2. Podaj Claude cel weryfikacji w prompcie. Wskaż polecenie testów i warunek akceptacji („all tests in src/api pass, no new lint warnings”). Claude sprawdzi wtedy swoją pracę, zanim cokolwiek przeczytasz, a nieprzechodząca bramka objawi się zatrzymaną partią, a nie niespodzianką w review.
  3. Porównuj na stałym zestawie zadań. Weź pięć niedawnych zadań ze znanym dobrym wynikiem. Uruchom je na starych i nowych ustawieniach i porównaj trzy liczby: odsetek przejść przez bramki, liczbę tur do zielonego wyniku i koszt z /usage albo total_cost_usd. Przyjmij tańsze ustawienie tylko wtedy, gdy odsetek przejść się utrzymuje.
  4. Patrz na koszt zaakceptowanej zmiany, a nie na sam koszt. W ciągu dwóch tygodni dziel wydatki przez scalone, niecofnięte pull requesty. Metoda jest w ekonomii oprogramowania budowanego przez agentów, a telemetria, która ją zasila, w kontroli kosztów.

Za ustawienia swojej sesji odpowiadasz ty. Za politykę modeli i effort w zespole odpowiada tech lead i to on zatwierdza jej zmianę na podstawie powyższego porównania.

  • Każda tura po przerwie jest wolna i droga. Cache wygasł. Na kluczu API żyje pięć minut. Ustaw promptCacheTtl na 1h, jeśli przerwy są regularne, albo po długiej przerwie zrób /clear i zacznij od nowa, zamiast wznawiać ogromną sesję.
  • /usage pokazuje wiele chybień w trakcie zadania. Odczytaj prawdopodobną przyczynę w wierszu Prompt cache (main). Zwykle winne są: zmiana /model, zmiana effort na Amazon Bedrock lub w Agent Platform w Google Cloud, przełączanie trybu planowania przy opusplan albo, przy wyłączonym tool search, serwer lub plugin z MCP dodany w trakcie sesji. Rozstrzygnij te wybory przed następnym zadaniem.
  • Edycja CLAUDE.md wydaje się ignorowana. Zmiana działa po /clear, /compact lub restarcie.
  • Kompakcja wycięła coś potrzebnego. Uruchom /rewind do tury sprzed kompakcji, jeśli jest jeszcze w historii checkpointów, albo powtórz utracone fakty. Następnym razem podaj /compact jawne listy „zachowaj” i „odrzuć” i dodaj do CLAUDE.md sekcję # Compact instructions.
  • Tańszy model lub niższy effort ciągle oblewa testy. Cofnij się o jeden stopień (najpierw effort, potem model) dla tego typu zadania i dopisz ten typ do zestawu porównawczego, żeby następna próba strojenia startowała od dowodów.
  • Na rachunku jest fast mode, o którym zapomniałeś. Poszukaj ikony ↯ i uruchom /fast off. Administrator może ustawić fastModePerSessionOptIn, żeby fast mode resetował się w każdej sesji.
  • Wydatki rosną, choć nikt nic nie pisze. /loop, zadanie cykliczne albo sprawdzenie celu uruchamiają tury z pełnym kontekstem. Przejrzyj wiersze Loops w /usage i anuluj te, których nikt nie czyta.