Debugowanie z Claude Code w terminalu

Debugowanie z Claude Code to czterokrokowa pętla w terminalu: przekaż błąd potokiem razem z kontekstem, zbadaj go w trybie planowania, w którym nic nie jest edytowane, udowodnij przyczynę źródłową testem, który nie przechodzi, a potem naprawiaj, aż ten test i cały zestaw testów przejdą. Regresje i awarie CI obsługują git bisect run oraz headless claude -p.

Aktualność dokumentacji

Dotyczy: Claude Code 2.1.283 (kanał wydań latest), sprawdzone 26 września 2026. Każdą flagę claude na tej stronie sprawdzono w claude --help tej wersji. stable to 2.1.287 na 2026-10-12, czyli nowsze wydanie niż sprawdzone. Resztę sprawdzono tylko na 2.1.283; na innej wersji zajrzyj do claude --help, czy jest tam --permission-prompts, zanim użyjesz przykładu triage w CI. Jeśli nie masz jeszcze zainstalowanego Claude Code, zacznij od przewodnika instalacji; resztę etapu testowania opisuje hub Test i debugowanie.

Ta strona jest dla programistów, którzy debugują w terminalu z Claude Code, i dla tech leadów, którzy decydują, czego ma dowodzić pull request z poprawką błędu. Sytuacja: CI świeci na czerwono z komunikatem Cannot read properties of undefined (reading 'map'), stack trace przechodzi przez sześć plików w dwóch serwisach, a ostatni merge zmienił 40 plików. Wklejasz błąd i prosisz o poprawkę. Claude dodaje sprawdzenie na null, CI robi się zielone, a tydzień później ten sam błąd wraca z innego miejsca wywołania.

Agent nie zawiódł jako programista. Poproszono go o edycję, zanim ktokolwiek znał przyczynę. Poniższy przepływ każe mu szukać, dopóki przyczyna nie zostanie udowodniona, a dowodem jest test, który sprawdzisz bez czytania każdej linii poprawki.

Co zyskujesz z debugowania w terminalu

• Sposób na przekazanie Claude Code wyjścia testów, serwera, logów i CI potokiem, bez kopiowania
• Etap badania tylko do odczytu w trybie planowania i regułę, kiedy go opuścić
• Dziesięć promptów do skopiowania: zgłoszenie błędu, ograniczona poprawka, stack trace z produkcji, błędy typów, wyścigi, rosnące zużycie pamięci, awarie tylko w CI, podejrzane commity bez znanego dobrego, równoległe śledztwo z subagentami i triage CI
• Przepis na git bisect run, który radzi sobie z niestabilnymi testami
• Listę dowodów, na podstawie której recenzent zatwierdzi poprawkę bez czytania całego diffu
• Sposoby wyjścia z sześciu typowych awarii debugowania z Claude Code

Jak działa pętla debugowania w Claude Code?

Każda faza ogranicza, co Claude może zmienić. To ograniczenie, a nie model, przerywa cykl „napraw, zepsuj, napraw”.

Faza	Tryb Claude Code	Claude może zmienić	Kończysz fazę, gdy
1. Przekazanie awarii	claude -p z potokiem, potem claude -c	nic	błąd, wyzwalacz i ostatnie zmiany są w kontekście
2. Śledztwo	tryb planowania (claude --permission-mode plan lub /plan w sesji)	nic	Claude wskazuje jedną przyczynę z plikiem, linią i warunkiem
3. Dowód przyczyny	twój zwykły tryb, tylko pliki testów	nowy test	test nie przechodzi z powodu, który Claude wskazał
4. Poprawka i weryfikacja	twój zwykły tryb	pliki wskazane w diagnozie	nowy test i cały zestaw przechodzą

1. Przekaż awarię razem z kontekstem

   Przekaż wyjście potokiem. Claude Code czyta standardowe wejście razem z promptem, więc błąd nie przechodzi przez schowek:

   npm test -- --run tests/services/order.test.ts 2>&1 | \
     claude -p "This test fails. Read the test and the source it imports. \
   Name the most likely root cause and the file to open first. Do not edit anything."

   Następnie uruchom claude -c, żeby kontynuować tę samą rozmowę interaktywnie, z wyjściem nadal w kontekście. Jeśli wiesz więcej, niż pokazuje log, poświęć 30 sekund na ustrukturyzowane zgłoszenie:

   Prompt do skopiowania: zgłoszenie błędu, które daje przyczynę źródłową

   I have a bug. Here is everything I know.
   
   Error and stack trace: [paste them in full]
   Trigger: [the user action, request or job that causes it]
   Frequency: [always / about 1 in 10 / only in production]
   Recent changes: [deploys, dependency bumps, config changes, with dates]
   
   Do not edit any file yet. Read every file in the stack trace and follow
   the imports from the entry point to the line that throws. Show me the
   data shape at each hop and the first hop where it differs from what the
   code expects. End with one root cause, stated as file:line plus the
   condition that triggers it, and how confident you are.

2. Prowadź śledztwo w trybie planowania

   Uruchom sesję w trybie planowania albo naciskaj Shift+Tab, aż wskaźnik trybu pokaże tryb planowania. Claude może czytać i przeszukiwać pliki, ale nie może ich edytować:

   claude --permission-mode plan

   Proś o prześledzenie, nie o poprawkę: „Prześledź żądanie od src/routes/orders.ts, linia 47, przez warstwę serwisów aż do zapytania. Gdzie items staje się undefined?”. Zanim przyjmiesz odpowiedź, zakwestionuj ją: „Udowodnij to. Pokaż linię, w której powstaje ta wartość, i wyjaśnij, dlaczego dzieje się to tylko u użytkowników z wygasłą sesją”. Dwie wiarygodne przyczyny oznaczają, że wciąż jesteś w fazie 2.

3. Udowodnij przyczynę testem, który nie przechodzi

   Diagnoza to twierdzenie. Test, który nie przechodzi z podanego powodu, to dowód. Poproś Claude o napisanie testu reprodukującego, uruchomienie go i pokazanie komunikatu błędu. Jeśli test nie przechodzi z innego powodu, diagnoza jest błędna: wróć do kroku 2, zamiast łatać dalej.

4. Popraw, a potem uruchom wszystko

   Wyjdź z trybu planowania i daj Claude poprawkę, której nie może rozszerzyć:

   Prompt do skopiowania: ograniczona poprawka

   The root cause is the one we proved with the new failing test.
   Fix it in the files the diagnosis named and nowhere else.
   
   Rules:
   - Do not edit the new test or any existing test.
   - Do not add a null check or try/catch that hides the symptom;
     fix the place where the bad value is produced.
   - Run the new test, then the full suite (npm test), and paste
     the summary lines of both runs.
   - Finish with `git diff --stat` and one sentence per changed file
     explaining why it had to change.

   Na koniec zadaj jeszcze jedno pytanie: „Search the codebase for other callers that make the same assumption, and list them with file:line. Do not change them.”. Ta lista to następne zgłoszenie, a nie część tego diffu.

Nie pozwól Claude przejść testu przez jego edycję

Reguła „nie edytuj testu” w prompcie to prośba, a nie blokada. Żeby na czas poprawki dodać zabezpieczenie, wpisz regułę odmowy, na przykład "Edit(**/*.test.ts)", do permissions.deny w .claude/settings.json. Blokuje ona narzędzia do edycji plików, ale nie polecenie Bash, które nadpisze plik (sed -i, heredoc, git checkout); tę lukę zamykają reguły sandboxa i kontrole CI ze strony o ochronie wyroczni. Pełny zestaw blokad, łącznie z regułami sandboxa i kontrolami CI poza diffem, opisuje strona o ochronie wyroczni.

Jak przekazać logi i wyjście CI do Claude Code?

Potok działa wszędzie tam, gdzie błąd już się wypisuje. Filtruj przed przekazaniem: sto istotnych linii pozwala Claude pogrupować błędy według przyczyny, a sto tysięcy surowych linii zostanie tylko streszczone.

Logi produkcyjne:

grep -E "ERROR|WARN" /var/log/app/production.log | tail -100 | \
  claude -p "Group these errors by root cause. For each group give the count, \
the source file and line, and whether it relates to the payment timeout we are \
investigating. Order by count."

Nieudany przebieg GitHub Actions (z flagą --log-failed CLI gh wypisuje tylko logi kroków, które zawiodły):

gh run view RUN_ID --log-failed | \
  claude -p "Identify the failing test, read its source and the code it tests, \
and explain what broke. Check the commits in this run for the change that caused it." \
  --allowedTools "Read,Grep,Glob,Bash(git show:*),Bash(git log:*)"

Zastąp RUN_ID numerem z gh run list.

Błędy produkcyjne prosto z Sentry. Gdy stack trace żyje w systemie śledzenia błędów, a nie w pliku logu, podłącz serwer MCP Sentry, żeby Claude przeczytał zgłoszenie, jego breadcrumbs i wydanie, w którym błąd się pojawił:

claude mcp add -s project --transport http sentry https://mcp.sentry.dev/mcp
claude mcp login sentry

Konfigurację Grafany, Datadoga i PostHoga oraz zakresy tylko do odczytu, które warto nadać, opisuje strona o MCP do obserwowalności.

Jakie prompty w Claude Code działają na powracające typy błędów?

Stack trace z produkcji

Ogólny prompt daje ogólną odpowiedź. Ten zabrania ogólnej poprawki i kończy się testem:

Prompt do skopiowania: stack trace z produkcji

Analyze this production error:

[paste the stack trace]

Do not suggest a generic fix. Instead:
1. Read the source files named in the trace, at the deployed commit
   (git log -1 --format=%H on the release tag if you need it).
2. Identify the exact line and the condition that triggers the error.
3. Explain why it happens: timing, data shape or an edge case.
4. Write a test that reproduces it and run it to show it fails.
5. Stop and wait for me before implementing the fix.

Błędy typów wskazujące niewłaściwy plik

Prompt do skopiowania: błąd typu w niewłaściwym pliku

This TypeScript error points at src/api/orders.ts, but I think the cause
is elsewhere:

[paste the tsc output]

Trace the type through every transformation from where it is declared
to where the error fires. Tell me the first place it diverges from what
the caller expects. That is the file to fix.

Wyścigi i sporadyczne awarie

Niejasny prompt daje niejasną teorię. Opisz awarię precyzyjnie i daj Claude listę rzeczy, które faktycznie je powodują:

Prompt do skopiowania: sporadycznie padający test

tests/services/payment.test.ts fails about 1 run in 10 with
"expected 'processing' but received 'completed'".

Do not edit anything yet. Read the test and src/services/payment.ts.
List every async operation whose order could change between runs, and check for:
1. shared mutable state between tests or between requests
2. a missing await
3. code that assumes two async calls finish in order
4. cleanup (afterEach, finally) that runs before pending work completes

Then write a loop that runs this test 50 times
(for i in $(seq 50); do npx vitest run tests/services/payment.test.ts || break; done)
and tell me which of your hypotheses the failure output supports.

Przy wyścigach, które opierają się pierwszemu podejściu, zwiększ głębokość rozumowania, zanim zmienisz model. Od v2.1.280 domyślnym modelem Claude Code jest Claude Opus 5.5 i działa on z effort medium; /model pokaże, czego używa twoja instalacja. Wpisz ultrathink w jednym prompcie, żeby pogłębić pojedynczą turę, albo uruchom /effort high (lub wystartuj z claude --effort xhigh) dla całej sesji. Kompromisy opisuje strona o głębokim rozumowaniu, a aktualne ustawienia domyślne i ceny przegląd modeli.

Rosnące zużycie pamięci

Snapshoty sterty to często setki megabajtów JSON-a, a wczytanie jednego zalewa kontekst. Najpierw porównaj je sam: otwórz oba w Chrome DevTools, w panelu Memory przełącz się na widok Comparison i wklej do promptu główne retainery.

Prompt do skopiowania: rosnące zużycie pamięci

Our Node.js service grows from 200 MB to 1.2 GB over six hours, then
dies with an out-of-memory error. Do not open the .heapsnapshot files;
here is the comparison summary (start vs 4h, top retainers):

[paste the Comparison view rows]

Read src/handlers/ and look for listeners added without removal, maps or
arrays that grow without a bound, closures that hold request objects,
and streams that are opened but never closed. Rank the candidates by how
well each one explains growth that is steady rather than stepped and
matches the retainers above. Then write a load test or script that
reproduces the steady growth, and show before/after heap numbers.

Lokalnie przechodzi, w CI nie

Prompt do skopiowania: awaria tylko w CI

This test passes locally and fails in CI. CI output:

[paste the output, or pipe it in with gh run view --log-failed]

Compare the environments before reading the code: run node --version and
print the TZ and LANG variables here, then read .github/workflows/ and
.node-version for what CI uses. Then check the test for timezone and
locale assumptions, absolute paths, timing-sensitive assertions, missing
fixtures, and dependence on a test that runs before it. Name the
difference that explains the failure and show how to reproduce it
locally (for example TZ=UTC npm test).

Jak znaleźć commit, który wszystko zepsuł?

Gdy masz dobry commit i test reprodukujący błąd, niech git szuka, a Claude czyta. Uruchom to w terminalu:

git bisect start HEAD GOOD_SHA
git bisect run npx vitest run src/api/search/search.test.ts
git bisect log | claude -p "Read this bisect log. Name the first bad commit, \
read its diff, and explain which change breaks /api/search." \
  --allowedTools "Read,Grep,Glob,Bash(git show:*),Bash(git log:*)"
git bisect reset

Zastąp GOOD_SHA ostatnim commitem, o którym wiesz, że działał. git bisect run traktuje kod wyjścia 0 jako dobry, a 1–127 (poza 125) jako zły, więc zadziała dowolne polecenie testowe.

Bez znanego dobrego commita zacznij od czasu:

Prompt do skopiowania: podejrzane commity bez znanego dobrego

This bug appeared after last Tuesday's deploy. Run
git log --oneline --since="10 days ago" -- src/services/
and read the diff of each commit. Which one could produce
"TypeError: Cannot read properties of null (reading 'id')" in order
processing? Rank the top three with the line that makes each suspect.

Jak subagenci pomagają przy błędzie, który obejmuje kilka serwisów?

Gdy błąd przecina kilka części systemu, subagenci badają go równolegle, każdy we własnym kontekście, i zwracają podsumowanie. Główna sesja przechowuje tylko wnioski, więc zostaje w niej miejsce na poprawkę. Claude Code ma do takiego przeszukiwania wbudowanego subagenta Explore; możesz też zdefiniować własnych w .claude/agents/ (zobacz stronę o własnych subagentach).

Prompt do skopiowania: równoległe śledztwo z subagentami

Use three subagents in parallel. None of them may edit files.

1. Trace a request from the API gateway through the auth middleware into
   the order service. Find where the user object loses organization_id.
2. Read the migration history for the organizations table. Was a column
   renamed or made nullable in the last month?
3. Find every read of user.organization_id and report which ones handle
   undefined and which do not, as file:line.

Each subagent returns at most 15 lines of findings with file:line
references. Then combine them into one root-cause statement.

Żeby ta pętla była dostępna bez proszenia o nią za każdym razem, zainstaluj skill do debugowania. Claude wczyta go, gdy zgłoszenie błędu pasuje do opisu skilla:

npx skills add obra/superpowers --skill systematic-debugging
# albo
npx skills add mattpocock/skills --skill diagnosing-bugs

Przenośna kopia Superpowers z npx skills add nie ma bootstrapu SessionStart, więc pełna metoda Superpowers nie uruchamia się sama. Jeśli jej potrzebujesz, zainstaluj w sesji Claude Code wtyczkę: /plugin install superpowers@claude-plugins-official.

Sposób sprawdzenia, czy skill rzeczywiście zmienił zachowanie agenta, znajdziesz na stronie o skillach do testowania i debugowania.

Jak analizować awarie CI w trybie headless?

claude -p działa bez człowieka przy klawiaturze, a --output-format json opakowuje odpowiedź w JSON, który kolejny krok może opublikować jako komentarz w pull requeście. Przy triage’u zostaw zadanie tylko do odczytu: zezwól wyłącznie na narzędzia do czytania plików i odrzucaj każde pytanie o uprawnienia, zamiast na nie czekać: robi to --permission-mode dontAsk, u każdego dostawcy, także tam, gdzie -p startuje w trybie auto (od v2.1.285).

Prompt do skopiowania: triage CI tylko do odczytu

# Testy uruchamiają kod gałęzi: ANTHROPIC_API_KEY nie może być w środowisku tego polecenia.
npm test 2>&1 | tail -300 > test-output.txt
# Agent tylko czyta: żadnych hooków, ustawień ani .mcp.json z gałęzi.
claude -p --bare --setting-sources "" --strict-mcp-config \
  --permission-mode dontAsk \
  --allowedTools "Read,Grep,Glob" \
  --permission-prompts none \
  --output-format json \
  "Classify each failure in this test output as a flaky test (timing or order
dependent), a real bug (logic error), or an environment problem (config,
versions, missing service). For real bugs give the root-cause file and line.
For flaky tests say what makes them nondeterministic. Do not propose edits." \
  < test-output.txt > triage.json

--bare --setting-sources "" --strict-mcp-config nie pozwala, by hooki, ustawienia i .mcp.json z gałęzi załadowały się obok klucza; --bare uwierzytelnia się wyłącznie przez ANTHROPIC_API_KEY albo apiKeyHelper, nie przez logowanie do subskrypcji. W workflow uruchamiaj testy i wywołanie claude -p w osobnych zadaniach, a test-output.txt przekazuj jako artefakt, tak jak robi to workflow triage’u testów: krok testów może zapisać do GITHUB_ENV albo GITHUB_PATH i w ten sposób sięgnąć do każdego kolejnego kroku tego samego zadania, także tego z kluczem.

Dwie zasady, gdy uruchamiasz ten triage w workflow. Uruchamiaj go tylko na własnych gałęziach (push albo pull_request z tego samego repozytorium), nigdy z sekretami w wyzwalaczu pull_request_target lub workflow_run, który pobiera kod kontrybutora. Poprawki niech nakłada człowiek albo osobne, zrecenzowane zadanie: zadanie triage’u, które może edytować i pushować, zamienia niestabilny test w niezrecenzowany commit. Pełny workflow, razem z blokiem permissions, opisuje strona o CI/CD w Claude Code.

Jak zweryfikować poprawkę z Claude Code bez czytania każdej linii?

Recenzuj dowody, nie diff. Pull request z poprawką błędu jest gotowy, gdy zawiera tych pięć elementów, a recenzent sprawdza je w tej kolejności:

1. Opis przyczyny źródłowej: jedno zdanie z plikiem, linią i warunkiem wyzwalającym.
2. Czerwony przed zielonym: wynik nowego testu na kodzie bez poprawki (porażka), a potem jego przejście. Sprawdź to sam: odłóż tylko poprawkę przez git stash push -- <pliki wskazane w diagnozie>, uruchom nowy test i zobacz, że pada, potem git stash pop. Zwykłe git stash odkłada też test dopisany do istniejącego pliku testowego, więc czerwony przebieg sprawdza tylko stare testy i niczego nie dowodzi.
3. Cały zestaw testów: linia podsumowania pełnego przebiegu testów po poprawce, nie tylko nowego testu.
4. Zakres: git diff --stat pokazuje tylko pliki wskazane w diagnozie i żaden istniejący test się nie zmienił.
5. Podobne miejsca wywołań: lista innych miejsc z tym samym założeniem, zgłoszona jako dalsza praca.

Programista, który prowadził sesję, zatwierdza punkty 1–3. Recenzent zatwierdza punkty 4 i 5, a cały diff czyta tylko wtedy, gdy punkt 4 pokazuje pliki spoza diagnozy. Te same elementy pasują do zespołowego formatu pakietu dowodów.

Co się psuje przy debugowaniu z Claude Code?

Claude naprawia objaw. Dodaje sprawdzenie na null, a błąd przenosi się gdzie indziej. Przyczyna: poproszono go o poprawkę, zanim przyczyna była znana. Wyjście: cofnij edycję przez /rewind (albo dwukrotne Esc), wróć do trybu planowania i użyj promptu ze zgłoszeniem błędu. Powiedz, co ma zostać naprawione: „the value is null because the fetch races the render; fix the race, not the null check”.

Poprawka psuje coś innego. Uruchomiono tylko nowy test. Wyjście: niech „uruchom cały zestaw i wklej podsumowanie” będzie częścią każdego promptu z poprawką, a CI niech uruchamia pełny zestaw jako wymaganą kontrolę.

Nowy test przechodzi przed poprawką. Test nie reprodukuje błędu, więc niczego nie dowodzi. Wyjście: uruchom go na kodzie bez poprawki (git stash push -- <pliki poprawki>, a nie zwykłe git stash, które może odłożyć też test), a jeśli przejdzie, powiedz Claude: „this test passes without the fix, so it does not reproduce the bug; make it fail for the reason you named”.

Claude edytuje test, żeby przeszedł. Osłabiona asercja albo nowe .skip zmienia czerwony na zielony bez naprawienia czegokolwiek. Wyjście: sprawdź w git diff --stat pliki testów, dodaj regułę odmowy z ostrzeżenia powyżej i uruchom oryginalny test z commita, w którym go napisano.

Bisekcja wskazuje zły commit. Niestabilny test oznacza commity jako dobre lub złe losowo. Wyjście: git bisect reset, a potem niech każdy krok uruchamia test kilka razy, tak żeby jedna porażka oznaczała commit jako zły: git bisect run sh -c 'for i in 1 2 3 4 5; do npx vitest run test.ts || exit 1; done'.

Kontekst zapełnia się logami. Długie sesje gromadzą odczyty plików i wyjście testów, aż wczesne ustalenia wypadają z kontekstu. Wyjście: uruchom /compact keep the root-cause statement, the failing test and its output albo zacznij nową sesję tylko z diagnozą i nazwą testu. Przekazywanie przefiltrowanego wyjścia zamiast całych logów zapobiega temu problemowi.

Dokąd dalej po naprawieniu błędu

Testowanie z Claude Code Zamień test regresyjny w nawyk: generuj zestawy testów, prowadź pętlę red-green i podłącz ją do CI.

Naprawianie błędów sterowane testami Ścisły protokół „najpierw czerwony test”, z testem zablokowanym przed rozpoczęciem poprawki.

Debugowanie z Codexem Ta sama pętla zaczynająca się od reprodukcji w aplikacji Codex, CLI, IDE i chmurze.

Debugowanie w Cursorze Polowanie na błędy w agencie Cursora, z osobnym trybem na każdą fazę i listą dowodów.

Rozwiązywanie problemów z samym Claude Code Gdy problemem jest narzędzie, a nie twój kod: instalacja, uwierzytelnianie, MCP i wydajność.

Refaktoryzacja z Claude Code Gdy błąd odsłania problem strukturalny, usuń go refaktoryzacją pod osłoną właśnie napisanych testów.