# Wzorce debugowania

URL: https://developertoolkit.ai/pl/cookbook/error-handling-recipes/debugging-patterns/
Description: Pięć receptur debugowania z agentem na sporadyczne błędy, ślady stosu, wycieki, wyścigi i błędy między usługami, każda ze sprawdzeniem przed poprawką i po niej.

Wzorce debugowania z pomocą AI to pięć receptur dla Claude Code, Codeksa i Cursora, w których dowody zbiera się przed poprawką: instrumentacja i korelacja sporadycznych błędów, celowana poprawka ze śladu stosu, wycieki pamięci z migawek sterty, wyścigi odtworzone testem oraz oś czasu między usługami według ID żądania. Każda kończy się sprawdzeniem, które przed poprawką nie przechodzi, a po niej przechodzi.

Ta strona jest dla programistów, którzy oddają błędy agentowi, i dla tech leadów, którzy decydują, jakie dowody musi zawierać pull request z poprawką. Sytuacja: mniej więcej co trzecie logowanie na produkcji kończy się błędem, ślad stosu wskazuje linię, która wygląda poprawnie, a błąd znika, gdy podłączasz debugger. Poproszony o „naprawę błędu autoryzacji” agent zwraca pewną siebie hipotezę i diff, po którym objaw cichnie. Poniższe wzorce każą agentowi najpierw zebrać dowody, a poprawkę udowodnić sprawdzeniem, które możesz uruchomić ponownie.

## Co dają ci te wzorce debugowania

- Tabelę „objaw → wzorzec”, która mówi, jakie dowody zebrać, zanim agent cokolwiek zmieni
- Siedem gotowych promptów: instrumentacja, korelacja logów, diagnoza śladu stosu, analiza różnicy migawek sterty, odtworzenie wyścigu, oś czasu między usługami i przegląd poprawki
- Dokładne polecenia, którymi przekażesz logi do Claude Code i Codeksa bez sesji interaktywnej
- Listę dowodów, dzięki której recenzent zatwierdzi poprawkę bez czytania każdej linii diffu
- Sposoby, na jakie debugowanie z agentem zawodzi, i wyjście z każdego z nich

## Który wzorzec debugowania pasuje do twojego błędu?

Zacznij od objawu. Każdy wiersz podaje dowody, których potrzebuje agent, i sprawdzenie, które dowodzi poprawki, bo poprawka bez sprawdzenia, które najpierw nie przechodziło, to wciąż zgadywanie.

| Objaw | Wzorzec | Dowody dla agenta | Dowód, że poprawka działa |
| --- | --- | --- | --- |
| Czasem zawodzi, bez wyraźnego wyzwalacza | [1. Instrumentacja i korelacja](#wzorzec-1-zinstrumentuj-i-skoreluj-sporadyczny-błąd) | Ustrukturyzowane logi ze 100 lub więcej odtworzonych przebiegów | Ta sama pętla pokazuje zero błędów |
| Jeden wyjątek ze śladem stosu | [2. Ślad stosu → celowana poprawka](#wzorzec-2-zamień-ślad-stosu-w-celowaną-poprawkę) | Pełny ślad, dane zdarzenia, wydanie | Test zbudowany ze zdarzenia najpierw nie przechodzi, potem przechodzi |
| Pamięć rośnie aż do restartu procesu | [3. Różnica migawek sterty](#wzorzec-3-znajdź-wyciek-pamięci-w-migawkach-sterty) | Dwie migawki przy tym samym obciążeniu, główne obiekty zatrzymujące | Skrypt obciążeniowy (`soak`: ta sama operacja powtórzona tysiące razy z limitem wzrostu sterty) przechodzi |
| Duplikaty lub zgubione zapisy pod obciążeniem | [4. Test współbieżności, który nie przechodzi](#wzorzec-4-odtwórz-warunek-wyścigu-testem-który-nie-przechodzi) | Operacja, współdzielony stan, zaobserwowany duplikat | Test współbieżny nie przechodzi przed poprawką, przechodzi po niej |
| Wolno lub błędnie tylko między usługami | [5. Oś czasu według ID żądania](#wzorzec-5-odtwórz-oś-czasu-między-usługami-według-id-żądania) | Logi lub spany z każdego przeskoku, z ID żądania | Luki nie ma w nowej osi czasu ani w nowym śladzie |

Deterministyczny błąd z jasną reprodukcją nie potrzebuje żadnego z tych wzorców: napisz test, który nie przechodzi, i daj agentowi go naprawić, jak w [programowaniu sterowanym testami z AI](/pl/method/principles/test-driven-development/).

## Przygotuj agenta przed pierwszym błędem

Dwa dodatki obniżają koszt każdego z poniższych wzorców. Skill do debugowania daje agentowi metodę (najpierw dowody, jedna hipoteza naraz, test przed poprawką), więc nie powtarzasz jej w każdym prompcie. Serwer MCP narzędzia do śledzenia błędów, podłączony tylko do odczytu, pozwala agentowi pobrać prawdziwy ślad stosu i zdarzenie zamiast twojej parafrazy. Obie instalacje, razem z pułapkami, opisują strony o [skillach do testowania i debugowania](/pl/ecosystem/skills/testing-debugging-skills/) oraz o [serwerach MCP do obserwowalności](/pl/ecosystem/mcp/observability-mcp/).

**Claude Code**

```bash
# Terminal, repository root
npx skills add obra/superpowers --skill systematic-debugging -a claude-code -y
claude mcp add -s project --transport http sentry https://mcp.sentry.dev/mcp
claude mcp login sentry
```

**Codex**

```bash
# Terminal, repository root
npx skills add obra/superpowers --skill systematic-debugging -a codex -y
codex mcp add sentry --url https://mcp.sentry.dev/mcp
codex mcp login sentry
```

**Cursor**

```bash
# Terminal, repository root
npx skills add obra/superpowers --skill systematic-debugging -a cursor -y
```

Następnie dodaj serwer do `.cursor/mcp.json` i dokończ logowanie OAuth, gdy Cursor o nie poprosi:

```json
{ "mcpServers": { "sentry": { "url": "https://mcp.sentry.dev/mcp" } } }
```

Na ekranie OAuth Sentry zostaw **Triage Issues** i **Manage Projects & Teams** odznaczone: agent może wtedy czytać zgłoszenia i zdarzenia, ale nie może ich zamykać ani przypisywać. Jeśli używasz innego narzędzia do śledzenia błędów, wzorce działają tak samo z wklejonym śladem stosu.

## Wzorzec 1: zinstrumentuj i skoreluj sporadyczny błąd

Sporadyczny błąd wymaga danych z wielu przebiegów, a nie dłuższego wpatrywania się w jeden. Agent dodaje wąskie, ustrukturyzowane logowanie, ty odtwarzasz błąd wiele razy, a agent porównuje przebiegi nieudane z udanymi, zanim cokolwiek zaproponuje.

1. **Najpierw zatwierdź lub odłóż (`stash`) swoje zmiany**, żeby `git diff` pokazywał tylko to, co doda agent. Instrumentacja jest tymczasowa; na końcu ją cofniesz.

2. **Poproś wyłącznie o logowanie, ograniczone do podejrzanej ścieżki.** Podaj objaw, częstość i to, co już wykluczyłeś.

   **Prompt do skopiowania: instrumentacja sporadycznego błędu autoryzacji**

   ```text
   Token validation in src/auth/validate.ts fails on roughly 30% of logins in production.
   It does not correlate with user type or time of day. Add temporary debug logging to
   diagnose it: token issue time (iat), expiry (exp), validation latency, the clock of the
   host that validates, and every branch that can reject the token. Use one structured
   JSON line per event with the prefix [AUTH-DEBUG] and a requestId field. Logging only:
   do not change behaviour, error handling or return values. List every line you added.
   ```

3. **Odtwórz błąd wiele razy i zapisz wynik.** Jeden udany przebieg niczego nie dowodzi przy błędzie sporadycznym. Uruchom w pętli najwęższy test, który przechodzi przez tę ścieżkę:

   ```bash
   # Terminal. 100 runs of one test file; every run is bracketed in the log
   for i in $(seq 1 100); do
     echo "RUN $i START" >> debug.log
     npx vitest run tests/auth/validate.test.ts >> debug.log 2>&1 \
       && echo "RUN $i PASSED" >> debug.log || echo "RUN $i FAILED" >> debug.log
   done
   grep -c "^RUN [0-9]* FAILED" debug.log
   ```

   Jeśli test lokalnie nigdy nie zawodzi, wyzwalacz tkwi w środowisku (rozjazd zegarów między hostami, obciążenie, współdzielony cache). Zbierz wtedy linie `[AUTH-DEBUG]` ze stagingu lub produkcji z tego samego okna czasu.

4. **Poproś o korelację, nie o poprawkę.** Przekaż log agentowi w przebiegu tylko do odczytu, żeby nie mógł edytować kodu, gdy rozumuje. Poniższe flagi sprawdziliśmy w Claude Code 2.1.283 i Codex 0.157.1.

   **Claude Code**

   ```bash
   # -p runs non-interactively and prints the answer; plan mode keeps it read-only
   grep -E "AUTH-DEBUG|^RUN " debug.log | claude -p --permission-mode plan \
     "Correlate the failing [AUTH-DEBUG] events against the passing ones. What do the failures share that the passes do not? Give confidence and the log lines that support it. No fix yet."
   ```

   **Codex**

   ```bash
   # Piped stdin is appended to the prompt; read-only sandbox, no edits
   grep -E "AUTH-DEBUG|^RUN " debug.log | codex exec -s read-only \
     "Correlate the failing [AUTH-DEBUG] events against the passing ones. What do the failures share that the passes do not? Give confidence and the log lines that support it. No fix yet."
   ```

   **Cursor**

   Przełącz się na Plan Mode, dołącz `debug.log` do czatu przez `@` i wklej poniższy prompt korelacyjny. Plan Mode tworzy plan zamiast edycji, więc ten krok pozostaje tylko do odczytu.

   **Prompt do skopiowania: korelacja udanych i nieudanych przebiegów**

   ```text
   debug.log holds 100 reproduced runs. Each run is bracketed by RUN n START and
   RUN n PASSED or RUN n FAILED. Group the [AUTH-DEBUG] events by run and requestId. Compare failing requests with passing
   ones on validation latency, exp minus the validating host's clock, and iat. Tell me
   what the failures have in common that the passes do not, quote the lines that show
   it, and give your confidence as high, medium or low. Do not propose a fix yet.
   If the evidence is too thin to decide, say which extra field to log.
   ```

   Przydatna odpowiedź wskazuje przyczynę, którą da się przetestować, na przykład: „każdy błąd ma `exp` mniej niż 2 s przed zegarem hosta walidującego i wszystkie pochodzą z hosta B, którego zegar spieszy się o 4 s”. Mglista odpowiedź („możliwe, że to warunek wyścigu”) znaczy, że logowanie nie złapało sygnału; dodaj pole, o które prosi agent, i uruchom pętlę jeszcze raz.

5. **Zamień przyczynę w test, który nie przechodzi, a potem napraw.** Test utrwala warunek (token walidowany przez host, którego zegar spieszy się o 4 s) i musi zawieść na obecnym kodzie. Dopiero wtedy agent dodaje poprawkę, na przykład niewielką tolerancję rozjazdu zegara, a pętla z kroku 3 rusza ponownie. Zero błędów na 100 przebiegów plus nowy test to twój dowód.

6. **Usuń instrumentację.** Poproś agenta o cofnięcie każdej linii `[AUTH-DEBUG]` i potwierdź, że `git grep AUTH-DEBUG` nic nie zwraca. Trwałe logowanie należy do [wzorców logowania](/pl/cookbook/error-handling-recipes/logging-patterns/), a nie do pozostałości po polowaniu na błąd.

## Wzorzec 2: zamień ślad stosu w celowaną poprawkę

Ślad stosu wskazuje plik, linię i łańcuch wywołań, więc to najbogatsze pojedyncze wejście, jakie możesz dać agentowi. Ryzyko leży w poprawce: najszybszy sposób, żeby `Cannot read properties of undefined` zniknęło, to optional chaining wszędzie, co ukrywa prawdziwy błąd. Każ agentowi sklasyfikować brakującą wartość, zanim dotknie kodu.

**Prompt do skopiowania: od śladu stosu do celowanej poprawki**

```text
Production error (Sentry issue linked if you have the Sentry MCP server, otherwise below):

TypeError: Cannot read properties of undefined (reading 'id')
    at OrderService.createOrder (src/services/order.ts:145:23)
    at async OrderController.create (src/controllers/order.ts:67:18)

1. Walk the call chain and tell me which value is undefined at order.ts:145 and every
   path by which it can arrive undefined. Quote the code for each path.
2. Classify each path: "should never happen" (a bug upstream: fail loudly with a typed
   error) or "expected sometimes" (legitimate incomplete data: handle it explicitly).
3. Write one failing test per path that reproduces the error with the event's data.
4. Only then fix. No blanket optional chaining, no empty catch blocks, no default values
   that hide missing data. Run the tests and show the output.
```

Dobra poprawka trzyma oba przypadki osobno:

```typescript
async createOrder(userId: string, input: OrderInput) {
  // "Should never happen": the controller validated userId, so this is a bug upstream
  const user = await this.users.find(userId);
  if (!user) throw new NotFoundError(`User ${userId} not found`);

  // "Expected sometimes": users created before billing launched have no customer record
  if (!user.billingCustomer) {
    logger.warn('user without billing customer; creating one', { userId });
    user.billingCustomer = await this.billing.createCustomer(user);
  }
  return this.orders.create(user, input);
}
```

Liczy się test zbudowany z prawdziwego zdarzenia. Jeśli test agenta przechodzi na kodzie bez poprawki, odtworzył coś innego; odeślij agenta do punktu 1.

Ten prompt oraz prompty z wzorców 3 i 4 działają bez zmian w Claude Code, Codeksie i Cursorze. Od narzędzia zależy tylko przekazywanie logów bez sesji interaktywnej we wzorcach 1 i 5, dlatego zakładki mają wyłącznie te kroki.

## Wzorzec 3: znajdź wyciek pamięci w migawkach sterty

Sterta, która rośnie aż do restartu procesu, to problem z zatrzymywaniem obiektów, a zatrzymywanie widać w dwóch migawkach sterty zrobionych przy tym samym obciążeniu. Zbierz dowody narzędziami samego Node’a, a agentowi daj listę obiektów zatrzymujących, nie zdanie „coś cieknie”.

1. **Uruchom usługę z migawkami na sygnał.** `--heapsnapshot-signal` zapisuje plik `.heapsnapshot` w katalogu roboczym za każdym razem, gdy proces dostanie sygnał:

   ```bash
   # Terminal
   node --heapsnapshot-signal=SIGUSR2 dist/server.js &
   # run warm-up load until heap usage is steady, then:
   kill -USR2 $!          # snapshot 1
   # run the same load for 30 minutes, then:
   kill -USR2 $!          # snapshot 2
   ```

   Zapis migawki blokuje pętlę zdarzeń i potrzebuje mniej więcej tyle dodatkowej pamięci, ile zajmuje sama sterta, więc w usłudze bliskiej limitu pamięci może wywołać ten sam restart, którego szukasz. Rób migawki na jednej instancji wyłączonej z load balancera albo na stagingu przy tym samym obciążeniu i zostaw zapas pamięci.

2. **Porównaj migawki.** Wczytaj obie do Chrome DevTools (karta **Memory**), wybierz drugą i przełącz widok na **Comparison**. Posortuj według różnicy rozmiaru i skopiuj 10 pierwszych konstruktorów ze ścieżkami obiektów zatrzymujących.

3. **Daj agentowi różnicę i poproś o ścieżkę zatrzymania.**

   **Prompt do skopiowania: wyjaśnij różnicę migawek sterty**

   ```text
   Two heap snapshots of our Express service, 30 minutes apart under constant load.
   Retained size grew about 100 MB. Top of the Comparison view, with retainer paths:
   <paste the 10 rows here>
   Name the object that keeps these alive and the code path that adds to it without
   removing. Quote the lines. Propose the smallest cleanup (an unsubscribe, a bounded
   cache, a removed listener), not a redesign. Then write scripts/soak-leak.mjs: run the
   leaking operation 10,000 times, call global.gc() before taking the baseline and
   again after the loop, then exit 1 if heapUsed grew more than 10 MB. The script must
   fail on the current code.
   ```

4. **Uruchom skrypt obciążeniowy (`soak-leak.mjs`) przed poprawką i po niej.** `global.gc()` wymaga flagi `--expose-gc`: `node --expose-gc scripts/soak-leak.mjs`. Zwykły skrypt Node’a zdejmuje pytanie, czy procesy robocze twojego runnera testów dziedziczą tę flagę. Najczęstsza przyczyna to nieograniczona kolekcja: listenery, timery albo wpisy cache dodawane przy każdym żądaniu i nigdy nieusuwane. Poprawka to ścieżka zwalniania, którą wywołujący rzeczywiście wywołują, a skrypt obciążeniowy uruchamiany w CI pokazuje, że robią to nadal.

## Wzorzec 4: odtwórz warunek wyścigu testem, który nie przechodzi

Bez testu, który najpierw nie przechodził, poprawka wyścigu to tylko nadzieja. Każ agentowi napisać test współbieżny, który nie przechodzi na obecnym kodzie, a potem wdrożyć najmniejsze zabezpieczenie, po którym test przejdzie.

**Prompt do skopiowania: od warunku wyścigu do testu, który nie przechodzi**

```text
Customers are charged twice when they double-click Pay, on roughly 5% of checkouts
under load. Write a Vitest test that fires 5 concurrent processPayment calls with the
same idempotency key and asserts that exactly one charge reaches the payment gateway
mock and the other four reject with ConflictError. Run it and show me it fails on the
current code. Then implement the smallest guard that makes it pass. We run 4 instances
behind a load balancer, so an in-memory lock is not enough: use the database.
Pass the idempotency key to the gateway call too, so a retry after a timeout
cannot create a second charge.
```

Lekcja siedzi w dwóch ostatnich zdaniach promptu. Bez nich najprostsze zabezpieczenie to `Map` w pamięci z kluczem po ID użytkownika. Taki kod przechodzi test w jednym procesie, a i tak pobiera opłatę dwa razy, gdy dwa kliknięcia trafią do dwóch instancji. Zabezpieczenie, które działa przy wielu instancjach, wygląda tak:

```typescript
async processPayment(key: string, payment: Payment) {
  // INSERT ... ON CONFLICT (idempotency_key) DO UPDATE SET status = 'pending'
  //   WHERE payment_attempts.status = 'failed'
  // against a unique index on idempotency_key:
  // only one instance can claim the key, however many receive the click
  const claimed = await db.paymentAttempts.insertIfAbsent({ idempotencyKey: key, status: 'pending' });
  if (!claimed) throw new ConflictError('Payment already processing');

  try {
    const charge = await gateway.charge(payment, { idempotencyKey: key });
    await db.paymentAttempts.update(key, { status: 'done', chargeId: charge.id });
    return charge;
  } catch (err) {
    // release the claim, or a gateway error leaves it 'pending' and every retry gets ConflictError
    await db.paymentAttempts.update(key, { status: 'failed' });
    throw err;
  }
}
```

Gałąź `catch` jest równie ważna jak samo zajęcie klucza: bez niej jeden timeout bramki blokuje ten klucz na zawsze. `insertIfAbsent` musi traktować wiersz `failed` jako ponownie do zajęcia. Zwolnienie klucza jest bezpieczne tylko dlatego, że klucz trafia też do bramki: timeout nie mówi, czy opłata przeszła, a bramka deduplikująca po tym samym kluczu zamienia ponowną próbę w odczyt zamiast drugiego obciążenia. Jeśli twoja bramka nie obsługuje klucza idempotencji, zostaw wiersz w `pending` i uzgodnij go z bramką, zanim pozwolisz na ponowną próbę. Zestaw testów potrzebuje drugiego przypadku, w którym mock bramki raz rzuca wyjątek, a ponowna próba się udaje.

Uruchom test co najmniej 20 razy w pętli, jak we wzorcu 1. Test współbieżności, który przeszedł raz, niewiele dowodzi.

## Wzorzec 5: odtwórz oś czasu między usługami według ID żądania

Gdy żądanie przechodzi przez kilka usług, żaden pojedynczy log nie wyjaśnia błędu; wyjaśnienie leży w lukach między przeskokami. Nadaj ID żądania na brzegu systemu, zbierz logi z każdego przeskoku i poproś agenta o odtworzenie osi czasu.

```bash
# Terminal. Collect one hour of logs from each hop (adjust to your platform)
for app in api-gateway order-service payment-service; do
  kubectl logs -l app=$app --since=1h --timestamps --tail=-1 | sed "s/ / [$app] /" > $app.log
done
grep -h "req_7f3a2c" *.log | sort | claude -p --permission-mode plan \
  "Rebuild the timeline for request req_7f3a2c across these services. Flag the longest gap."
```

`sed` oznacza każdą linię nazwą usługi zaraz po znaczniku czasu, więc `sort` nadal układa linie według czasu, a agent widzi, który przeskok wypisał daną linię. `--tail=-1` jest ważne: z selektorem etykiet `kubectl logs` zwraca tylko 10 ostatnich linii z każdego poda, jeśli nie ustawisz `--tail`, a agent odbudowałby oś czasu z niepełnych danych bez żadnego ostrzeżenia.

Logi produkcyjne zawierają dane użytkowników i ciągi, które użytkownicy kontrolują: najpierw zamaskuj adresy e-mail, tokeny i identyfikatory (na przykład filtrem `sed` w potoku) i uruchamiaj agenta tylko do odczytu, jak tutaj, bo linie logu mogą zawierać tekst, który brzmi jak polecenia. To samo dotyczy linii `[AUTH-DEBUG]` zebranych ze stagingu lub produkcji we wzorcu 1.

W Codeksie zamień ostatnie polecenie na `codex exec -s read-only` z tym samym promptem. W Cursorze dołącz trzy pliki przez `@` w Plan Mode.

**Prompt do skopiowania: oś czasu między usługami**

```text
Attached are logs from api-gateway, order-service and payment-service, each line with a
timestamp, the service name in brackets and a requestId. For requestId req_7f3a2c, list every event across the three
services in time order with the milliseconds since the previous event. Mark the longest
gap and name the service that owns it. Then list the log lines from that service in the
same window for other requestIds: is the gap specific to this request or shared (a pool,
a lock, a downstream timeout)? No fix yet.
```

Oś czasu zamienia „checkout czasem działa wolno” w „payment-service czekał 5 s na połączenie z bazą, bo pulę wyczerpało zadanie wsadowe”. Jeśli twoje usługi eksportują spany OpenTelemetry, daj agentowi ślad zamiast logów tekstowych: prompt działa bez zmian, a struktura rodzic–dziecko usuwa zgadywanie kolejności. Podłączenie samych śladów i alertów opisują [wzorce monitorowania i logowania](/pl/cookbook/devops-recipes/monitoring-logging/).

## Jak udowodnić poprawkę błędu bez czytania każdej linii?

Recenzent powinien zatwierdzać pull request z poprawką na podstawie dowodów, a kod czytać tylko tam, gdzie dowodu brakuje albo coś zaskakuje. Wymagaj w opisie pull requesta następujących elementów:

| Dowód | Co dowodzi | Kto go dostarcza |
| --- | --- | --- |
| Reprodukcja (test lub pętla) i jej wynik **przed** poprawką | Agent odtworzył zgłoszony błąd, a nie jego sąsiada | Agent, sprawdza programista |
| Ta sama reprodukcja **po** poprawce, z liczbą przebiegów | Przyczyna zniknęła, a nie tylko występuje rzadziej | Agent |
| Pełny zestaw testów, sprawdzanie typów i lint na zielono w CI | Nic innego się nie zepsuło | CI |
| Diagnoza w dwóch zdaniach: przyczyna i dowód na nią | Poprawka trafia w przyczynę, a nie w objaw | Programista |
| Przegląd diffu przez drugiego agenta względem tej diagnozy | Skutki uboczne, które zmęczony autor przeoczy | Osobny przebieg przeglądu |
| Wskaźnik błędów lub metryka po wdrożeniu, przez jeden szczyt ruchu | Poprawka trzyma się na produkcji | Programista, który wdrożył |

Wbudowane narzędzia przeglądu dają ogólny przegląd bez diagnozy: `/code-review` w sesji Claude Code, `codex exec review --uncommitted` w terminalu albo Bugbot na pull requeście w Cursorze. W Codeksie własne instrukcje i wskazanie diffu wykluczają się: `codex exec review "<prompt>"` bez flagi celu przyjmuje twoje instrukcje, ale `codex exec review --uncommitted "<prompt>"` kończy się błędem „the argument '--uncommitted' cannot be used with '[PROMPT]'” (sprawdzone w codex-cli 0.157.1).

Żeby przejrzeć poprawkę względem diagnozy, przekaż diff potokiem do nowej sesji bez interakcji, tylko do odczytu, z poniższym promptem: `git diff | claude -p --permission-mode plan "<review prompt>"` albo `git diff | codex exec -s read-only "<review prompt>"` (lub `codex exec review "<review prompt>"` bez flagi celu). W Cursorze wklej prompt w Plan Mode.

**Prompt do skopiowania: przegląd poprawki względem diagnozy**

```text
Review this diff as a bug fix. The diagnosis: <paste the two-sentence cause>.
Check three things and answer each with file:line evidence: (1) does the diff change the
code path the diagnosis names, (2) does it hide errors anywhere (optional chaining that
swallows a bug, empty catch, a default value for required data, a skipped or loosened
test), (3) does the new test fail if the fix is reverted? Report findings only; do not edit.
```

Zatwierdzanie: programista, który prowadził polowanie, odpowiada za dowody; recenzent, przy poprawce incydentu zwykle tech lead, zatwierdza, gdy obecny jest każdy wiersz. Agent nie może edytować testu reprodukującego, żeby przeszedł. [Ochrona wyroczni](/pl/workflows/test/protect-the-oracle/) pokazuje, jak uczynić to mechanicznie niemożliwym, zamiast polegać na zaufaniu.

## Co idzie nie tak, gdy agent debuguje za ciebie?

**Typowe awarie przy debugowaniu z agentem**

- **Wiarygodna, ale błędna przyczyna.** Przy skąpych dowodach agent wskazuje przyczynę pasującą do objawu. Co zrobić: żądaj poziomu pewności i wspierających linii logu, i nie przyjmuj poprawki, dopóki reprodukcja nie zawiedzie na kodzie bez poprawki.
- **Poprawka ucisza objaw.** Optional chaining, puste bloki `catch` albo ponawianie sprawiają, że błąd znika z logów. Co zrobić: prompt przeglądowy powyżej sprawdza właśnie to; odrzuć poprawkę i odeślij agenta do klasyfikacji „nie powinno się zdarzyć” albo „czasem się zdarza”.
- **Agent edytuje test.** Reprodukcja, która była czerwona, robi się zielona, bo poluzowano asercję. Co zrobić: przejrzyj `git diff` pliku testu osobno i trzymaj testy reprodukujące w ścieżce, do której agent nie ma prawa zapisu.
- **Instrumentacja ukrywa błąd.** Synchroniczne logowanie zmienia zależności czasowe i wyścig przestaje się odtwarzać. Co zrobić: loguj do bufora w pamięci i zrzucaj go po zakończeniu żądania albo loguj mniej pól.
- **Szum w logach zagłusza sygnał.** „Dodaj logowanie wszędzie” daje megabajty, których agent nie skoreluje. Co zrobić: ogranicz logowanie do podejrzanej ścieżki i jednego prefiksu, który da się wygrepować, jak we wzorcu 1.
- **Poprawka za poprawką, bez postępu.** Trzy nieudane poprawki z rzędu zwykle oznaczają błędny model systemu, a nie pecha. Co zrobić: przestań edytować, zacznij nową sesję z samymi dowodami i poproś o trzy uszeregowane hipotezy oraz obserwację, która wykluczy każdą z nich.
- **Nieaktualny kontekst.** Po długiej sesji agent rozumuje o kodzie, który od tego czasu się zmienił. Co zrobić: zacznij nową sesję albo uruchom ponownie polecenie bez interakcji na aktualnym stanie gałęzi, zanim zaufasz jego analizie.

## Dokąd dalej z debugowaniem

- Zacznij od przeglądu sekcji: [receptury obsługi błędów](/pl/cookbook/error-handling-recipes/).
- Pętle debugowania w konkretnych narzędziach: [Claude Code w terminalu](/pl/claude-code/test/debugging/), [Codex na wszystkich powierzchniach](/pl/codex/test/bug-hunting/) i [Plan Mode oraz tryb Agent w Cursorze](/pl/cursor-ide/test/bug-hunting/).
- Każdy błąd produkcyjny najpierw jako test: [programowanie sterowane błędami](/pl/method/principles/error-driven-development/).
- Dalej w tej sekcji: [wzorce logowania](/pl/cookbook/error-handling-recipes/logging-patterns/), czyli ustrukturyzowane logi, których potrzebują te prompty, a potem [wzorce odzyskiwania](/pl/cookbook/error-handling-recipes/recovery-patterns/) z ponawianiem i łagodną degradacją, gdy już znasz przyczynę.
