Workflow debugowania

Twój endpoint API zwraca błąd 500, ale tylko dla niektórych użytkowników. Wklejasz błąd do trybu Agent Cursora i mówisz “napraw to”. Agent zmienia trzy pliki, błąd znika dla twojego przypadku testowego, ale teraz inna grupa użytkowników dostaje błąd 403. Mówisz agentowi, żeby naprawił i to. Dwie kolejne zmiany plików. Teraz oryginalny błąd 500 wrócił. Od 20 minut kręcisz się w kółko i jesteś dalej od naprawy niż na początku.

Problem nie leży w Cursorze. Problem polega na traktowaniu debugowania jako “powiedz AI, żeby naprawiło i miej nadzieję”. Skuteczne debugowanie wspomagane AI to ustrukturyzowany proces: najpierw zbadaj, zrozum przyczynę źródłową, a potem zastosuj celowaną poprawkę.

Czego się nauczysz

• Systematyczny workflow debugowania z użyciem trybów Ask, Debug i Agent w sekwencji
• Gotowe prompty do skopiowania na każdy etap procesu debugowania
• Techniki wykorzystywania logów, śladów błędów i danych runtime z AI
• Wzorce zapobiegające pętli “napraw-zepsuj-napraw”

Trzyfazowy workflow debugowania

Faza 1: Zbadaj (tryb Ask)

Zanim dotkniesz jakiegokolwiek kodu, zrozum co się dzieje:

Wskazówka

Prompt do skopiowania — badanie:

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.

To daje ci model mentalny problemu, zanim zaczniesz cokolwiek zmieniać.

Faza 2: Zbierz dowody (tryb Debug lub ręczne logowanie)

Gdy masz hipotezy, zbierz dowody z runtime, aby je potwierdzić lub wykluczyć.

Opcja A: Użyj trybu Debug

Przełącz na tryb Debug i opisz błąd. Agent:

1. Wygeneruje hipotezy o przyczynach źródłowych
2. Doda strategiczne instrukcje logowania do kodu
3. Poprosi cię o odtworzenie błędu
4. Przeanalizuje przechwycone logi
5. Zidentyfikuje przyczynę źródłową na podstawie dowodów

Opcja B: Ręczne logowanie i analiza

Jeśli tryb Debug nie jest dostępny lub wolisz ręczną kontrolę:

Wskazówka

Prompt do skopiowania — dodawanie 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.

Po odtworzeniu błędu wklej logi z powrotem do Cursora:

Wskazówka

Prompt do skopiowania — analiza 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.

Faza 3: Celowana poprawka (tryb Agent)

Dopiero po zrozumieniu przyczyny źródłowej przełącz się na tryb Agent, aby naprawić:

Wskazówka

Prompt do skopiowania — celowana poprawka:

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]')

Wzorzec napraw-potem-zweryfikuj

Po każdej poprawce zweryfikuj, że faktycznie działa, dodając 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 nie przechodzi, wiesz, że poprawka jest niekompletna. Jeśli przechodzi, masz test regresji, który zapobiega powrotowi tego błędu.

Typowe wzorce debugowania

Wzorzec: Badanie błędu typów

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.

Wzorzec: Analiza warunków wyścigu

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.

Wzorzec: Kaskada błędów budowania

Gdy masz wiele błędów budowania, nie naprawiaj ich po jednym:

Wskazówka

Prompt do skopiowania — rozwiązywanie błędów budowania:

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.

To workflow w stylu TDD, który spopularyzował Steve Sewell z Builder.io: pozwól agentowi uruchomić budowanie, zobaczyć błędy, naprawić je i iterować, aż wszystko przejdzie — wszystko automatycznie, gdy auto-run jest włączony.

Kiedy coś nie działa

Pętla “napraw-zepsuj-napraw”. Pomijasz fazę 1 (badanie). Wróć do trybu Ask, zrozum system, a potem dokonaj jednej celowanej zmiany.

Agent “naprawia” test zamiast kodu. Wyraźnie powiedz: “The test is correct. The implementation is wrong. Fix the implementation to make the test pass.”

Logi trybu Debug nie wyłapują problemu. Błąd może być w innej części łańcucha wywołań niż oczekiwano. Poproś agenta o dodanie logowania szerzej lub odtwórz błąd wielokrotnie, aby wyłapać przerywane zachowanie.

Zbyt wiele błędów do naprawienia naraz. Triażuj: najpierw napraw błędy kompilacji (blokują wszystko inne), potem błędy runtime, a na koniec błędy logiki. Użyj wzorca kaskady błędów budowania opisanego powyżej.

Co dalej

• Wzorce testowania — Pisanie testów zapobiegających nawrotom błędów
• Strategie refaktoryzacji — Porządkowanie kodu po naprawach błędów
• Workflow recenzji — Wyłapywanie błędów zanim dotrą na produkcję