Debugowanie z AI w Cursorze

Polowanie na błędy z AI w Cursorze to pętla w trzech fazach: agent bada awarię bez edytowania kodu, odtwarza ją nieprzechodzącym testem albo skryptem obciążeniowym i dopiero potem nanosi w trybie Agent jedną celowaną poprawkę. Reprodukcja służy zarazem jako dowód, więc poprawkę przyjmuje się po przejściu testu z czerwonego na zielony, a nie po przekonująco wyglądającym diffie.

Ten poradnik jest dla programistów, którzy debugują z agentem Cursora, i dla tech leadów, którzy ustalają, jakie dowody musi nieść pull request z poprawką błędu. Sytuacja, którą rozwiązuje: od wtorkowego wdrożenia produkcja zwraca 500 mniej więcej na co siódme żądanie do kasy, diff to drobny refaktor kodu płatności, a jedyny tekst błędu to Transaction failed. Wklejasz błąd do trybu Agent i prosisz o poprawkę. Agent zmienia trzy pliki, inna grupa użytkowników dostaje teraz 403, a po dwudziestu minutach pierwotne 500 wraca.

Agent nie zawiódł jako programista. Kazano mu edytować, zanim ktokolwiek znał przyczynę. Debugowanie to problem przeszukiwania, a agent przeszukuje dobrze, kiedy nie pozwalasz mu edytować w trakcie szukania.

Co zyskujesz dzięki temu procesowi polowania na błędy

Plan „jeden tryb na fazę”, który trzyma agenta w trybie tylko do odczytu, dopóki przyczyna nie jest udowodniona
Osiem promptów do skopiowania: triaż objawów, reprodukcja, instrumentacja, porównanie logów, ograniczona poprawka, test regresyjny, który najpierw nie może przechodzić, kaskada błędów builda i diagnoza wyścigu
Przepis na git bisect run dla regresji, które zaczęły się od konkretnego wdrożenia
Listę dowodów, na podstawie której recenzent zatwierdzi poprawkę bez czytania każdej linii
Sposoby wyjścia z sześciu typowych sytuacji, w których debugowanie z AI idzie źle

Który tryb Cursora pasuje do której fazy debugowania?

Każda faza ogranicza to, co agent może zmienić. To ograniczenie, a nie model, zatrzymuje pętlę „napraw, zepsuj, napraw”.

Faza	Cel	Tryb w Cursorze	Agent może zmienić	Wychodzisz z fazy, gdy
1. Zbadaj	Uszeregowane, sprawdzalne hipotezy	Plan Mode (albo tryb Ask, jeśli jest w twoim selektorze)	Nic	Każda hipoteza wskazuje obserwację, która by ją obaliła
2. Odtwórz i zbierz dowody	Awaria wywoływana na żądanie	Tryb Agent ograniczony do testów, skryptów i logowania (albo tryb Debug, jeśli jest w twoim selektorze)	Nowe pliki testów, skrypty obciążeniowe, oznaczone linie logów	Test albo skrypt kończy się błędem z przewidzianego powodu
3. Napraw i udowodnij	Usunięta jedna przyczyna	Tryb Agent	Tylko pliki wskazane w diagnozie	Reprodukcja przechodzi, zestaw testów jest zielony, a logowanie diagnostyczne zniknęło

Plan Mode „tworzy szczegółowe plany implementacji, zanim napisze jakikolwiek kod”, więc to bezpieczne miejsce na myślenie. Zanim zaczniesz, zacommituj albo odłóż (git stash) swoją pracę, żeby git diff pokazywał tylko to, co agent zmieni w trakcie polowania. Punkt powrotu w obrębie jednej sesji opisuje poradnik o checkpointach i gałęziach.

Faza 1: zbadaj błąd bez dotykania kodu

Zamień objawy w uszeregowane hipotezy

Najpierw spisz wszystkie obserwowalne fakty: treść błędu, częstość, środowiska, w których występuje i w których nie, moment startu i to, co się zmieniło. Potem proś o hipotezy, które da się sprawdzić, a nie o poprawkę.

Do not edit any files. I want a diagnosis plan, not a fix.

Symptoms:
- POST /api/checkout returns 500 with the body "Transaction failed"
- About 15% of requests fail; the rest succeed with the same payload shape
- Production only; I cannot reproduce it on my laptop with single requests
- Started after Tuesday's 14:30 UTC deploy (a refactor of src/payment/processor.ts)
- Failures cluster during traffic peaks, but not exclusively
- The real exception is caught and rewrapped, so there is no stack trace

Read @src/checkout, @src/payment and @src/middleware.

List the five most likely root causes, ranked. For each one give:
1. The code location that makes it possible (file and function)
2. The evidence that supports it
3. The single observation that would rule it out
4. The cheapest way to make that observation (a log line, a metric, a test)

Spodziewaj się odpowiedzi w rodzaju: wyczerpanie puli połączeń, wyścig na współdzielonym stanie, niezgodne timeouty albo ścieżka błędu, która pomija sprzątanie. Najważniejszy jest punkt 3. Hipoteza, której żadna obserwacja nie może obalić, zjada popołudnie i nic nie daje.

Wciągnij dowody z produkcji do sesji przez serwer MCP

Gdy awaria występuje tylko na produkcji, daj agentowi prawdziwe zdarzenia zamiast swojego streszczenia. Oficjalny serwer Sentry MCP (getsentry/sentry-mcp, pakiet stdio @sentry/mcp-server 0.42.0, sprawdzony przez npm view 26 września 2026) udostępnia issues, zdarzenia i trace’y. Jego zdalny endpoint to https://mcp.sentry.dev/mcp, a Cursor deklaruje zdalny serwer przez URL w pliku projektu .cursor/mcp.json:

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

Zdalny serwer loguje cię przez OAuth, więc żaden token nie trafia do pliku. Pierwsze połączenie otwiera logowanie w przeglądarce, więc dodaj serwer i zaloguj się przed incydentem, a nie w jego trakcie. Każdy załadowany serwer dokłada też definicje swoich narzędzi do kontekstu agenta: jak utrzymać ten koszt w ryzach, pokazuje strona ograniczanie kosztu tokenów MCP. Potem zapytaj w tym samym trybie tylko do odczytu: „Find the most frequent unresolved error on the checkout endpoint in the last 24 hours, open its trace, and map each frame to a file in this repository. Do not edit anything.” Zysk jest taki, że agent czyta stack trace połknięty przez twój handler, zamiast zgadywać z opakowanego komunikatu. Inne serwery obserwowalności porównuje strona serwery MCP do obserwowalności.

Faza 2: odtwórz awarię i zbierz dowody z czasu wykonania

Odtwórz, zanim zdiagnozujesz

Reprodukcja jest warta więcej niż diagnoza, bo później jest też testem, który udowadnia poprawkę. Przy sporadycznej awarii pod obciążeniem niech tryb Agent napisze skrypt i nic poza nim.

Only create new files. Do not change any existing source file.

@src/checkout/route.ts @src/payment/processor.ts

Write a k6 script at tests/load/checkout-stress.js that:
1. Runs the real checkout flow against http://localhost:3000: create cart, add two items, POST /api/checkout
2. Ramps from 10 to 200 virtual users over 60 seconds, then holds for 30 seconds
3. Varies the payment amount and card type on each iteration
4. Counts responses by status code and counts bodies containing "Transaction failed"
5. Sets a threshold so the run fails when more than 1% of checkouts fail

Then tell me the exact command to run it and what output would confirm the bug.

Uruchom go poleceniem k6 run tests/load/checkout-stress.js. Jeśli odsetek błędów rośnie razem z liczbą wirtualnych użytkowników, masz reprodukcję. Jeśli zostaje na zerze, różnica między twoim laptopem a produkcją (wolumen danych, rozmiar puli, opóźnienia sieci) jest kolejną hipotezą do sprawdzenia.

Przy błędzie deterministycznym reprodukcją jest test jednostkowy albo integracyjny, który dziś nie przechodzi. Jak napisać go najpierw, opisuje TDD w Cursorze.

Instrumentuj ścieżkę, nie zachowanie

Jeśli selektor trybów oferuje tryb Debug, możesz go użyć w tym kroku. Ręczna wersja poniżej daje te same dowody w każdym trybie, a instrumentację łatwo potem usunąć.

Add diagnostic logging to the checkout flow to test these hypotheses: [PASTE THE TWO TOP HYPOTHESES FROM PHASE 1].

Log, using our logger in @src/lib/logger.ts at level 'debug':
1. Request received: request ID and user ID (never card data)
2. Database connection acquired and released: pool size, active and waiting counts
3. Before and after the payment gateway call: duration in milliseconds and outcome
4. Every early return and every catch block: the original error class and message before it is rewrapped

Prefix every line with [CHECKOUT_DEBUG] so it can be found and removed with one grep.
Do NOT change any business logic, control flow or error handling. Only add log statements.
When done, show me `git diff --stat` so I can confirm only logging changed.

Potem uruchom reprodukcję dwa razy i zachowaj jeden nieudany i jeden udany przebieg. Dopiero ich porównanie umożliwia diagnozę.

Do not edit any files.

Here is the [CHECKOUT_DEBUG] output of a FAILED checkout:
[PASTE FAILING LOG]

Here is the output of a SUCCESSFUL checkout from the same load run:
[PASTE PASSING LOG]

1. Where do the two executions first diverge?
2. Which of my hypotheses does this confirm, and which does it rule out?
3. Name the exact function and line that causes the failure, and explain the mechanism.
4. Predict what the load test will show once that cause is removed.

Punkt 4 to twoje kryterium akceptacji dla fazy 3. Typowe znalezisko w tym scenariuszu: processPayment pobiera połączenie z puli, a gałąź nieudanej walidacji wraca, zanim je zwolni. Pod obciążeniem pula się opróżnia, kolejne żądania dostają timeout w oczekiwaniu na połączenie, a blok catch opakowuje ten timeout jako Transaction failed. To opakowanie sprawia, że treść błędu nigdy nie wskazywała przyczyny.

Znajdź commit, który wprowadził regresję

Gdy błąd zaczął się od konkretnego wdrożenia, a masz reprodukcję, która przy awarii kończy się niezerowym kodem wyjścia, niech historię przeszuka git. Próg k6 z promptu o teście obciążeniowym już daje taki kod wyjścia. Test obciążeniowy potrzebuje świeżego serwera aplikacji na każdym commicie, więc zamknij kroki w małym skrypcie, na przykład tests/load/bisect.sh:

#!/bin/sh
npm ci >/dev/null || exit 125          # zależności z lockfile'a tego commita, nie poprzedniego
npm run build >/dev/null || exit 125   # commit, który się nie buduje, zostaje pominięty, a nie obwiniony
node dist/server.js & pid=$!           # uruchom sam serwer, nie wrapper npm
trap 'kill $pid 2>/dev/null' EXIT      # zatrzymaj go, jakkolwiek skończy się skrypt
sleep 5                                # czas na start serwera na localhost:3000
k6 run --quiet tests/load/checkout-stress.js

Potem oddaj sterowanie gitowi:

git bisect start HEAD abc1234        # najpierw zły commit, potem ostatni znany dobry
git bisect run sh tests/load/bisect.sh
git bisect reset                     # powrót do punktu wyjścia

Zamień abc1234 na commit wdrożony w poniedziałek. Git w każdym kroku dzieli zakres na pół, więc 12 commitów wymaga najwyżej czterech przebiegów. Kod wyjścia 125 mówi bisectowi, żeby pominął commit, którego nie da się przetestować, więc zepsuty build nigdy nie zostanie obwiniony o regresję. Zamień dist/server.js na punkt wejścia swojego builda: zabicie wrappera npm start potrafi zostawić prawdziwy serwer na porcie 3000, a wtedy kolejny krok testuje niewłaściwy commit. Port 3000 musi być wolny przed uruchomieniem git bisect run i przed każdym krokiem. Trzymaj bisect.sh poza testowanymi commitami (nieśledzony plik przetrwa każdy checkout) i wydłuż sleep, jeśli serwer startuje wolno.

Faza 3: napraw jedną przyczynę i udowodnij to

Ogranicz poprawkę do diagnozy

Dopiero teraz przełącz się na tryb Agent i wklej diagnozę, żeby agent pracował na dowodach, a nie na nowej własnej teorii.

Root cause (proven by the [CHECKOUT_DEBUG] traces): in @src/payment/processor.ts, processPayment acquires a pool connection and the validation-failure branch returns without releasing it. Under load the pool drains and later requests time out.

Fix only this:
1. Move input validation before the connection is acquired
2. Wrap all connection use in try/finally so release always runs
3. Keep the original error class when rewrapping, so logs show ConnectionTimeoutError instead of "Transaction failed"

Rules:
- Touch only src/payment/processor.ts and new test files. If another file must change, stop and tell me why first.
- No retries, no larger pool, no longer timeouts. Those hide the leak.
- Do not edit or delete existing tests.
- Remove every line containing [CHECKOUT_DEBUG] when you are done.

Reguła „bez ponowień” jest tam dlatego, że wrapper z ponowieniami to częsta, wiarygodnie wyglądająca, ale błędna poprawka: przez godzinę obniża odsetek błędów, a pod stałym obciążeniem opróżnia pulę jeszcze szybciej.

Napisz test regresyjny, który najpierw nie przechodzi

Test regresyjny dowodzi poprawki tylko wtedy, gdy nie przechodzi na nienaprawionym kodzie. Poproś o ten dowód wprost.

Write tests/payment/connection-leak.test.ts following the patterns in the existing payment tests.

It must:
1. Call processPayment with input that fails validation, 50 times in a row
2. Assert that the pool's active connection count returns to its starting value
3. Assert that a valid payment still succeeds afterwards

Prove the test is real:
- Run `git stash push src/payment/processor.ts`, run the new test, and show me that it FAILS
- Run `git stash pop`, run it again, and show me that it PASSES
- Then run the full test suite, the type check and the linter, and report each result

Jeśli test przechodzi na nienaprawionym kodzie, nie testuje tego błędu. Usuń go i opisz warunek awarii dokładniej. Jak nie dopuścić, żeby ktoś później dopasował test do kodu, wyjaśnia strona chroń wyrocznię.

Skąd wiesz, że poprawka jest dobra, bez czytania każdej linii?

Poprawkę przyjmujesz na podstawie dowodów, a nie tego, jak czyta się diff. Dołącz do pull requesta:

Dowód	Jak go uzyskać	Co udowadnia
Test regresyjny najpierw czerwony, potem zielony	Przebieg ze `stash` opisany wyżej, wynik wklejony do PR	Test wykrywa ten błąd, a poprawka go usuwa
Reprodukcja przed i po	`k6 run tests/load/checkout-stress.js` na starym i nowym commicie	Odsetek awarii spada tak, jak przewidziała faza 2
Wszystkie bramki zielone	Testy, sprawdzenie typów i lint w CI	Nic innego się nie zepsuło
Zakres zgodny z diagnozą	`git diff --stat` pokazuje tylko wskazany plik i nowe testy	Agent nie refaktoryzował przy okazji
Instrumentacja usunięta	`git grep -c CHECKOUT_DEBUG` nic nie zwraca	Żadne logowanie diagnostyczne nie trafia na produkcję
Niezależny przegląd	Bugbot albo drugi agent przegląda PR pod kątem diagnozy	Recenzent, który nie pisał poprawki, szukał skutków ubocznych

Zatwierdzenie: za dowody odpowiada programista, który prowadził polowanie. Recenzent, przy poprawce incydentu zwykle tech lead, zatwierdza, gdy każdy wiersz jest obecny, a diff czyta tylko tam, gdzie wiersza brakuje albo coś zaskakuje. Po wdrożeniu obserwuj ten sam błąd w monitoringu przez jeden szczyt ruchu, zanim zamkniesz incydent. Taki alert opisuje poradnik o monitoringu. Szerszą praktykę przedstawia strona dowody zamiast czytania kodu.

Jak debugować kaskady błędów builda i wyścigi w Cursorze?

Dwa powtarzalne rodzaje błędów potrzebują własnego przepisu: ściana błędów kompilatora z kilkoma ukrytymi przyczynami i utracona aktualizacja, która pojawia się tylko przy współbieżności.

Kaskada błędów builda albo typów

Czterdzieści błędów po podbiciu zależności ma zwykle dwie albo trzy przyczyny. Poprawianie ich po kolei według plików to najwolniejsza droga.

Run `npx tsc --noEmit` and read every error before changing anything.

1. Group the errors by root cause (a changed type, a removed export, a renamed module). Show me the groups.
2. Fix the root cause of the largest group first, then re-run the type check.
3. Repeat until it passes.

Do not use `any`, `as` casts, `@ts-ignore` or `@ts-expect-error` to silence an error. If the correct fix needs a design decision, stop and ask me.

Jak zdiagnozować wyścig z pomocą agenta?

Do not edit any files yet.

When two requests update the same user at the same time, the second write overwrites the first. Relevant code: @src/services/user-service.ts

1. Name the read-modify-write sequence that is not atomic, with file and line
2. Describe the interleaving that loses the update, step by step
3. Compare three fixes for this codebase: a conditional update with a version column, a database transaction with row locking, and an in-process mutex. Say which one still works with several server instances.
4. Write a test that fires 20 concurrent updates and asserts that none is lost. It must fail on the current code.

Logowanie potrafi zmienić zależności czasowe na tyle, że wyścig znika. Jeśli błąd przestaje występować po dodaniu instrumentacji, zapisuj znaczniki czasu z process.hrtime.bigint() do tablicy w pamięci i wypisz je po przebiegu, żeby gorąca ścieżka nie robiła żadnego I/O.

Jak spisać post-mortem po poprawce z AI?

W tej samej sesji, w Plan Mode albo trybie Ask, poproś agenta o post-mortem z podsumowaniem, osią czasu, przyczyną, poprawką, luką w wykrywaniu, prewencją i zadaniami do wykonania, zapisany w docs/postmortems/. Luka w wykrywaniu („dlaczego monitoring pokazywał Transaction failed zamiast timeoutu?”) zwykle daje najcenniejsze zadanie. Przed publikacją sprawdź oś czasu z dziennikiem incydentu: agent wie tylko to, co widziała sesja.

Które powtarzalne błędy zasługują na zapisany prompt?

Prompty, do których wracasz, zapisz jako Rule albo Agent Skill, żeby dostał je cały zespół. Format pokazuje poradnik o Rules. Jeśli wolisz gotową metodę, skill systematic-debugging z obra/superpowers jest przeznaczony do użycia „when encountering any bug, test failure, or unexpected behavior, before proposing fixes” i prowadzi agenta przez badanie przyczyny, analizę wzorców i testowanie hipotez, zanim przejdzie do implementacji. Zainstaluj go dla Cursora przez CLI skills (1.7.0, sprawdzone 26 września 2026):

npx skills add obra/superpowers --skill systematic-debugging -a cursor

Przeczytaj SKILL.md przed instalacją: otwarte zgłoszenie #2277 (10 września 2026) opisuje, że katalog skilla zawiera pliki scenariuszy testów presji (pressure tests), które kopiują się do katalogu uruchomieniowego. Więcej opcji porównuje strona skille do testowania i debugowania.

Kiedy debugowanie z AI w Cursorze idzie źle

Pętla „napraw, zepsuj, napraw”. Agent edytuje, psuje się coś innego, agent edytuje znowu. Wyjście: git stash albo przywrócenie ostatniego czystego commita, powrót do Plan Mode i niewychodzenie z fazy 1, dopóki każda hipoteza nie ma obserwacji, która może ją obalić.

Pewna siebie, ale błędna przyczyna. Wyjaśnienie brzmi dobrze, a poprawka niczego nie zmienia. Wyjście: przewidywanie z fazy 2 to ujawnia. Jeśli test obciążeniowy nie zmienia się tak, jak przewidziała diagnoza, diagnoza jest błędna, choćby brzmiała przekonująco. Wróć do porównania przebiegów z nowymi danymi.

Poprawka ukrywa objaw. Ponowienia, większa pula albo dłuższy timeout sprawiają, że błąd występuje rzadziej, ale jego przyczyna zostaje. Wyjście: odrzuć diff i powtórz regułę „napraw przyczynę wskazaną w diagnozie; bez ponowień, bez zmian puli i timeoutów”.

Agent zmienia test zamiast kodu. Test regresyjny nagle przechodzi, bo zmieniła się jego asercja. Wyjście: napisz „The test is correct. The implementation is wrong. Do not modify tests/payment/connection-leak.test.ts.” i zanim cokolwiek przyjmiesz, sprawdź w git diff --stat, czy nie zmieniły się pliki testów.

Instrumentacja nie łapie awarii. Logi nie pokazują różnicy między przebiegiem nieudanym a udanym. Wyjście: błąd siedzi gdzie indziej w łańcuchu wywołań. Rozszerz logowanie o jedną warstwę na zewnątrz (middleware, sterownik bazy, klient HTTP) i zbierz kilka nieudanych próbek, bo pojedyncza próbka sporadycznej awarii potrafi zmylić.

Nic nie odtwarza się lokalnie. Niektóre awarie wymagają produkcyjnych wolumenów danych, prawdziwych opóźnień albo konkretnej infrastruktury. Wyjście: dodaj ustrukturyzowane, oznaczone logowanie za flagą, wdróż je, przeanalizuj wyjście z produkcji w Plan Mode albo trybie Ask i poproś agenta o sprawdzenie changeloga i issue trackera biblioteki, która zawodzi, pod kątem znanych wycieków i timeoutów w twojej wersji.

Dokąd dalej po naprawieniu błędu

TDD w Cursorze Przy nowej pracy pisz najpierw nieprzechodzący test, żeby mniej błędów trafiało na tę stronę.

Wzorce testowania Zbuduj zestaw testów jednostkowych, integracyjnych i end-to-end, który łapie tę klasę błędów.

Tryby agenta od środka Czym różnią się Plan Mode i tryb Agent i kiedy przełączać się między nimi.

Wzorce debugowania (cookbook) Przepisy niezależne od narzędzia na wycieki pamięci, timeouty i niestabilne awarie.

Debugowanie w Claude Code Ta sama pętla zbadaj, odtwórz, napraw z poziomu terminala.

Polowanie na błędy w Codex Debugowanie zaczynające się od reprodukcji w aplikacji Codex, CLI i chmurze.