Przepływy debugowania

Debugowanie to obszar, w którym Claude Code przekształca się z pomocnego asystenta w niezbędnego detektywa. Łącząc głębokie zrozumienie kodu, systematyczną analizę i zdolność wykonywania poleceń diagnostycznych, Claude może tropić błędy, których znalezienie ręcznie zajęłoby godziny. Ten przewodnik ujawnia przepływy debugowania, które przekształcają frustrujące polowania na błędy w systematyczne sesje rozwiązywania problemów.

Mentalność debugowania

Zrozumienie podejścia Claude do debugowania

Claude podchodzi do debugowania jak doświadczony programista:

Oparte na hipotezach

Formułuje teorie o przyczynach błędów na podstawie objawów, następnie systematycznie testuje każdą hipotezę aż do znalezienia głównej przyczyny.

Oparte na dowodach

Zbiera konkretne dowody poprzez logi, ślady stosu i analizę kodu zamiast robienia założeń.

Systematyczna eksploracja

Śledzi ścieżki wykonania, bada zmiany stanu i identyfikuje dokładny punkt, w którym oczekiwane zachowanie różni się od rzeczywistego.

Uniwersalny przepływ debugowania

1. Odtwórz problem

   "Widzę ten błąd podczas uruchamiania npm test:
   TypeError: Cannot read property 'name' of undefined
   Czy możesz pomóc mi to zdebugować?"

2. Zbierz kontekst

   "Pokaż mi pełny ślad stosu i test
   który nie przechodzi"

3. Sformułuj hipotezy

   "Jakie są możliwe przyczyny tego błędu
   na podstawie struktury kodu?"

4. Testuj systematycznie

   "Dodajmy instrukcje console.log aby śledzić
   przepływ danych i znaleźć gdzie 'name' staje się undefined"

5. Zastosuj poprawkę

   "Na podstawie tego co znaleźliśmy, zaimplementuj poprawkę
   która obsłuży przypadek undefined"

6. Zweryfikuj rozwiązanie

   "Uruchom testy ponownie aby potwierdzić że poprawka działa"

Analiza logów w czasie rzeczywistym

Debugowanie strumieniowe logów

Jedna z najpotężniejszych funkcji debugowania Claude to analiza logów w czasie rzeczywistym:

Podstawowe monitorowanie logów

# Strumieniuj logi do Claude w celu analizy
tail -f app.log | claude -p "Monitoruj błędy i anomalie"

# Claude będzie:
# - Identyfikować wzorce błędów
# - Korelować powiązane zdarzenia
# - Sugerować główne przyczyny
# - Alarmować o krytycznych problemach

Wykrywanie wzorców

# Znajdź określone wzorce w logach
claude "Przeanalizuj ostatnie 1000 linii app.log pod kątem:
- Częstotliwości błędów według typu
- Nietypowych wzorców
- Oznak degradacji wydajności
- Korelacji z ostatnimi wdrożeniami"

Korelacja wielu serwisów

# Koreluj logi między serwisami
claude "Porównaj znaczniki czasu w api.log i database.log
aby znaleźć sekwencję zdarzeń prowadzącą do błędu timeout"

Niestandardowe polecenia analizy logów

Utwórz specjalistyczne polecenia debugowania:

.claude/commands/debug-logs.md

Przeanalizuj dostarczone logi pod kątem: $ARGUMENTS

1. Zidentyfikuj wszystkie typy błędów i ich częstotliwość
2. Znajdź wzorce w czasie występowania błędów
3. Koreluj błędy z określonymi akcjami użytkowników
4. Zidentyfikuj potencjalne główne przyczyny
5. Zasugeruj kroki debugowania dla każdego problemu
6. Utwórz listę priorytetów na podstawie wpływu

Formatuj wynik jako:
- Streszczenie wykonawcze
- Szczegółowe odkrycia
- Zalecane działania

Analiza śladów stosu

Głęboka analiza śladów stosu

Claude doskonale radzi sobie z rozwikłaniem złożonych śladów stosu:

Przepływ śladu stosu

"Oto ślad stosu z produkcji:
[wklej pełny ślad stosu]

Proszę:
1. Zidentyfikuj główną przyczynę
2. Prześledzić przez stos wywołań
3. Znajdź dokładną linię gdzie błąd się rozpoczyna
4. Wyjaśnij co dzieje się na każdym poziomie
5. Zasugeruj poprawki"

Ślady stosu wielojęzyczne

Dla aplikacji z wieloma językami:

"Ten błąd obejmuje backend Python i frontend JavaScript:
[wklej wielojęzyczny ślad stosu]

Prześledzić przepływ błędu przez granice językowe i
zidentyfikować gdzie następuje korupcja danych"

Debugowanie wizualne

Debugowanie oparte na zrzutach ekranu

Claude może analizować błędy UI poprzez zrzuty ekranu:

1. Przechwyć błąd

   • Mac: Cmd+Ctrl+Shift+4
   • Windows: Win+Shift+S
   • Linux: Narzędzie zrzutu ekranu

2. Udostępnij Claude

   "Oto zrzut ekranu pokazujący błąd układu
   [wklej obraz z Ctrl+V]
   Przycisk powinien być wyrównany do lewej ale pojawia się na środku"

3. Otrzymaj ukierunkowaną analizę Claude będzie:

   • Identyfikować problemy CSS
   • Sugerować konkretne poprawki
   • Wskazywać odpowiedni kod
   • Wyjaśniać dlaczego błąd występuje

Debugowanie stanu komponentu

"Komponent React nie przerenderowuje się gdy stan się zmienia.
Oto zrzut ekranu React DevTools pokazujący stan
[wklej zrzut ekranu]

Zdebuguj dlaczego komponent się nie aktualizuje"

Zaawansowane wzorce debugowania

Debugowanie z podróżami w czasie

Odtwórz sekwencję zdarzeń prowadzących do błędu:

Analiza historii Git

"Ten błąd zaczął się pojawiać w zeszłym tygodniu.
Użyj historii git aby:
1. Znaleźć commity z zeszłego tygodnia
2. Zidentyfikować zmiany w kodzie uwierzytelniania
3. Skorelować z momentem gdy użytkownicy zgłosili problemy
4. Wskazać problematyczny commit"

Odtwarzanie stanu

"Utwórz skrypt debugowania który:
1. Odtwarza dokładny stan przed błędem
2. Przechodzi przez każdą operację
3. Loguje zmiany stanu na każdym kroku
4. Identyfikuje gdzie stan staje się nieprawidłowy"

Analiza ścieżki audytu

"Przeanalizuj logi audytu aby zrozumieć:
- Jakie działania podjął użytkownik
- Kolejność operacji
- Wszelkie równoczesne żądania
- Końcowy stan który spowodował błąd"

Debugowanie wydajności

Analiza profilowania

"Aplikacja działa wolno. Sprofiluj kod i:
- Zidentyfikuj wąskie gardła
- Znajdź algorytmy O(n²)
- Wykryj wycieki pamięci
- Zasugeruj optymalizacje"

Optymalizacja zapytań

"Te zapytania do bazy danych przekraczają limit czasu:
[wklej logi wolnych zapytań]
- Przeanalizuj plany wykonania zapytań
- Zidentyfikuj brakujące indeksy
- Zasugeruj przepisanie zapytań"

Debugowanie pamięci

"Użycie pamięci stale rośnie. Pomóż mi:
- Znaleźć wycieki pamięci
- Zidentyfikować referencje cykliczne
- Śledzić alokację obiektów
- Zaimplementować poprawki"

Debugowanie sieci

"Wywołania API sporadycznie nie powodzą się:
- Przeanalizuj logi sieciowe
- Sprawdź wzorce timeout
- Zidentyfikuj problemy logiki ponawiania
- Zasugeruj ulepszenia odporności"

Debugowanie określonych typów błędów

Warunki wyścigu

1. Zidentyfikuj objawy

   "Użytkownicy zgłaszają sporadyczne niepowodzenia logowania.
   Czasami działa ale czasami nie.
   Podejrzewam warunek wyścigu."

2. Przeanalizuj współbieżność

   "Znajdź wszystkie operacje współbieżne w przepływie logowania.
   Szukaj dostępu do stanu współdzielonego bez właściwej synchronizacji."

3. Dodaj instrumentację

   "Dodaj logowanie ze znacznikami czasu aby śledzić dokładną
   kolejność operacji gdy błąd występuje"

4. Zaimplementuj poprawkę

   "Dodaj właściwe blokowanie/synchronizację aby zapobiec
   warunkowi wyścigu"

Wycieki pamięci

// Poproś Claude o analizę wycieków
"Przejrzyj ten kod pod kątem potencjalnych wycieków pamięci:
- Nie usunięte listenery zdarzeń
- Domknięcia trzymające referencje
- Zależności cykliczne
- Duże obiekty w cache'ach"

// Claude zapewnia konkretne poprawki:
// - Dodaj czyszczenie w useEffect
// - Zaimplementuj WeakMap dla cache'ów
// - Przerwij referencje cykliczne

Błędy typu off-by-one

"Ta paginacja pokazuje 11 elementów zamiast 10.
Zdebuguj błąd off-by-one w obliczeniu."

// Claude będzie:
// - Śledzić warunki graniczne
// - Sprawdzać iteracje pętli
// - Weryfikować indeksowanie tablic
// - Naprawiać błędy fence-post

Debugowanie oparte na testach

Tworzenie testów odtwarzających

Wzorzec odtwarzania błędu

"Utwórz minimalny przypadek testowy który odtwarza ten błąd:
- Usuń niepowiązany kod
- Wyizoluj komponent który nie działa
- Spraw aby zawodził konsekwentnie
- Udokumentuj oczekiwane vs rzeczywiste zachowanie"

Debugowanie poprzez testy

Debugowanie testów jednostkowych

"Ten test nieoczekiwanie nie przechodzi:
[wklej nieudany test]

Zdebuguj poprzez:
1. Dodanie console.log do śledzenia wykonania
2. Sprawdzenie konfiguracji mocków
3. Weryfikację assertów
4. Uruchomienie w izolacji"

Debugowanie testów integracyjnych

"Test integracyjny przechodzi lokalnie ale nie w CI:
- Porównaj środowiska
- Sprawdź problemy z czasem
- Zweryfikuj zależności zewnętrzne
- Dodaj wynik debugowania"

Rozwiązywanie niestabilnych testów

"Ten test losowo nie przechodzi w 20% przypadków:
- Zidentyfikuj niedeterministyczne zachowanie
- Dodaj jawne oczekiwania gdzie potrzeba
- Mockuj operacje zależne od czasu
- Zapewnij właściwe czyszczenie"

Debugowanie produkcyjne

Bezpieczne debugowanie produkcyjne

Uwaga

Podczas debugowania w produkcji:

• Używaj operacji tylko do odczytu
• Unikaj modyfikowania stanu
• Implementuj wyłączniki bezpieczeństwa
• Miej gotowe plany wycofania

Przepływ śledztwa produkcyjnego

1. Zbierz dowody bez wpływu

   "Przeanalizuj logi produkcyjne bez uruchamiania poleceń
   które mogłyby wpłynąć na użytkowników"

2. Utwórz lokalne odtworzenie

   "Na podstawie danych produkcyjnych, utwórz lokalne
   środowisko które odtwarza problem"

3. Testuj poprawkę na stagingu

   "Wdróż poprawkę na staging i zweryfikuj z
   danymi podobnymi do produkcyjnych"

4. Monitoruj wdrożenie

   "Utwórz alerty monitorowania dla określonego
   wzorca błędu przed wdrożeniem poprawki"

Integracja narzędzi debugowania

Niestandardowe polecenia debugowania

Utwórz potężne skróty debugowania:

.claude/commands/debug-error.md

Zdebuguj błąd: $ARGUMENTS

1. Przeszukaj bazę kodu pod kątem komunikatu błędu
2. Znajdź wszystkie ścieżki kodu które mogą go wywołać
3. Przeanalizuj ostatnie zmiany w tych plikach
4. Sprawdź podobne problemy z przeszłości
5. Zaproponuj poprawki z wyjaśnieniami

Hooki debugowania

Automatyzuj przepływy debugowania z hookami:

{
  "hooks": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "if [[ \"$CLAUDE_TOOL_OUTPUT\" =~ error ]]; then echo '🔍 Wykryto błąd - uruchamiam diagnostykę...'; fi"
        }
      ]
    }
  ]
}

Częste pułapki debugowania

Antywzorce debugowania do unikania

❌ Zmienianie wielu rzeczy naraz - Testuj jedną hipotezę na raz ❌ Ignorowanie komunikatów błędów - Czytaj je uważnie, często zawierają odpowiedź ❌ Założenia bez weryfikacji - Zawsze potwierdź swoje teorie dowodami ❌ Debugowanie najpierw w produkcji - Odtwarzaj lokalnie gdy to możliwe ❌ Nie sprawdzanie podstaw - Zweryfikuj konfigurację, środowisko i zależności ❌ Pomijanie kroku odtworzenia - Zawsze odtwarzaj przed próbą naprawy

Budowanie podręcznika debugowania

Standardy debugowania zespołu

Udokumentuj swoje wzorce debugowania:

# Dodatki do CLAUDE.md dla debugowania

## Proces debugowania
1. Zawsze utwórz test który odtwarza problem
2. Używaj naszego standardowego formatu logowania
3. Sprawdź najpierw te częste przyczyny:
   - Zmienne środowiskowe
   - Połączenia z bazą danych
   - Timeouty API
   - Unieważnienie cache

## Polecenia debugowania
- `npm run debug` - Uruchom z włączonym debugowaniem
- `npm run analyze:logs` - Uruchom analizę logów
- `npm run trace` - Włącz szczegółowe śledzenie

Integracja post-mortem

Po naprawieniu błędów, ucz się z nich:

"Utwórz dokument post-mortem dla tego błędu:
- Analiza głównej przyczyny
- Oś czasu zdarzeń
- Co poszło nie tak
- Jak zapobiec podobnym problemom
- Potrzebne ulepszenia monitorowania"

Podsumowanie

Debugowanie z Claude Code przekształca jedną z najbardziej frustrujących aktywności programistycznych w systematyczny, niemal przyjemny proces. Łącząc zrozumienie kodu przez Claude, rozpoznawanie wzorców i zdolność wykonywania poleceń diagnostycznych, możesz tropić błędy szybciej i bardziej niezawodnie niż kiedykolwiek wcześniej. Kluczem jest podejście metodyczne - zbieranie dowodów, formułowanie hipotez, systematyczne testowanie i uczenie się z każdego błędu aby zapobiec przyszłym. Dzięki tym przepływom spędzisz mniej czasu na polowaniu na błędy, a więcej na budowaniu funkcji.