Debugowanie i odzyskiwanie po błędach

Odzyskiwanie po błędach w Cursorze to cofnięcie zmiany agenta, która zepsuła build albo zachowanie aplikacji, i powtórzenie pracy w ciaśniejszych ramach. Checkpointy cofają edycje plików w obrębie jednego czatu, commity gita chronią wszystko pomiędzy czatami, a naprawa jest zaakceptowana dopiero wtedy, gdy build, testy i zawężony diff mówią to samo, a nie wtedy, gdy agent twierdzi, że już działa.

Aktualność dokumentacji

Zakres: linia Cursor 3.x, sprawdzona 26 września 2026 r. Plan Mode zweryfikowano na cursor.com 28 sierpnia 2026 r. Stron Cursora o checkpointach i trybach uruchamiania (run modes) nie dało się ponownie sprawdzić 26 września 2026 r., dlatego każdy krok odzyskiwania poniżej działa też z samym gitem.

Ta strona jest dla programisty, który zbudował pierwszą funkcję z agentem Cursora i właśnie patrzy, jak coś się sypie. Agent zrefaktoryzował moduł uwierzytelniania, przeniósł funkcje między plikami i dodał warstwę walidacji. Testy przechodzą, ale strona logowania w przeglądarce jest pusta. Prosisz o poprawkę, agent edytuje sześć kolejnych plików i nagle padają dwa testy, które godzinę temu były zielone.

Co daje ci procedura odzyskiwania w Cursorze

• Dwie warstwy cofania (checkpointy i git), które przygotowujesz, zanim agent zacznie pracę
• Tabelę decyzji: kiedy przywrócić checkpoint, kiedy wrócić do commita, a kiedy poprawiać na bieżąco (fix forward)
• Cztery prompty do skopiowania: diagnoza w nowym czacie, zawężona poprawka, instrumentacja w czasie działania i bramka przed PR
• Polecenia gita, które mierzą, co agent zmienił, bez czytania całego diffa
• Sposoby wyjścia z sześciu sytuacji, w których samo odzyskiwanie idzie źle

Dlaczego błędy agenta wymagają innego odzyskiwania

Pomyłki agenta rzadko wyglądają jak literówki. Wyglądają jak skończona praca.

Typowy błąd człowieka	Typowy błąd agenta
Literówka albo błąd o jeden (off-by-one)	Kod, który się kompiluje i przechodzi sprawdzanie typów, ale robi coś innego, niż trzeba
Pominięty przypadek brzegowy	Pewne siebie, błędne założenie co do wymagania
Pomyłka przy kopiuj-wklej	Wzorzec z jednej części kodu zastosowany tam, gdzie nie pasuje
Jedna zepsuta funkcja	Zmiany rozsiane po wielu plikach, część z nich niezwiązana z zadaniem

Wynikają z tego dwie rzeczy, na których opiera się cała reszta. Po pierwsze, zielony build niewiele dowodzi, więc potrzebujesz dowodu z zachowania: testu, który odtwarza błąd, albo logów z działania aplikacji. Po drugie, relacja agenta o tym, co zmienił, nie jest wiarygodna, więc zmianę mierzysz gitem, a nie czytając czat.

Przygotuj dwie warstwy cofania, zanim agent zacznie

Cursor zapisuje w obrębie czatu checkpointy edycji plików wykonanych przez agenta, więc możesz wrócić do stanu sprzed danej odpowiedzi. Są lokalne dla Cursora i niezależne od gita. Git to warstwa, która przetrwa zamknięty czat, restart edytora i przejście na maszynę kolegi. Używaj obu.

1. Każde zadanie dla agenta zaczynaj od czystego drzewa roboczego na osobnej gałęzi. W terminalu:

   git status --short            # nie może niczego wypisać; najpierw commit albo stash
   git switch -c fix/login-blank-page

2. Commituj po każdym etapie, który agent kończy, a nie dopiero na końcu. Przy funkcji budowanej fazami to jeden commit po schemacie, jeden po API i jeden po UI:

   git add -A && git commit -m "wip: API endpoints pass their tests"

3. Przed ryzykownym promptem (refaktoryzacja, aktualizacja zależności, migracja) zrób kolejny commit. To commit, a nie checkpoint, jest twoim punktem powrotu, gdy edytor się zamknie albo czat przepadnie.

4. Wiedz, czego checkpoint nie cofnie. Wszystko, co agent zrobił przez terminal, leży poza migawką plików: migracja wykonana na lokalnej bazie, zainstalowany pakiet, plik wygenerowany skryptem. Traktuj to jako niechronione i cofaj ręcznie.

To, czy agent pyta cię przed każdym poleceniem w terminalu, zależy od trybu uruchamiania ustawionego w twoim workspace w ustawieniach bezpieczeństwa agenta Cursora. Pozwól uruchamiać bez pytania polecenia testów, lintu i buildu, zamiast znosić zatwierdzanie dla wszystkich poleceń. Konfigurację opisuje strona niezbędna konfiguracja.

Przywrócić checkpoint, wrócić do commita czy poprawiać na bieżąco?

Wybierz najmniejsze cofnięcie, które usuwa szkodę.

Sytuacja	Cofnij przez	Dlaczego
Ostatnia odpowiedź agenta pogorszyła sprawę, a wcześniejsze były w porządku	Przywróć checkpoint sprzed tej odpowiedzi	Usuwa jeden krok i zachowuje resztę pracy z sesji
Kilka odpowiedzi z rzędu poszło źle albo nie wiesz, która zepsuła kod	Żeby zachować kopię: git stash push -u -m "agent attempt" (to przy okazji czyści drzewo). Żeby odrzucić zmiany: git restore --staged --worktree . do ostatniego commita, potem git clean -nd, żeby zobaczyć pliki utworzone przez agenta, i git clean -fd, żeby je usunąć	Commit to znany dobry stan, a ciąg checkpointów może nim nie być
Czat przepadł, Cursor się zrestartował albo zmiana jest już zacommitowana	git reset --hard LAST_GOOD_COMMIT na twojej gałęzi, potem git clean -nd i git clean -fd dla plików utworzonych przez agenta. Jeśli już wypchnąłeś zmiany, uruchom zamiast tego git revert AGENT_COMMIT. LAST_GOOD_COMMIT i AGENT_COMMIT to hashe z git log --oneline	Na tym etapie historię ma tylko git
Jeden fragment jest zły, a reszta poprawna i przetestowana	Poprawianie na bieżąco zawężonym promptem (poniżej)	Powtarzanie dobrej pracy kosztuje więcej niż poprawienie jednej części
Sam prompt był błędny albo niepełny	Cofnij (i uruchom git clean -fd), potem otwórz nowy czat z lepszym promptem	Poprawianie na bieżąco dalej buduje na błędnym założeniu

Uwaga

git restore --staged --worktree . i git reset --hard odrzucają niezacommitowane zmiany bez pytania, ale żadne z nich nie usuwa nowych, nieśledzonych plików; robi to git clean -fd, a podgląd daje git clean -nd. Jeśli w git status jest cokolwiek, co może ci się jeszcze przydać, najpierw uruchom git stash push -u -m "before reset".

Jak zatrzymać agenta, który kręci się w kółko przy tym samym błędzie

Wzorzec wygląda tak: agent coś zmienia, test pada, agent próbuje innego podejścia, znowu pada, a potem zaczyna się powtarzać albo cofać własną wcześniejszą poprawkę. Kolejne prompty w tym samym czacie rzadko pomagają, bo kontekst zawiera już kilka nieudanych podejść, które ciągną następną próbę w ich stronę.

1. Zatrzymaj agenta w czacie, żeby przestał edytować pliki.

2. Przywróć checkpoint sprzed pętli albo uruchom git restore --staged --worktree ., żeby wrócić do ostatniego commita, potem git clean -nd, żeby zobaczyć pliki utworzone przez agenta, i git clean -fd, żeby je usunąć.

3. Znajdź przyczynę sam albo z agentem w Plan Mode, który planuje, zanim napisze jakikolwiek kod. Czytaj faktyczny wynik padającego testu, a nie streszczenie agenta.

4. Otwórz nowy czat i przekaż agentowi diagnozę, plik i to, czego nie wolno mu ruszać.

Prompt do skopiowania: diagnoza w nowym czacie po pętli

@src/auth/session.ts @tests/auth/session.test.ts

The test "redirects to /dashboard after login" fails with:
  TypeError: Cannot read properties of undefined (reading 'userId')
at src/auth/session.ts in getSessionUser.

Cause: the session middleware expects req.session to be populated,
but the test's request mock never sets it up. The production code is correct.

Fix the mock in tests/auth/session.test.ts so it creates req.session the way
src/middleware/session.ts does. Do not modify any file under src/.
Run `npx vitest run tests/auth/session.test.ts` and show me the output.
Stop after one attempt if it still fails and tell me what you observed.

Ostatnie zdanie ma znaczenie. Agent, któremu każesz zatrzymać się po jednej nieudanej próbie, wraca z raportem zamiast wchodzić w nową pętlę.

Jak ograniczyć agenta, który zmienił za dużo plików

Poprosiłeś o ponawianie jednego wywołania płatności, a agent przy okazji przeformatował moduł rozliczeń, zmienił nazwę funkcji pomocniczej i ruszył trzy testy. Najpierw to zmierz:

git diff --stat              # pliki i liczba linii zmienionych od ostatniego commita

Jeśli na liście są pliki, których zadanie nie wymagało, przywróć checkpoint i zawęź zakres w samym prompcie. Nazwij plik, wskaż funkcję pomocniczą do użycia i powiedz, co jest poza zakresem.

Prompt do skopiowania: zawężona poprawka w jednym pliku

Only modify src/services/billing.ts. Do not change any other file,
including tests, config, or formatting outside the function you edit.

Add retries to processPayment for network errors and HTTP 5xx responses only.
Use the existing withRetry helper in src/utils/retry.ts with 3 attempts and
exponential backoff. Do not retry 4xx responses.

When you are done, run `git diff --stat` and confirm that billing.ts is the only
file listed. Then run `npx vitest run src/services` and show me the result.

Jeśli agent w każdej sesji robi tę samą niechcianą zmianę, poprawka należy do reguły projektu, a nie do każdego promptu osobno.

Gdy testy przechodzą, a funkcja jest zepsuta

Czytanie kodu nie znajdzie tej klasy błędów. Agent potrzebuje dowodów z działania programu: co kod faktycznie zrobił, po kolei, na ścieżce, która zawodzi. Poproś o tymczasowe, oznaczone logowanie w każdym kroku, sam odtwórz błąd i wklej wynik z powrotem. Jeśli w wyborze trybu jest tryb przeznaczony do tej pętli z dowodami z działania, kroki są takie same.

Prompt do skopiowania: instrumentacja w czasie działania dla błędu widocznego tylko w przeglądarce

The login form works in tests but renders a blank page in the browser after
a successful POST /api/login (200, session cookie set).

Do not fix anything yet. Add temporary logging, each line prefixed with
[DEBUG-LOGIN], at these points:
- the submit handler in src/components/LoginForm.tsx (before and after the fetch)
- the redirect logic in src/auth/redirect.ts
- the first render of src/pages/dashboard.tsx

Tell me the exact steps to reproduce. I will paste the browser console
output back to you. After the fix, remove every [DEBUG-LOGIN] line.

Znacznik sprawia, że sprzątanie da się sprawdzić: przed commitem git grep -n --untracked "DEBUG-LOGIN" nie może niczego wypisać. Przy błędach sporadycznych, wyścigach i regresjach, które wymagają git bisect, przejdź pełny proces opisany w debugowaniu z pomocą AI w Cursorze.

Jak udowodnić naprawę bez czytania każdej linii

„Wszystkie testy przechodzą” w ustach agenta to deklaracja. Akceptuj naprawę na podstawie dowodów, które sprawdzisz w minutę, w tej kolejności.

1. Bramka jest zielona. Build, lint, sprawdzanie typów i testy kończą się w terminalu, a nie w podsumowaniu agenta.

2. Zakres jest taki, o jaki prosiłeś. git diff --stat main...HEAD pokazuje tylko pliki, których zadanie wymagało.

3. Testów nie osłabiono. git diff main...HEAD -- '*.test.*' '*.spec.*' nie pokazuje usuniętych asercji, nowych .skip ani poluzowanych oczekiwanych wartości. Agent naciskany, by test zrobił się zielony, czasem edytuje test zamiast kodu; zobacz chroń wyrocznię testową.

4. Kodu debugującego już nie ma. git grep -n --untracked "DEBUG-" niczego nie wypisuje.

5. Pierwotny objaw zniknął. Odtwórz błąd tak, jak zobaczyłeś go za pierwszym razem, a jeszcze lepiej zachowaj test, który go odtwarzał.

Żeby bramka działała automatycznie, uruchamiaj polecenie testów i grep na DEBUG- z hooka stop w Cursorze, który odsyła agenta do pracy, gdy któreś z nich zawiedzie; zobacz, jak kazać Cursorowi ponowić bramkę, zanim powie „gotowe”. Resztę agent może wykonać za ciebie jednym przebiegiem, zanim otworzysz pull request.

Prompt do skopiowania: bramka przed PR po naprawie

Run our full check: npm run build && npm run lint && npx tsc --noEmit && npm test

If anything fails, fix the code, not the tests, and rerun.
Stop after two failed attempts and report what you observed.
Stop and ask me if a fix would require changing a test's expected values.

Then compare this branch with main and report:
1. The output of `git diff --stat main...HEAD`, and any file you did not need to change
2. Any change under tests/ or in *.test.* / *.spec.* files, quoted in full
3. Any leftover debug logging, TODOs, hardcoded values, or unused imports
Do not open a pull request.

Jako autor bierzesz odpowiedzialność za pull request i wpisujesz pięć powyższych sprawdzeń do jego opisu. Potem CI uruchamia tę samą bramkę, a automatyczny recenzent, taki jak Bugbot, oraz kolega z zespołu przeglądają pull request. Podział tych sprawdzeń w zespole opisuje strona kontrola wersji i współpraca zespołowa w Cursorze.

Poprawiać na bieżąco czy zacząć od nowa?

Rozpoczęcie od nowa to świadomy wybór, a nie porażka. Traktuj poniższe jako ustawienia domyślne i dopasuj je do swojego kodu.

Zacznij od nowa, gdy	Poprawiaj na bieżąco, gdy
Agent trzy razy poległ na tej samej poprawce	Błąd jest mały i odizolowany, a reszta kodu jest dobra
Zrozumienie splątanych zmian zajęłoby dłużej niż ich powtórzenie	Większość zmiany jest poprawna i pokryta przechodzącymi testami
Orientujesz się, że pierwotny prompt był błędny albo niepełny	Pracę trudno byłoby odtworzyć, a zły jest jeden fragment
Czat jest długi i wciąż wraca do nieudanych podejść	Błąd ma jasną diagnozę, którą przekażesz w jednym prompcie

Jak zacząć od nowa czysto: wróć do ostatniego dobrego commita, usuń nowe pliki agenta przez git clean -fd (podgląd: git clean -nd), otwórz nowy czat, napisz prompt z jawnymi limitami plików i kryteriami akceptacji, a jeśli Plan Mode wygenerował plik planu, odwołaj się do niego. Ogólnie trzymaj rozmowy krótkie; dlaczego długie czaty tracą jakość, wyjaśnia zarządzanie kontekstem.

Gdy problemem jest Cursor, a nie kod

Czasem agent działa dobrze, a zawodzi edytor.

• Agent przestaje odpowiadać albo zwraca błąd przy każdym żądaniu. Sprawdź sieć i wykorzystanie limitu w swoim planie, potem wybierz inny model w selektorze modeli, żeby wykluczyć awarię jednego dostawcy. Zobacz wybór modelu.
• Serwer MCP nie działa albo znikają jego narzędzia. Otwórz logi tego serwera MCP (zobacz konfigurację MCP w Cursorze), popraw polecenie albo dane uwierzytelniające, które zgłaszają, potem zrestartuj serwer albo edytor.
• Wysokie użycie CPU zaraz po otwarciu dużego repozytorium. Zwykle to indeksowanie i uspokaja się po jego zakończeniu. Jeśli nie, wyklucz katalogi z wygenerowanymi plikami plikiem ignore; zobacz niezbędną konfigurację.
• Praca zniknęła po awarii. Najpierw sprawdź git stash list i git reflog. Zacommitowaną pracę da się odzyskać z refloga nawet po twardym resecie.

Co idzie źle przy odzyskiwaniu po błędach agenta?

Objaw	Przyczyna	Jak wyjść
Pliki przywrócone, a aplikacja wciąż pada tak samo	Agent uruchomił w terminalu migrację, instalację albo generator, a checkpoint tego nie obejmuje, albo utworzył nowe, nieśledzone pliki, które git restore --staged --worktree . zostawia	Cofnij efekt uboczny ręcznie (wycofaj migrację, przeinstaluj zależności z lockfile przez npm ci), wypisz nowe pliki przez git clean -nd i usuń je przez git clean -fd, potem ponownie uruchom bramkę
git reset --hard usunął pracę, której potrzebowałeś	Niezacommitowane zmiany nie trafiły do stasha	Zacommitowana praca: git reflog. Dodana do indeksu, ale niezacommitowana: czasem znajdzie ją git fsck --lost-found. Niezaindeksowane edycje: przywróć checkpoint, jeśli ten czat jest wciąż otwarty. Od teraz uruchamiaj git stash push -u przed każdym resetem
Test jest zielony, a błąd nadal jest	Agent poluzował test zamiast naprawić kod	Przywróć test z main przez git restore --source main -- TEST_FILE (TEST_FILE to ścieżka poluzowanego testu), potem ponów prompt z zawężoną poprawką z dopiskiem „do not modify tests”
Nowy czat znowu robi tę samą błędną zmianę	Błędne założenie siedzi w kodzie albo w nieaktualnej regule, a nie w starym czacie	Popraw albo dodaj regułę projektu, która opisuje konwencję, potem spróbuj ponownie
Po poprawce testy przechodzą osobno, a razem padają	Agent wprowadził współdzielony stan: zmienną na poziomie modułu, niewyczyszczony mock, ponownie używane połączenie z bazą	Poproś agenta, by znalazł stan współdzielony między testami i go odizolował; zobacz wzorce testowania w Cursorze
Logi debugujące trafiają do pull requesta	Instrumentacja nie była oznaczona, więc nic jej nie wychwyciło	Oznaczaj każdą tymczasową linię logu i włącz git grep -n --untracked "DEBUG-" do bramki przed PR

Co dalej po odzyskiwaniu po błędach w Cursorze

Kontrola wersji i współpraca zespołowa w Cursorze Następny krok szybkiego startu: opisy commitów, konflikty scalania i pull requesty ze sprawdzeniami gita, które dowodzą, że nic nie zginęło.

Debugowanie z pomocą AI w Cursorze Pełny proces dla błędów sporadycznych i wyścigów: zbadaj w trybie tylko do odczytu, odtwórz, napraw jedną przyczynę.

Checkpointy i gałęzie Warstwa cofania w szczegółach oraz gałęzie i worktree do eksperymentów z agentem.

Odzyskiwanie po błędach w Claude Code Ta sama procedura w agencie terminalowym, oparta na własnych checkpointach Claude Code.

Wersję tej strony dla Codeksa znajdziesz w artykule odzyskiwanie po błędach w Codeksie.