Przepływy debugowania

Jest 2 w nocy. Twój endpoint przetwarzania płatności zwraca sporadyczne błędy 500. Logi błędów pokazują “Cannot read property ‘amount’ of undefined”, ale obiekt jest wyraźnie zdefiniowany trzy linie wyżej. Wpatrujesz się w kod od 40 minut. Błąd to race condition między dwiema operacjami asynchronicznymi, a Claude Code może go znaleźć w 90 sekund — jeśli dasz mu odpowiedni kontekst.

Co wyniesiesz z tego artykułu

• Systematyczny przepływ debugowania, który działa dla każdego błędu
• Prompty do analizy śladów błędów, które identyfikują przyczyny źródłowe
• Strategie bisection do znajdowania commita, który wprowadził błąd
• Wzorce parsowania logów do debugowania produkcyjnego

Przepływ debugowania

1. Przechwyć kontekst błędu Przekieruj błąd bezpośrednio do Claude Code:

   cat error.log | claude -p "Analyze this error. What is the root cause and which file should I look at first?"

2. Kontynuuj interaktywnie dla głębszego badania

   claude -c

   Teraz jesteś w tej samej sesji z załadowanym kontekstem błędu. Poproś Claude o odczytanie odpowiednich plików.

3. Odtwórz problem

   Run the failing test: npx jest src/payments/__tests__/process.test.ts
   Show me the exact line where it fails and the state of all variables at that point.

4. Zidentyfikuj przyczynę źródłową

   ultrathink about why this fails intermittently. The error only happens under load.
   Read the async flow in processPayment() and identify any race conditions.

5. Napraw i zweryfikuj

   Fix the race condition. Then run the full test suite to make sure nothing else broke.

Analiza śladów błędów

Diagnoza śladu stosu

Here is a stack trace from production:

[paste stack trace]

1. Identify the root cause (not just the symptom)
2. Trace the call chain from the error back to the original trigger
3. Read the source files involved and explain what went wrong
4. Suggest a fix that addresses the root cause, not just the symptom

Wskazówka

Gotowy do skopiowania prompt do analizy błędów produkcyjnych:

Analyze this production error:

[paste error/stack trace]

Do NOT suggest generic fixes. Instead:
1. Read the actual source files mentioned in the trace
2. Identify the exact line and condition that triggers the error
3. Explain WHY it happens (timing, data shape, edge case)
4. Write a test that reproduces the error
5. Implement the fix
6. Verify the test now passes

Debugowanie błędów typów

This TypeScript error makes no sense to me:

[paste TypeScript error]

Read the file and its imports. Trace the type through every transformation
to find where the type mismatch actually originates. It might not be in the
file the error points to.

Wzorce błędów asynchronicznych/współbieżnych

ultrathink about this intermittent failure:

The test passes 9 out of 10 times. The failure is:
[paste failure output]

This smells like a race condition. Read the async flow in the failing test
and the code it exercises. Identify:
1. Any shared mutable state
2. Any missing await calls
3. Any operations that assume sequential execution
4. Any cleanup that runs before async operations complete

Git bisection z Claude Code

Gdy wiesz, że błąd nie istniał w poprzedniej wersji:

The /api/search endpoint was working correctly in commit abc123 (2 weeks ago)
but is broken in HEAD. Help me bisect:

1. Run: git log --oneline abc123..HEAD -- src/api/search/
2. Identify the most likely commit to have introduced the regression
3. Check out that commit and run the relevant test
4. If the test passes, the bug is in a later commit. If it fails, it is in this commit or earlier.
5. Narrow down to the exact commit using binary search.

Wskazówka

Gotowy do skopiowania prompt do automatycznej bisection git:

# Run this in your terminal
git bisect start HEAD abc123
git bisect run npx jest src/api/search/search.test.ts --bail

# Then ask Claude to analyze the result
git bisect log | claude -p "Analyze this bisect log. Which commit introduced the regression and what changed in that commit?"

Parsowanie logów

Analiza logów produkcyjnych

# Pipe filtered logs to Claude Code
grep "ERROR\|WARN" /var/log/app.log | tail -100 | \
  claude -p "Categorize these errors. Which are most frequent? Which are likely related to the payment processing bug we are investigating?"

Debugowanie wydajności

Our API response times increased from 50ms to 800ms after the last deploy.
Run these diagnostics:

1. Check git diff HEAD~1 for changes to database queries
2. Look for any new N+1 query patterns in the changed files
3. Check if any new middleware was added to the request pipeline
4. Look for blocking I/O operations that could explain the latency

Focus on database query changes first -- that is the most common cause.

Kiedy coś idzie nie tak

Claude nie może odtworzyć błędu: Niektóre błędy manifestują się tylko w środowiskach produkcyjnych. Jeśli Claude nie może odtworzyć problemu lokalnie, podaj logi produkcyjne, szczegóły środowiska i konkretne dane, które powodują problem. Rozważ użycie --append-system-prompt, aby dać Claude kontekst produkcyjny.

Sesja debugowania wyczerpuje kontekst: Długie sesje debugowania akumulują dużo odczytów plików i wyników testów. Użyj /compact Keep all error traces, test output, and diagnostic results, aby zachować ważny kontekst, zwalniając jednocześnie miejsce.

Claude naprawia objaw, nie przyczynę: To się zdarza, gdy opisujesz objaw bez kontekstu. Zamiast “fix the null pointer error”, powiedz “the user object is null because the async fetch races with the render. Fix the race condition, not the null check.”

Bisection zawodzi na niestabilnych testach: Jeśli test jest sporadyczny, git bisect run da niepoprawne wyniki. Uruchom test wielokrotnie w każdym punkcie bisection: git bisect run bash -c 'for i in 1 2 3; do npx jest test.ts || exit 1; done'.

Co dalej

• Inżynieria promptów — Pisz skuteczniejsze prompty do debugowania
• Automatyzacja przeglądów — Wyłapuj błędy zanim trafią na produkcję
• Mistrzostwo terminala — Skonfiguruj terminal pod przepływy debugowania