Debugowanie i odzyskiwanie po błędach

Agent właśnie zrefaktoryzował twój moduł uwierzytelniania. Przeniósł funkcje między plikami, zaktualizował importy i dodał nową warstwę walidacji. Testy przechodzą — ale strona logowania wyświetla biały ekran w przeglądarce. Terminal nie pokazuje błędów. Agent jest pewny że jego zmiany są poprawne. Witaj w rzeczywistości rozwoju wspomaganego przez AI: kod wygląda dobrze, przechodzi lint i psuje się w sposób subtelny i frustrujący. Ten artykuł to twój przewodnik terenowy do diagnozowania i odzyskiwania dokładnie z takich sytuacji.

Co wyniesiesz z tego rozdziału

• Systematyczne podejście do debugowania kodu generowanego przez AI które różni się od debugowania kodu pisanego przez ludzi
• Opanowanie systemu checkpointów Cursor dla natychmiastowego rollbacku
• Przepływ pracy trybu debugowania dla trudnych błędów wymagających dowodów runtime
• Wzorzec czyszczenia “pre-PR” który wyłapuje problemy zanim dotrą do twojego zespołu
• Strategie odzyskiwania gdy agent utknął w pętli

Natura błędów generowanych przez AI

Błędy generowane przez AI różnią się od błędów ludzkich. Zrozumienie różnicy zmienia sposób debugowania:

Błędy ludzkie	Błędy generowane przez AI
Literówki i błędy off-by-one	Strukturalnie poprawne ale semantycznie błędne
Zapomniane przypadki brzegowe	Pewność co do błędnych założeń
Błędy kopiowania-wklejania	Spójny wzorzec zastosowany do złego kontekstu
Błędy logiczne w złożonych przepływach	Działający kod który rozwiązuje zły problem

Najbardziej niebezpieczne błędy AI to te które wyglądają całkowicie rozsądnie. Kod kompiluje się, typy się zgadzają, testy przechodzą — ale zachowanie jest subtelnie błędne ponieważ agent źle zrozumiał wymaganie lub zastosował wzorzec z niewłaściwej części twojej bazy kodu.

Odzyskiwanie checkpointu

Cursor tworzy checkpoint przed każdym zestawem zmian które agent wprowadza. To twoje najważniejsze narzędzie odzyskiwania.

Jak działają checkpointy

Za każdym razem gdy agent modyfikuje pliki, Cursor zapisuje stan wszystkich zmienionych plików. Możesz zobaczyć checkpointy na osi czasu rozmowy jako numerowane znaczniki.

Przywracanie checkpointu

1. Znajdź checkpoint na osi czasu rozmowy (przed problematyczną zmianą)
2. Kliknij przycisk Restore obok niego
3. Wszystkie pliki wracają do stanu z tego checkpointu
4. Twoja historia rozmowy jest zachowana — tylko pliki się zmieniają

Strategia checkpointów

Dla złożonych zadań, twórz wyraźne punkty przywracania commitując do gita między fazami:

[Agent buduje schemat bazy danych] --> git commit
[Agent buduje endpointy API] --> git commit
[Agent buduje frontend] --> git commit

Jeśli praca nad frontendem pójdzie źle, możesz przywrócić checkpoint i nadal mieć pracę nad API bezpiecznie zacommitowaną w git.

Notatka

Checkpointy są lokalne dla Cursor i twojej sesji. Commity git są trwałe i możliwe do udostępnienia. Używaj checkpointów dla szybkiego eksperymentowania, commitów git dla prawdziwego zachowania kamieni milowych.

Tryb debugowania

Cursor oferuje dedykowany tryb debugowania dla błędów które są trudne do odtworzenia lub zrozumienia tylko z czytania kodu. Tryb debugowania przyjmuje inne podejście niż standardowy tryb Agent: zamiast natychmiast pisać poprawki, instrumentuje twój kod, zbiera dowody runtime i dopiero wtedy wprowadza celowane poprawki.

Kiedy używać trybu debugowania

• Błąd jest odtwarzalny ale przyczyna nie jest oczywista z kodu
• Race conditions lub problemy zależne od czasu
• Problemy wydajności wymagające profilowania
• Regresje gdzie coś działało a teraz nie działa

Jak działa tryb debugowania

Przełącz na tryb debugowania z wyboru trybu (Cmd+.).

1. Opisz błąd

   The login form submits successfully (200 response) but the user is not
   redirected to the dashboard. The session cookie appears to be set correctly.
   This started happening after the auth refactor yesterday.

2. Agent generuje hipotezy

   Agent eksploruje istotne pliki i proponuje wiele możliwych przyczyn.

3. Agent dodaje instrumentację

   Wstawia celowane instrukcje logowania które wysyłają dane do lokalnego serwera debugowania działającego w rozszerzeniu Cursor.

4. Odtwarzasz błąd

   Agent mówi ci dokładnie jakie kroki wykonać. Podążaj za nimi precyzyjnie.

5. Agent analizuje logi

   Po odtworzeniu, przegląda zebrane dane i identyfikuje główną przyczynę.

6. Agent wprowadza celowaną poprawkę

   Zamiast zgadywać, naprawia dokładną linię powodującą problem, na podstawie dowodów runtime.

7. Weryfikuj i czyść

   Odtwórz ponownie aby potwierdzić poprawkę. Agent usuwa całą instrumentację.

Prompt do skopiowania dla sesji trybu debugowania

The payment webhook handler is intermittently returning 500 errors.
It happens roughly 1 in 10 times. The logs show "TypeError: Cannot read
property 'id' of undefined" but the request body always contains the expected fields.
I suspect a race condition or timing issue.

Add instrumentation to trace the exact execution path and help me
reproduce the failure.

Wzorzec czyszczenia pre-PR

Przed wysłaniem PR, przeprowadź agenta przez kompleksowe przejście czyszczące. To wyłapuje problemy które prześlizgnęły się przez rozmowy o pojedynczych zadaniach.

Prompt do skopiowania dla czyszczenia pre-PR

Run our full pre-PR check: npm run build && npm run lint && npm test

If anything fails, fix it and rerun until everything passes.
Then review all the changes on this branch compared to main and
flag any potential issues: missing error handling, unused imports,
hardcoded values, or deviations from our project conventions.

Ten pojedynczy prompt, z włączonym auto-run, obsługuje:

1. Błędy kompilacji TypeScript
2. Naruszenia lint
3. Awarie testów
4. Końcowe przejście przeglądu kodu

Agent iteruje nad każdą awarią aż build jest czysty. Przegląd na końcu wyłapuje semantyczne problemy które lintery pomijają.

Częste wzorce błędów i poprawki

Wzorzec 1: Agent zapętla się na tym samym błędzie

Agent wprowadza zmianę, test nie przechodzi, cofa, próbuje innego podejścia, znowu nie przechodzi i zaczyna się powtarzać.

Poprawka: Naciśnij Escape aby go zatrzymać. Zacznij nową rozmowę z bardziej konkretnym kontekstem:

@src/auth/session.ts The test "should redirect after login" is failing
because the session middleware expects req.session to be populated,
but the test mock does not set it up. Fix the mock, not the production code.

Kluczowa wskazówka: gdy agent się zapętla, stracił orientację w problemie. Świeża rozmowa z konkretną diagnozą przerywa pętlę.

Wzorzec 2: Kod kompiluje się ale zachowanie jest błędne

Wszystko przechodzi w terminalu ale funkcja nie działa w przeglądarce lub przy ręcznym testowaniu.

Poprawka: Użyj trybu debugowania aby dodać instrumentację, lub poproś agenta aby dodał logowanie:

Prompt do skopiowania dla rozbieżności przeglądarka kontra testy

The form submission works in tests but fails in the browser.
Add console.log statements at each step of the form submission handler
in @src/handlers/form-submit.ts so I can see where it diverges
from expected behavior. I'll paste the console output back to you.

Uruchom aplikację, odtwórz problem, skopiuj output konsoli z powrotem do czatu. Agent ma teraz dowody runtime zamiast statycznej analizy.

Wzorzec 3: Agent zmienia za dużo plików

Poprosiłeś o małą zmianę a agent przepisał połowę bazy kodu.

Poprawka: Przywróć checkpoint natychmiast. Następnie bądź bardziej konkretny:

Only modify src/services/billing.ts. Do not change any other files.
Add a retry mechanism to the processPayment function. Use the
existing retry utility in src/utils/retry.ts.

Ograniczenia jak “modyfikuj tylko” i “nie zmieniaj” to instrukcje które agent respektuje. Im szerszy twój prompt, tym więcej plików uważa za uprawnione cele.

Wzorzec 4: Niestabilne testy po zmianach AI

Testy które przechodziły teraz sporadycznie nie przechodzą.

Poprawka: To często wskazuje że agent wprowadził zależności czasowe lub współdzielony stan:

Prompt do skopiowania dla izolacji niestabilnych testów

@src/services/billing.test.ts These tests are now flaky -- they pass
individually but fail when run together. Check for shared state between
tests (database connections, module-level variables, un-cleared mocks)
and add proper isolation.

Wzorzec 5: Błędy importu po refaktoryzacji

Agent przeniósł kod między plikami i niektóre importy są błędne.

Poprawka: Pozwól agentowi użyć kompilatora TypeScript aby znaleźć i naprawić wszystkie błędy importu:

Run tsc and fix all import errors. Do not change any logic,
only fix the import paths and missing exports.

Decyzja “zacząć od nowa”

Czasami najlepsza strategia debugowania to wyrzucić zepsute zmiany i spróbować ponownie z lepszym promptem. To nie jest porażka — to celowa strategia.

Zacznij od nowa gdy:

• Agent wykonał więcej niż 3 nieudane próby tej samej poprawki
• Zmiany są tak splątane że zrozumienie ich zajmuje dłużej niż ich powtórzenie
• Zdajesz sobie sprawę że oryginalny prompt był błędny lub niekompletny

Nie zaczynaj od nowa gdy:

• Problem to mały, izolowany błąd w poza tym dobrym kodzie
• Większość zmian jest poprawna i tylko jeden element jest błędny
• Agent zainwestował znaczną pracę którą byłoby drogo odtworzyć

Aby czysto zacząć od nowa:

1. Przywróć najwcześniejszy checkpoint (lub git stash)
2. Zacznij nową rozmowę
3. Napisz bardziej konkretny prompt z wyraźnymi ograniczeniami
4. Odnieś się do pliku planu jeśli go masz

Uwaga

Oprzyj się chęci ciągłego poprawiania agenta w długiej rozmowie. Po 3-4 próbach poprawek, kontekst rozmowy jest zanieczyszczony nieudanymi podejściami. Świeży start z lepszym początkowym promptem prawie zawsze produkuje lepszy wynik szybciej.

Zapobieganie błędom zanim się pojawią

Najlepsze debugowanie to debugowanie którego nigdy nie musisz robić. Te praktyki dramatycznie redukują częstość błędów generowanych przez AI:

1. Pisz zasady projektu dla każdej konwencji — jeśli agent wciąż popełnia ten sam błąd, dodaj zasadę
2. Użyj trybu Plan najpierw — planowanie wyłapuje błędy architektoniczne zanim kod zostanie napisany
3. Odwołuj się do istniejących wzorców — odniesienia @ do istniejących plików dają agentowi konkretne przykłady do naśladowania
4. Trzymaj rozmowy krótkie — długie rozmowy prowadzą do degradacji kontekstu i zdezorientowanego outputu
5. Commituj często — małe commity oznaczają małe rollbacki
6. Uruchamiaj testy ciągle — z włączonym auto-run, agent wyłapuje własne błędy natychmiast

Gdy sam Cursor ma problemy

Czasami problem jest z Cursorem a nie wygenerowanym kodem:

AI nie odpowiada: Sprawdź status subskrypcji i połączenie internetowe. Przełącz modele jeśli jedno API nie działa.

Wysokie użycie CPU: Może działać indeksowanie. Sprawdź Ustawienia następnie Indeksowanie i dokumentacja. Jeśli się utrzymuje, otwórz Process Explorer (paleta poleceń następnie “Developer: Open Process Explorer”) aby znaleźć winowajcę, a potem przetestuj z minimalnym zestawem rozszerzeń wyłączonym przez Ustawienia następnie Rozszerzenia.

Błędy serwera MCP: Sprawdź panel Output (View następnie Output, wybierz serwer MCP). Zrestartuj Cursor jeśli serwer utknął.

Utracone zmiany po crashu: Sprawdź git stash, historię checkpointów Cursor oraz lokalną historię / pliki backupowe Cursor w katalogu app-support (macOS: ~/Library/Application Support/Cursor/, Linux: ~/.config/Cursor/, Windows: %APPDATA%\Cursor\).

Co dalej

Ukończyłeś szybki start Cursor. Stąd:

Wzorce produktywności

Głębokie zanurzenie w skróty klawiszowe, szablony promptów i przepływy pracy oszczędzające czas dla codziennego rozwoju.

Zaawansowane techniki

Eksploruj głębokie zanurzenia w trybie agenta, niestandardowe serwery MCP i strategie dużych baz kodu dla złożonych projektów.

Współdzielone przepływy pracy

Ucz się przepływów pracy między narzędziami które działają w Cursor, Claude Code i Codex.

Wskazówki i sztuczki

Przeglądaj kolekcję wskazówek dla sprawdzonych bojowo wzorców od doświadczonych użytkowników Cursor.