Debugowanie z AI w Cursorze

Polowanie na błędy w Cursorze ma trzy fazy i osobny tryb dla każdej: tryb Ask bada objawy i porządkuje hipotezy, tryb Debug oprzyrządowuje kod i zbiera dowody z czasu wykonania, a tryb Agent nanosi jedną celowaną poprawkę wraz z testem regresyjnym. Ta kolejność istnieje po to, żeby nie wpaść w pętlę napraw-zepsuj-napraw, którą produkuje zgadywanie.

Produkcja zwraca 500 przy 15% żądań do kasy. Na dev działa bez zarzutu. Zaczęło się po wtorkowym wdrożeniu, ale diff wygląda niewinnie — drobny refaktor logiki płatności — a komunikat błędu brzmi wybitnie bezużytecznie: “Transaction failed”. Prezes prosi o aktualizację co pół godziny.

Kuszące jest wkleić błąd do trybu Agent i napisać “napraw to”. Zmienia trzy pliki, twój przypadek testowy przechodzi, a teraz inna grupa użytkowników dostaje 403. Każesz naprawić i to. Kolejne dwa pliki. Pierwotne 500 wraca, a po dwudziestu minutach jesteś dalej od rozwiązania niż na początku.

Problemem nie jest Cursor. Problemem jest traktowanie debugowania jako “każ AI naprawić i licz na szczęście”. Debugowanie to problem przeszukiwania, a AI przeszukuje bardzo dobrze — pod warunkiem, że każesz mu szukać, zanim zacznie edytować.

Co daje systematyczne polowanie na błędy

• Trzyfazowy przepływ, w którym tryby Ask, Debug i Agent robią to, w czym każdy jest naprawdę dobry
• Prompt generujący hipotezy, który zamienia objawy w uszeregowane, sprawdzalne teorie
• Przepływ w trybie Debug, który oprzyrządowuje kod, zbiera dane z czasu wykonania i wyprowadza przyczynę z dowodów
• Prompt do testu obciążeniowego odtwarzającego sporadyczną awarię lokalnie
• Prompty copy-paste do błędów typów, wyścigów i kaskady błędów builda
• Szablon post-mortem dokumentujący błąd, poprawkę i zapobieganie

Debugowanie jako problem przeszukiwania: trzy fazy

Każda faza ma swój tryb, a tryb ma znaczenie, bo ogranicza to, co AI wolno zrobić:

1. Badaj w trybie Ask. Tylko do odczytu. Budujesz obraz awarii i nic nie powinno się w tym czasie zmienić.
2. Zbieraj dowody w trybie Debug (albo ręcznym logowaniem). Wyłącznie oprzyrządowanie, żadnych zmian zachowania.
3. Naprawiaj w trybie Agent. Jedna celowana zmiana plus test regresyjny, który to potwierdza.

Przeskok od razu do trzeciej fazy to właśnie źródło pętli napraw-zepsuj-napraw.

Faza 1: badaj, zanim dotkniesz kodu

Zamiana objawów w uszeregowane hipotezy

Najpierw zbierz wszystkie obserwowalne fakty, a potem poproś o teorie, które da się sprawdzić:

Wskazówka

Prompt copy-paste — analiza objawów:

I have a production bug with these symptoms:

- Error: "Transaction failed" on checkout endpoint (POST /api/checkout)
- Frequency: ~15% of requests, seemingly random
- Environment: production only, cannot reproduce in dev
- Timeline: started after deployment on Tuesday at 14:30 UTC
- Pattern: seems to correlate with traffic spikes but not exclusively
- Error logs show the failure happens in the payment processing step
- No stack trace -- the error is caught and wrapped in a generic message

@src/checkout @src/payment @src/middleware

Based on the code and symptoms, what are the top 5 most likely root causes, ranked by probability? For each hypothesis, tell me:
1. What evidence supports it
2. What evidence would confirm or rule it out
3. What specific log line or metric I should look for

Spodziewaj się odpowiedzi w rodzaju wyczerpania puli połączeń, wyścigu, źle ustawionego timeoutu albo brakującej obsługi błędu na jednej ze ścieżek. Kolejność liczy się mniej niż punkty drugi i trzeci: hipoteza, której nie umiesz potwierdzić ani odrzucić, to teoria, która zje ci popołudnie.

Mapowanie łańcucha wywołań

Gdy zamiast listy objawów masz stack trace, poproś o ścieżkę, a nie o teorię:

Wskazówka

Prompt copy-paste do badania problemu:

I am seeing this error in production:

[PASTE FULL ERROR MESSAGE AND STACK TRACE]

It affects about 20% of requests to POST /api/orders/create.

Without making any changes, help me understand:
1. What is the call chain from the route to where the error occurs?
2. What are the possible causes based on the stack trace?
3. What data or conditions could make this fail for some users but not others?
4. What additional information would help narrow down the root cause?

Search the codebase for the relevant files.

Fraza “Without making any changes” naprawdę tam pracuje. To różnica między obrazem sytuacji w głowie a niespodziewanym diffem.

Faza 2: zbierz dowody z czasu wykonania

Tryb Debug

Cursor ma do tego osobny tryb Debug. Przełączysz się na niego w wyborze trybu albo skrótem Cmd+. / Ctrl+.. W odróżnieniu od trybu Agent prowadzi ustrukturyzowane śledztwo:

1. Przegląda istotne pliki i generuje hipotezy
2. Dokłada oprzyrządowanie (instrukcje logowania) raportujące do lokalnego serwera debugowania
3. Prosi cię o odtworzenie błędu
4. Analizuje zebrane dane z czasu wykonania
5. Proponuje celowaną poprawkę opartą na dowodach, a nie na zgadywaniu

The checkout endpoint at POST /api/checkout is returning "Transaction failed"
for ~15% of requests under load. The error happens in the payment processing
step. I can reproduce it locally using a load testing tool (k6 or similar)
that sends 200 concurrent requests.

Find the root cause using instrumentation.

Tryb Debug dokłada logi w miejscach, które mają znaczenie — pobranie połączenia z bazą, wywołania API płatności, granice transakcji — i prosi o wywołanie błędu. Mając dane z czasu wykonania, zwykle wskazuje problem w kilka minut.

Notatka

Tryb Debug sprawdza się najlepiej wtedy, gdy potrafisz odtworzyć błąd lokalnie. Jeśli widzisz go wyłącznie na produkcji, podaj zamiast tego logi produkcyjne jako kontekst i analizuj w trybie Ask albo Agent.

Ręczne logowanie i analiza

Gdy tryb Debug jest niedostępny albo chcesz mieć ściślejszą kontrolę, zrób to samo ręcznie. Najpierw oprzyrządowanie:

Wskazówka

Prompt copy-paste do dołożenia logów diagnostycznych:

Add detailed logging to the order creation flow to help diagnose an intermittent 500 error.

Add logs at these points:
1. Request received (log the full request body and user ID)
2. Before validation (log what the validator receives)
3. After validation (log the validated data)
4. Before database insert (log the query parameters)
5. After database response (log success or error)
6. At the catch block (log the full error with stack trace)

Use our logger from @src/lib/logger.ts with log level 'debug'.
Tag all logs with prefix '[ORDER_DEBUG]' so I can grep for them.

Do NOT change any business logic. Only add logging.

Potem odtwórz błąd i przynieś dwa przebiegi, nie jeden. To porównanie umożliwia postawienie diagnozy:

Wskazówka

Prompt copy-paste do analizy logów:

Here are the debug logs from a failed order creation request:

[PASTE LOGS HERE]

And here are logs from a successful request for comparison:

[PASTE LOGS HERE]

Based on the difference between these two executions, what is causing the failure? Be specific about which line of code is responsible and why.

Celowe odtworzenie sporadycznej awarii

Jeśli nie umiesz wywołać błędu ręcznie, niech tryb Agent zbuduje coś, co umie:

Wskazówka

Prompt copy-paste — generowanie testu obciążeniowego:

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

Generate a k6 load test script that:

1. Simulates the exact checkout flow (create cart, add items, initiate checkout, process payment)
2. Ramps from 10 to 200 concurrent users over 60 seconds
3. Uses realistic payment data (varying amounts, different card types)
4. Tracks: response times, error rates by status code, the specific "Transaction failed" error message
5. Reports which requests failed and the exact response body
6. Runs against localhost:3000

The goal is to reproduce the ~15% failure rate we see in production.
Save as tests/load/checkout-stress.js.

Test obciążeniowy odtwarzający awarię jest wart więcej niż diagnoza, którą przyniesie, bo to nim później zweryfikujesz poprawkę.

Czytanie dowodów

@logs/debug-output.log @src/payment/processor.ts

Here are the debug logs from the load test. Analyze them and answer:

1. Which requests failed and what do they have in common?
2. What is the timing pattern? Do failures cluster at specific intervals?
3. Is there a resource that's being exhausted (connections, file handles, memory)?
4. Can you identify the exact line where the failure originates?
5. What is the root cause?

Show me the specific code that needs to change and explain why.

Typowe ustalenie w takim scenariuszu: procesor płatności pobiera połączenie z bazą i nie zwalnia go na części ścieżek błędu. Pod obciążeniem pula się wyczerpuje, a wynikły timeout zostaje opakowany w ogólny komunikat “Transaction failed” — i dlatego treść błędu nigdy nie wskazywała prawdziwego problemu.

Faza 3: celowana poprawka

Napraw przyczynę i tylko przyczynę

Dopiero teraz przełącz się na tryb Agent i nałóż na niego ograniczenia. Szablon poniżej warto zachować:

Wskazówka

Prompt copy-paste do celowanej poprawki:

The root cause of the intermittent 500 error in order creation is: [YOUR DIAGNOSIS FROM PHASE 2]

Fix this by:
1. [SPECIFIC CHANGE 1]
2. [SPECIFIC CHANGE 2]

Do NOT refactor other code. Make the minimum change needed to fix this specific issue.

After making the fix:
1. Run the existing tests to make sure nothing else broke
2. Add a test case that reproduces the exact scenario that was failing
3. Remove the debug logging I added earlier (all lines with '[ORDER_DEBUG]')

Wypełniony pod opisany wyciek połączeń ten sam szkielet staje się konkretem — zwróć uwagę, jak duża jego część dotyczy tego, by następny taki przypadek dało się zdiagnozować, a nie samego wycieku:

Wskazówka

Prompt copy-paste — wdrożenie poprawki:

@src/payment/processor.ts

The root cause is a database connection leak: when payment validation fails on line 47, the function returns early without releasing the connection acquired on line 32. Under load, the pool exhausts and subsequent requests timeout.

Fix this by:

1. Moving the validation BEFORE the connection acquisition (no connection needed for input validation)
2. Wrapping the entire connection usage in a try/finally that guarantees release
3. Replacing the generic "Transaction failed" error with specific error types: ValidationError, PaymentGatewayError, ConnectionTimeoutError -- each with a unique error code
4. Adding connection pool metrics logging (pool size, active connections, waiting requests) on every checkout request
5. Creating a regression test in tests/payment/connection-leak.test.ts that verifies the connection is released even when validation fails

Run the load test after the fix to verify the error rate drops to 0%.

Test regresyjny, który to potwierdza

Każda poprawka dostaje test, który wyłapałby ten błąd:

Add a regression test for the bug we just fixed.

The test should:
1. Set up the exact conditions that caused the failure (user with [specific condition])
2. Call the endpoint with the same request that was failing
3. Assert that it succeeds with the correct response
4. Also test the edge case where [related condition]

Put the test in @src/routes/__tests__/orders.test.ts following existing patterns.
Run the test to confirm it passes.

Jeśli test upada, poprawka była niepełna. Jeśli przechodzi, masz coś, co nie pozwoli błędowi wrócić.

Znalezienie commita, który to wprowadził

Gdy błąd zaczął się po konkretnym wdrożeniu, a ty masz wiarygodny test, niech szuka git:

The checkout load test passes on commit abc123 (Monday) but fails on HEAD (Tuesday).
There are 12 commits between them. Help me set up a git bisect:

1. Create a script that runs the load test and returns exit code 0 if fewer than 1% of
   requests fail, exit code 1 otherwise
2. Show me the git bisect commands to find the exact commit that introduced the regression

Dwanaście commitów zawęża się do jednego w mniej więcej cztery iteracje.

Powtarzalne przypadki warte zapisanego promptu

Błędy typów wskazujące nie to miejsce

TypeScript reports this error at build time:

[PASTE TSC ERROR]

Trace the types involved. Show me:
1. Where the type is defined
2. How it flows through the code to this point
3. Why the types are incompatible
4. The minimal fix that maintains type safety

Do not use `any` or type assertions to fix this. Find the real type issue.

Wyścigi

This code has a race condition -- when two requests arrive simultaneously
for the same user, the second request overwrites the first one's data.

Relevant code: @src/services/user-service.ts

Analyze the concurrent execution paths and identify:
1. Which operation is not atomic
2. Where the race window exists
3. The best fix (optimistic locking, database transaction, or mutex)

Show me the fix with before/after code comparison.

Kaskada błędów builda

Przy wielu błędach builda poprawianie ich po kolei to droga najwolniejsza — większość jest skutkiem jednego prawdziwego problemu:

Wskazówka

Prompt copy-paste do rozbrojenia błędów builda:

Run `npm run build` (or `tsc --noEmit`) and see the errors.

Fix all build errors. Start with the root causes (often a type change or missing import), not the downstream effects. A single root fix often resolves 5-10 cascading errors.

After fixing, run the build again. Repeat until the build passes.

Przy włączonym auto-run agent uruchamia build, czyta błędy, poprawia je i iteruje, aż przejdzie — pętla, którą spopularyzował Steve Sewell z Builder.io.

Spisanie post-mortem

Krok, który większość zespołów pomija, i ten o najdłuższym zwrocie. Napisz szkic w trybie Ask, póki sesja jest jeszcze w kontekście:

Based on this debugging session, write a post-mortem document covering:

1. Summary: what broke, who was affected, how long it lasted
2. Timeline: when it started, when detected, when fixed
3. Root cause: the connection leak in payment processing
4. Fix: what changed and why
5. Detection gap: why our monitoring didn't catch this sooner
6. Prevention: what we will do to prevent similar bugs (connection pool alerting, code review checklist for resource cleanup)
7. Action items with owners and deadlines

Save to docs/postmortems/2026-02-checkout-connection-leak.md

Gdzie debugowanie z AI się psuje

Utknąłeś w pętli napraw-zepsuj-napraw. Faza pierwsza została pominięta. Wróć do trybu Ask, zbuduj obraz systemu, a potem wprowadź dokładnie jedną celowaną zmianę.

Oprzyrządowanie zmienia zachowanie błędu. Instrukcje logowania przesuwają czasy na tyle, że wyścig znika — klasyczny heisenbug. Sięgnij po lżejsze oprzyrządowanie: inkrementuj liczniki atomowe zamiast logować napisy albo zbieraj znaczniki process.hrtime(), które nie wymagają wejścia/wyjścia.

AI podaje wiarygodną, ale błędną przyczynę. Modele dobrze dopasowują wzorce i potrafią mylić się z pełnym przekonaniem. Zweryfikuj przed wdrożeniem: jeśli diagnoza jest trafna, poprawka powinna zbić odsetek błędów w teście obciążeniowym prawie do zera.

Poprawka zamiata objaw pod dywan. Klasyczna zła poprawka to opakowanie awaryjnej operacji w ponowienia zamiast zatkania wycieku. Ponowienia na chwilę maskują wyczerpanie puli, a przy dłuższym obciążeniu pogarszają sprawę. Nie zgadzaj się i poproś o przyczynę.

Agent “naprawia” test zamiast kodu. Powiedz to wprost: “The test is correct. The implementation is wrong. Fix the implementation to make the test pass.”

Oprzyrządowanie nie łapie problemu. Błąd siedzi w innym miejscu łańcucha wywołań, niż zakładałeś. Rozszerz logowanie albo odtwórz awarię kilka razy — zachowanie sporadyczne potrzebuje więcej niż jednej próbki.

Nic nie odtwarza się lokalnie. Część błędów potrzebuje produkcyjnych wolumenów danych, prawdziwych opóźnień sieci albo konkretnego sprzętu. Oprzyrząduj produkcję logowaniem strukturalnym i analizuj je w trybie Ask, a agentowi każ poszukać znanych problemów w bibliotece albo usłudze, która zawodzi.

Ślad prowadzi do node_modules. Sprawdź przez @Docs zgłoszenia i changelog biblioteki, a potem zapytaj wprost: “Has this library been reported to have connection leaks or timeout issues in recent versions?”

Błędów jest za dużo, żeby je posegregować. Najpierw napraw błędy kompilacji, bo blokują wszystko inne, potem błędy czasu wykonania, a na końcu błędy logiki — z użyciem promptu na kaskadę builda powyżej.

Dokąd dalej po naprawieniu błędu

Wzorce testowania Pisz testy, które nie pozwolą tej klasie błędów wrócić.

Strategie refaktoryzacji Uporządkuj strukturę, którą błąd obnażył, gdy poprawka już wejdzie.

Integracja z API Buduj odporne integracje z API, z ponowieniami i bezpiecznikami, które zapobiegają takim awariom.

Optymalizacja wydajności Znajduj wąskie gardła, zanim zamienią się w incydenty produkcyjne.