# Debugowanie i naprawa błędów z Claude Code: praktyczny przewodnik

> Kompletny, praktyczny przewodnik po debugowaniu kodu za pomocą Claude Code: analiza stack trace’ów, interpretacja logów serwera, rozwiązywanie błędów TypeScript, naprawa testów oraz eliminacja wąskich gardeł wydajności.

## 1. Dlaczego debugowanie z Claude Code jest skuteczniejsze niż tradycyjne podejście

Klasyczny proces poszukiwania błędów często zamienia się w wyczerpującą rutynę: programista godzinami przebija się przez zagmatwany stack trace w terminalu, ręcznie rozmieszcza dziesiątki `console.log` lub punktów zatrzymania debuggera i próbuje powiązać dane z kilku modułów.

Terminalowy agent Claude Code zasadniczo zmienia to podejście: mając bezpośredni dostęp do systemu plików, potrafi natychmiast prześledzić łańcuch wykonań od interfejsu klienta (UI), przez kontrolery backendu, aż po zapytania do bazy danych.

```mermaid
flowchart TD
    A["Симптом: Помилка або аварійний лог"] --> B["Claude Code CLI"]
    B --> C["Аналіз Stack Trace & Виділення файлів"]
    C --> D["Read & Grep по кодовій базі"]
    D --> E["Локалізація джерела збою"]
    E --> F["Генерація гіпотези та виправлення"]
    F --> G["Автоматичний прогін тестів / збірки"]
    G -->|Успіх| H["Коміт виправлення"]
    G -->|Помилка| E
```

### Porównanie ręcznego debugowania i debugowania z Claude Code

| Kryterium | Tradycyjne ręczne debugowanie | Debugowanie z Claude Code |
| :--- | :--- | :--- |
| **Lokalizacja błędu** | Ręczne przechodzenie linia po linii stosu w IDE | Automatyczne mapowanie błędu na kontekst projektu |
| **Praca z logami** | Wzrokowe szukanie anomalii w tysiącach linii | Autonomiczna analiza ustrukturyzowanych logów przez potoki CLI |
| **Złożone zależności** | Konieczność utrzymywania w głowie grafu wywołań obejmującego 5–10 plików | Krokowe śledzenie semantyczne przepływów danych |
| **Błędy TypeScript** | Próby szybkiego obejścia problemu przez `as any` | Poprawna naprawa zawężania typów bez naruszania systemu typów |
| **Weryfikacja poprawki** | Ręczny restart aplikacji lub testów w konsoli | Automatyczny cykliczny restart testów do pełnego sukcesu |

> [!NOTE]
> Claude Code nie zastępuje zrozumienia kodu przez programistę, ale skraca czas od wystąpienia incydentu do lokalizacji jego przyczyny źródłowej o 3–5 razy.

---

## 2. Anatomia idealnego raportu o błędzie dla asystenta AI

Jakość i szybkość rozwiązania problemu bezpośrednio zależą od tego, jak kompletnie opisano błąd w zapytaniu wejściowym.

### Rozmyte zapytanie vs. ustrukturyzowany opis

> [!WARNING]
> **Nieefektywne zapytanie:**
> *«Aplikacja się zepsuła, formularz rejestracji nie działa, sprawdź co jest nie tak.»*
> 
> Przy takim opisie agent musi losowo przeszukiwać dziesiątki plików, marnując limity okna kontekstowego na zgadywanie.

> [!TIP]
> **Profesjonalny inżynierski opis:**
> *«Podczas wysyłania formularza na `/register` użytkownik otrzymuje status 500. W konsoli przeglądarki pojawia się błąd: `TypeError: Cannot read properties of undefined (reading 'email')`. Zapytanie wysyła JSON z polami `username` oraz `mailAddress`. Sprawdź schemat walidacji w `src/api/auth.ts` i uzgodnij nazwy pól.»*

### Cztery zasady wyczerpującego opisu defektu

1. **Oczekiwane zachowanie (Expected Behavior):** co dokładnie miało się stać przy pozytywnym scenariuszu.
2. **Faktyczne zachowanie (Actual Behavior):** dokładny tekst błędu, kod statusu lub nieoczekiwany wynik obliczeń.
3. **Kroki reprodukcji (Reproduction Steps):** które przyciski zostały kliknięte, jakie parametry przekazano w URL lub jakie ciało zapytania zostało wysłane.
4. **Kontekst lokalizacji (Context & File Paths):** na której dokładnie stronie, komponencie czy endpoincie następuje awaria wykonania.

---

## 3. Analiza Stack Traces i rozkład komunikatów o błędach

Komunikaty o błędach i stosy wywołań można przekazywać agentowi w czystej postaci. Claude samodzielnie odfiltruje szum z bibliotek systemowych (`node_modules`) i skupi się na kodzie Twojego projektu.

### Przekazanie surowego stosu błędu

```text
I am getting this runtime error when rendering the user table:

TypeError: Cannot read properties of undefined (reading 'map')
    at UserTable (src/components/UserTable.tsx:34:22)
    at renderWithHooks (node_modules/react-dom/cjs/react-dom.development.js:15486:18)
    at mountIndeterminateComponent (node_modules/react-dom/cjs/react-dom.development.js:20103:13)

What is causing this, and how should we properly handle loading and empty states?
```

### Jak Claude analizuje podobny incydent

1. **Celowane czytanie:** otwiera `src/components/UserTable.tsx` w linii 34 za pomocą narzędzia `Read`.
2. **Analiza źródła danych:** sprawdza propsy i hooki stanu (`useState`, `useQuery`), aby ustalić, dlaczego tablica użytkowników w momencie renderowania ma wartość `undefined`.
3. **Bezpieczna poprawka:** dodaje sprawdzenie istnienia danych (Optional Chaining `users?.map(...)`), stan ładowania (Skeleton/Spinner) lub domyślną wartość (`users = []`).

---

## 4. Praca z logami serwera i analiza przez potok CLI

Do badania awarii serwerowych lub błędów w środowisku stagingowym Claude Code można podłączać bezpośrednio do standardowych strumieni wejścia/wyjścia Unix.

### Analiza logów przez potok konsolowy

```bash
# Передати останні 100 рядків серверного логу в Claude для швидкої діагностики
tail -n 100 /var/log/nginx/error.log | claude -p "Find critical errors and explain their root cause. Provide actionable fix instructions."

# Пошук помилок із конкретного сервісу Docker
docker logs --tail 200 api-service 2>&1 | claude -p "Analyze database connection failures and timeout exceptions."
```

### Interaktywne badanie plików logów

W sesji interaktywnej możesz skierować agenta na zapisane logi:

```text
Read logs/production-error.log and focus on entries with status 500 from the last two hours. Group related exceptions and trace which external service call failed.
```

Claude wyróżni powtarzalne wzorce odmów, wykryje awarie uwierzytelniania zewnętrznych API lub wyczerpanie puli połączeń z bazą danych.

---

## 5. Strategiczne instrumentowanie: celowane logowanie i śledzenie

Najtrudniejsze błędy to tak zwane „cichy defekty” (Silent Bugs), gdy aplikacja nie rzuca wyjątków, ale zwraca niepoprawny wynik (np. końcowa kwota zamówienia liczona jako `$0.00` zamiast `$42.50`).

W takich przypadkach stosuje się metodę strategicznego instrumentowania.

### Algorytm krok po kroku dochodzenia

1. **Postaw zadanie na rozmieszczenie logów:**
   ```text
   The order total calculation is returning 0 for items with promo codes. Add targeted diagnostic logging to calculateOrderTotal and its call sites to log input arguments, discount factors, and return values.
   ```
2. **Odtwórz błąd w aplikacji:** wykonaj zamówienie z kodem promocyjnym w środowisku testowym.
3. **Przekaż otrzymane diagnostyczne logi z powrotem agentowi:**
   ```text
   Here is the diagnostic log from the checkout attempt:
   [DEBUG] Item subtotal: 42.50
   [DEBUG] Promo code applied: 'SPRING20' -> parsed discount: '0.2' (string)
   [DEBUG] Applying formula: 42.50 * (1 - '0.2') -> NaN -> coerced to 0

   What went wrong?
   ```
4. **Poprawka i czyszczenie:**
   Claude natychmiast wskaże problem niezgodności typów (string zamiast number), poprawi funkcję parsującą i **samodzielnie usunie wszystkie tymczasowe logi debugujące**.

---

## 6. Naprawa złożonych błędów typów w TypeScript

Błędy kompilatora TypeScript bywają skomplikowane, szczególnie przy pracy z generykami, uniami typów (Unions) lub zagnieżdżonymi obiektami.

### Dlaczego „zagłuszanie” kompilatora jest niebezpieczne

Wielu programistów w pośpiechu używa wymuszonego rzutowania typów (`as unknown as TargetType`), co ukrywa problem na etapie budowania, ale prowadzi do awarii w runtime.

:::tabs
@tab Niebezpieczne podejście (Type Casting)
```typescript
// Погано: примусове ігнорування проблеми типів
const userEmail = (response.data as any).user.email;
// Якщо user виявиться null, додаток впаде в продакшені!
```
@tab Poprawne zawężanie typów (Type Narrowing)
```typescript
// Добре: безпечне звуження типів через захисники
if (!response.data || typeof response.data !== 'object' || !('user' in response.data)) {
  throw new Error('Invalid API response structure');
}
const userEmail = response.data.user?.email ?? 'anonymous';
```
:::

### Instrukcja dla Claude dotycząca czystego rozwiązania

```text
I am encountering this TypeScript compiler error in src/services/payment.ts:48:

Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Fix this issue properly using strict type narrowing or safe fallback values. Do NOT use type assertions ('as') or 'any'.
```

Claude sprawdzi cały cykl życia zmiennej i doda poprawną obsługę braku wartości.

---

## 7. Zautomatyzowana naprawa buildów i testów w pętli

Jedną z najpotężniejszych możliwości Claude Code jest autonomiczna praca w pętli „Uruchom → Analizuj → Popraw → Zweryfikuj”.

```mermaid
flowchart TD
    A["Команда: 'Fix all failing tests'"] --> B["Запуск npm test через Bash"]
    B --> C{"Всі тести пройдено?"}
    C -->|Так| D["Звіт про успішне завершення"]
    C -->|Ні| E["Аналіз помилок у звіті тестувальника"]
    E --> F{"Де баг: у коді чи в тесті?"}
    F -->|У коді| G["Виправлення бізнес-логіки"]
    F -->|У тесті| H["Оновлення застарілих очікувань тесту"]
    G & H --> B
```

### Gotowe szablony komend do likwidacji defektów

:::tabs
@tab Naprawa testów jednostkowych (Jest / Vitest)
```text
Run the test suite with npm test. For each failing test:
1. Determine if the failure is caused by a real bug or an outdated test expectation.
2. Fix the underlying issue cleanly.
3. Re-run tests until all test suites pass.
```
@tab Poprawa błędów kompilacji builda
```text
Run npm run build. Inspect the compiler and bundler error output. Fix all type and syntax errors, then verify with a clean build.
```
@tab Usunięcie błędów lintingu (ESLint)
```text
Run npx eslint src/ --max-warnings=0. Fix all reportable style and syntax errors without disabling ESLint rules.
```
:::

---

## 8. Szukanie wąskich gardeł wydajności i wycieków zasobów

Błędy to nie tylko awaryjne zakończenia (crash). Wolne działanie strony, nadmierne obciążenie bazy danych i zawieszanie się interfejsu to krytyczne defekty wydajności.

### Zapytanie o audyt szybkości działania

```text
The /dashboard page takes over 6 seconds to load. Analyze the server-side data fetching and client components:
1. Check for N+1 query patterns in our Prisma calls.
2. Identify missing database indices on frequently queried foreign keys.
3. Look for unnecessary client component re-renders caused by unstable object references.
```

### Czego Claude szuka podczas analizy wydajności

- **Zapytania N+1:** zamiana cyklicznych zapytań do bazy na pojedyncze zapytanie z operatorem `IN` lub relacją `include`.
- **Memoizacja w React:** wykrywanie ciężkich obliczeń bez `useMemo` lub niestabilnych handlerów zdarzeń bez `useCallback`.
- **Nadmiarowe payloady:** dodanie paginacji (`limit`/`offset`) lub selektywnej projekcji pól (`select: { id: true, name: true }`) zamiast ładowania całej tabeli.

---

## 9. Praktyczny warsztat: krokowe dochodzenie rzeczywistego błędu

Rozważmy praktyczny scenariusz: użytkownicy skarżą się, że przy zastosowaniu kuponu rabatowego 15% w koszyku z trzema produktami całkowita kwota naliczana jest nieprawidłowo.

### Krok 1. Lokalizacja kodu obliczeniowego

Otwórz Claude Code i znajdź odpowiedni moduł:

```text
Find where the cart discount calculation is implemented and inspect the file.
```

Claude skorzysta z `Grep` dla słowa `discount` i otworzy plik `src/domain/cart.ts`.

### Krok 2. Analiza wadliwego kodu

```typescript
// Знайдений фрагмент у src/domain/cart.ts:
export function applyCoupon(total: number, discountPercent: number): number {
  return total - total * (discountPercent / 100);
}
```

Na pierwszy rzut oka formuła wygląda poprawnie. Jednak w JavaScript operacje na liczbach zmiennoprzecinkowych często prowadzą do problemów z zaokrągleniem: `100 - 100 * (15 / 100)` zwraca `85.00000000000001`, co łamie bramkę płatniczą Stripe, oczekującą całkowitej liczby centów.

### Krok 3. Sformułowanie zadania na poprawkę i testy

```text
In src/domain/cart.ts, the applyCoupon function causes floating-point precision issues that fail payment validation. Refactor it to calculate prices in integer cents, add rounding via Math.round, and create a comprehensive unit test in src/domain/cart.test.ts covering edge cases.
```

### Krok 4. Weryfikacja wyniku

Agent poprawia funkcję:

```typescript
export function applyCouponInCents(totalCents: number, discountPercent: number): number {
  const discountAmount = Math.round(totalCents * (discountPercent / 100));
  return Math.max(0, totalCents - discountAmount);
}
```

Po tym Claude samodzielnie uruchamia `npm test src/domain/cart.test.ts` i potwierdza, że wszystkie testy przeszły.

---

## 10. Szybka samoewaluacja i podsumowujący checklist debugowania

Sprawdź swoje umiejętności pracy z debugowaniem w Claude Code.

### Pytania kontrolne

> **1. Jaka jest najbardziej efektywna metoda badania awarii serwera, która wystąpiła na serwerze stagingowym?**
>
> > [!TIP]
> > **Odpowiedź:** Przekazać ostatnie linie loga bezpośrednio do trybu autonomicznego Claude Code przez potok konsolowy: `tail -n 150 /var/log/app.log | claude -p "Find errors and diagnose causes"`.

> **2. Dlaczego przy poprawianiu błędów typów TypeScript należy zabronić asystentowi używania operatora `as`?**
>
> > [!TIP]
> > **Odpowiedź:** Rzutowanie typów przez `as` jedynie maskuje problem dla kompilatora, ale nie chroni aplikacji przed awaryjnymi upadkami w runtime przy braku oczekiwanych danych. Należy wymagać poprawnego zawężania typów (Type Narrowing) lub wartości domyślnych.

> **3. Jak prawidłowo zorganizować naprawę dziesięciu testów, które padły po refaktoryzacji?**
>
> > [!TIP]
> > **Odpowiedź:** Uruchomić Claude Code w trybie pętli z jasną instrukcją: uruchom testy, przeanalizuj błędy, odróżnij przestarzałe oczekiwania testów od rzeczywistych defektów logiki biznesowej i powtarzaj iterację do osiągnięcia 100% sukcesu.

### Checklist systematycznego polowania na błędy

- [ ] Podawaj agentowi 4 obowiązkowe elementy: Oczekiwane zachowanie, Faktyczne zachowanie, Kroki reprodukcji oraz Ścieżki plików.
- [ ] Przekazuj pełne stack traces bez skrótów – Claude sam znajdzie potrzebne linie kodu.
- [ ] Używaj potoków Unix (`tail | claude -p`) do szybkiej diagnostyki logów serwerowych.
- [ ] Wymagaj bezpiecznej poprawki typów bez użycia wymuszonego rzutowania `as any`.
- [ ] Zlecaj Claude pisanie testów regresyjnych dla każdego naprawionego buga, aby zapobiec nawrotom.
- [ ] Czyść tymczasowe logi diagnostyczne przed zatwierdzaniem zmian w repozytorium.