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

   Formularz logowania wysyła się pomyślnie (odpowiedź 200) ale użytkownik nie jest
   przekierowywany do dashboardu. Cookie sesji wygląda na poprawnie ustawione.
   To zaczęło się dziać po refaktoryzacji auth wczoraj.

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

Handler webhooka płatności sporadycznie zwraca błędy 500.
Zdarza się to mniej więcej 1 na 10 razy. Logi pokazują "TypeError: Cannot read
property 'id' of undefined" ale ciało żądania zawsze zawiera oczekiwane pola.
Podejrzewam race condition lub problem z czasem.

Dodaj instrumentację aby prześledzić dokładną ścieżkę wykonania i pomóż mi
odtworzyć awarię.

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

Uruchom nasze pełne sprawdzenie pre-PR: npm run build && npm run lint && npm test

Jeśli cokolwiek nie przejdzie, napraw to i uruchom ponownie aż wszystko przejdzie.
Następnie przejrzyj wszystkie zmiany na tej gałęzi w porównaniu do main i
oznacz wszelkie potencjalne problemy: brakującą obsługę błędów, nieużywane importy,
zakodowane wartości lub odchylenia od naszych konwencji projektu.

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 Test "should redirect after login" nie przechodzi
ponieważ middleware sesji oczekuje że req.session będzie wypełnione,
ale mock testu tego nie ustawia. Napraw mocka, nie kod produkcyjny.

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:

Wysyłanie formularza działa w testach ale nie działa w przeglądarce.
Dodaj instrukcje console.log na każdym kroku handlera wysyłania formularza
w @src/handlers/form-submit.ts żebym mógł zobaczyć gdzie odchodzi
od oczekiwanego zachowania. Wkleję output konsoli z powrotem do ciebie.

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:

Modyfikuj tylko src/services/billing.ts. Nie zmieniaj żadnych innych plików.
Dodaj mechanizm prób ponownych do funkcji processPayment. Użyj
istniejącego narzędzia prób ponownych w 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:

@src/services/billing.test.ts Te testy są teraz niestabilne -- przechodzą
indywidualnie ale nie przechodzą gdy uruchamiane razem. Sprawdź współdzielony stan między
testami (połączenia bazodanowe, zmienne na poziomie modułu, niewyczyszczone mocki)
i dodaj odpowiednią izolację.

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:

Uruchom tsc i napraw wszystkie błędy importu. Nie zmieniaj żadnej logiki,
tylko napraw ścieżki importu i brakujące eksporty.

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, spróbuj wyłączyć rozszerzenia z cursor --disable-extensions.

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 i pliki backupowe w ~/.config/Cursor/Backups/.

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.