Przepływ pracy debugowania w CLI

Twoje CI właśnie pokazało czerwony status. Komunikat błędu to “Cannot read properties of undefined (reading ‘map’)” ze stosem wywołań dotykającym sześciu plików w dwóch serwisach. Twój kolega mówi, że wczoraj to działało. Git blame wskazuje na commit merge z 40 zmienionymi plikami. Możesz spędzić następne dwie godziny dodając console.log. Albo możesz przekierować błąd do Claude Code i mieć analizę przyczyny źródłowej w pięć minut.

Programiści, którzy najszybciej debugują z Claude Code, nie tylko wklejają błędy i proszą o poprawki. Używają systematycznego przepływu pracy: dają Claude’owi błąd z pełnym kontekstem, pozwalają mu prześledzić ścieżkę wykonania w kodzie, weryfikują diagnozę przed zastosowaniem poprawki i piszą test zapobiegający regresji. Ta lekcja opisuje ten przepływ pracy.

Co wynosisz z tej lekcji

Przepływ pracy od komunikatu błędu do przyczyny źródłowej w minuty
Prompty, które dają Claude wystarczający kontekst do diagnozy prawdziwych bugów, nie tylko zgadywania
Technika pipe-and-diagnose dla błędów produkcyjnych
Wzorce trybu headless dla automatycznego triażu błędów w CI

Przepływ pracy debugowania

Daj Claude’owi pełny kontekst błędu

Jakość diagnozy zależy całkowicie od jakości wejścia. Gołe komunikaty błędu dają ci zgadywanie. Stos wywołań z kontekstem daje ci przyczynę źródłową.

Prompt do skopiowania dla diagnozy bugów:

I have a bug. Here's everything I know:

Error: [paste the full error message and stack trace]

When it happens: [describe the trigger -- user action, API call, etc.]
How often: [always, intermittently, only in production, etc.]
What changed recently: [recent deploys, dependency updates, config changes]

Trace through the code path from the entry point to where
the error occurs. Read every file in the stack trace.
Tell me the root cause before suggesting any fix.

Pozwól Claude’owi prześledzić ścieżkę wykonania

Claude czyta pliki w stosie wywołań, śledzi importy, sprawdza typy i buduje obraz tego, co poszło nie tak. Nie śpiesz się z tym krokiem — to właśnie w trakcie śledzenia znajduje się bug.
```
Trace the request flow from src/routes/orders.ts line 47
through the service layer and into the database query.
Show me the data shape at each step. Where does the value
become undefined?
```

Zweryfikuj diagnozę przed zastosowaniem poprawki

Claude może zidentyfikować błędną przyczynę źródłową, szczególnie dla sporadycznych bugów. Przed napisaniem jakiejkolwiek poprawki zweryfikuj.

You're saying the bug is in the middleware that parses the
JWT token. Prove it: show me the specific line where the
undefined value originates, and explain why it only happens
for users with expired sessions.

Napraw buga i napisz test regresji

Fix the bug. Then write a test that reproduces the exact
scenario that caused it -- expired session token with a
valid user ID. The test should fail without the fix and
pass with it.

Sprawdź podobne bugi w innych miejscach

Search the codebase for other places that use the same
pattern that caused this bug. Are there other middleware
functions that assume the token payload is always present?
List them so I can fix them proactively.

Przekierowywanie błędów bezpośrednio do Claude

Projekt Claude Code oparty na terminalu oznacza, że możesz przekierować output błędów bezpośrednio do niego. To najszybsza droga od błędu do diagnozy.

Z twojego serwera deweloperskiego

# Przekieruj test, który nie przechodzi, bezpośrednio do Claude
npm test -- --run tests/services/order.test.ts 2>&1 | \
  claude -p "This test is failing. Read the test file and the \
  source code it tests. Diagnose the root cause and fix it."

Z logów produkcyjnych

# Weź ostatnie błędy i przeanalizuj je
grep "ERROR" /var/log/app/production.log | tail -50 | \
  claude -p "Analyze these production errors. Group them by \
  root cause. For each group, identify the source file and \
  suggest a fix. Prioritize by frequency."

Z outputu CI

# Przekieruj output niepowodzenia CI do Claude
gh run view 12345 --log-failed | \
  claude -p "This CI run failed. Identify which test failed, \
  read the relevant source code, and explain what broke. \
  Check recent commits to see if a specific change caused it."

Prompt do skopiowania dla automatycznego triażu błędów CI:

claude -p "Read the failing test output below and diagnose
the root cause. Read the test file and the source files it
imports. If the fix is straightforward, apply it and run the
tests again to verify.

$(npm test 2>&1)" --output-format json

Debugowanie specyficznych typów bugów

Race conditions

Race conditions są notorycznie trudne do debugowania, ponieważ zależą od timingu. Daj Claude’owi pełny obraz.

We have an intermittent test failure in tests/services/payment.test.ts.
It passes 9 out of 10 times. The error is "expected 'processing'
but received 'completed'".

Read the test and the payment service. Look for any async operations
that might resolve in a different order depending on timing.
Check for missing awaits, unhandled promises, or shared mutable state.

Wycieki pamięci

Our Node.js service memory grows from 200MB to 1.2GB over 6 hours,
then crashes with OOM. I took heap snapshots at startup and at
the 4-hour mark.

Read our event handler code in src/handlers/ and look for:
1. Event listeners that are added but never removed
2. Arrays or maps that grow without bounds
3. Closures that capture large objects
4. Streams that are opened but never closed

”Działa lokalnie, ale nie działa w CI”

This test passes on my machine but fails in CI. Here's the CI output:
[paste output]

Here's my local Node version: v20.11.0
CI uses: v20.10.0

Read the test file and look for:
1. Environment-dependent code (paths, timezones, locale)
2. Timing-sensitive assertions
3. Missing test fixtures or setup steps
4. Order-dependent tests that assume state from a previous test

Używanie sub-agentów do złożonego debugowania

Kiedy bug obejmuje wiele części systemu, użyj sub-agentów do równoległego badania bez zapełniania głównego kontekstu nieistotnym kodem.

Use sub-agents to investigate this bug from multiple angles:

1. Trace the request from the API gateway through the auth
   middleware to the order service. Find where the user object
   loses its organization_id field.

2. Check the database migration history for the organizations
   table. Was a column recently renamed or made nullable?

3. Search for all places in the codebase that read
   user.organization_id and check if any of them handle
   the undefined case.

Report findings so we can pinpoint the root cause.

Każdy sub-agent działa we własnym kontekście, czyta tyle plików, ile potrzeba i raportuje zwięzłe podsumowanie. Twoja główna sesja pozostaje czysta dla faktycznej poprawki.

Automatyzacja debugowania w trybie headless

Dla zespołów, które chcą automatycznego triażu błędów, tryb headless zamienia Claude Code w pipeline debugowania.

# Automatyczna analiza błędów w CI
claude -p "Analyze the test failures in this output and
categorize them:
1. Flaky tests (timing-dependent, order-dependent)
2. Real bugs (code logic errors)
3. Environment issues (missing config, wrong versions)

For real bugs, identify the root cause file and line number.
For flaky tests, suggest how to make them deterministic.

$(cat test-output.log)" \
  --output-format json > debug-report.json

To generuje ustrukturyzowany raport JSON, który twój pipeline CI może opublikować jako komentarz do PR lub wysłać na Slack.

Czytanie kontekstu błędu z Git

Claude Code jest świadomy git. Użyj tego do debugowania regresji.

This bug started appearing after last Tuesday's deploy. Run:
git log --oneline --after="2026-02-03" -- src/services/

Then read the diffs for each commit that touched the services
directory. Which commit introduced the change that could cause
"TypeError: Cannot read property 'id' of null" in the order
processing flow?

Dla głębszej analizy:

Run git bisect between the last known good commit (abc123)
and the current HEAD. The test that reproduces the bug is
tests/services/order.test.ts. Find the exact commit that
introduced the regression.

Kiedy to nie działa

Claude naprawia symptom, ale nie przyczynę źródłową. To się dzieje, gdy wklejasz tylko komunikat błędu bez kontekstu. Zawsze dołączaj: stos wywołań, kiedy to się dzieje, co ostatnio się zmieniło i jak często to występuje. Im więcej kontekstu, tym dokładniejsza diagnoza.

Poprawka psuje coś innego. Claude naprawił buga, ale nie sprawdził skutków ubocznych. Po każdej poprawce uruchom pełny zestaw testów, nie tylko test dla buga. Dodaj to do swojego promptu: “After fixing the bug, run the full test suite and show me any new failures.”

Claude nie może odtworzyć buga z opisu. Najpierw napisz test, który nie przechodzi. “Before debugging, write a test that reproduces this exact scenario. Run it to confirm it fails. Then trace the code to find the root cause.” Test, który nie przechodzi, to najbardziej jednoznaczny raport o błędzie.

Extended thinking pomaga przy złożonych bugach. Dla bugów obejmujących wiele plików lub subtelne problemy z timingiem, ustaw poziom wysiłku na wysoki przed debugowaniem. Claude będzie rozumował przez problem bardziej starannie przed zasugerowaniem poprawki.

Kontekst wypełnia się podczas długiej sesji debugowania. Jeśli czytałeś wiele plików do śledzenia buga, uruchom /compact Focus on the bug diagnosis and the fix. Drop file contents we already analyzed. Alternatywnie, jeśli masz jasną diagnozę, rozpocznij świeżą sesję tylko z diagnozą i pozwól Claude’owi zaimplementować poprawkę od zera.

Co dalej

Twój bug jest naprawiony i test regresji jest na miejscu. Teraz wzmocnij resztę swojego zestawu testów, aby łapać bugi zanim trafią na produkcję.

Testing Generuj kompleksowe zestawy testów, które łapią bugi przed wysłaniem

Refactoring Kiedy debugowanie ujawnia problemy strukturalne, refaktoryzuj je systematycznie