Debugowanie i polowanie na błędy z Codexem

Debugowanie z Codexem działa, gdy każdy błąd przechodzi pętlę: reprodukcja, izolacja, diagnoza, poprawka, weryfikacja. Przed jakąkolwiek poprawką Codex pisze nieprzechodzący test, który staje się dowodem, że poprawka działa. Powierzchnię dobiera się do błędu: CLI do pętli lokalnej, worktree do izolowanej poprawki, Codex cloud do błędów zależnych od środowiska, wzmiankę @codex do czerwonego pull requesta.

Ta strona jest dla programistów, którzy codziennie pracują z Codexem, i dla tech leadów, którzy chcą, żeby poprawki błędów w zespole przychodziły z dowodami, a nie z diffem do czytania linijka po linijce. Sytuacja: użytkownicy zgłaszają, że zapis ustawień profilu pokazuje komunikat o sukcesie, ale po odświeżeniu strony zmiany nie ma. API zwraca 200, w logach czysto, a w bazie leżą stare dane. Chcesz znaleźć przyczynę, naprawić ją i udowodnić naprawę jeszcze tego popołudnia, bez przeglądania każdej linijki, której dotknął Codex.

Co daje debugowanie z Codexem zaczynające się od reprodukcji

Pięciokrokową pętlę, która działa na każdej powierzchni Codexa, z zasadą, że żadna poprawka nie powstaje, zanim nie istnieje test, który nie przechodzi
Tabelę decyzyjną: kiedy CLI, kiedy codex exec, worktree, Codex cloud, a kiedy wzmianka @codex
Siedem promptów do skopiowania: reprodukcja, diagnoza, poprawka, bisekcja regresji, błędy produkcyjne, niestabilne testy i wycieki pamięci
Tabelę dowodów, która mówi, czy poprawka jest dobra, bez czytania całego diffu
Sposoby wyjścia z sytuacji, w których sesja debugowania z Codexem utyka

Pętla debugowania: reprodukcja, izolacja, diagnoza, poprawka, weryfikacja

Kolejność ma większe znaczenie niż sformułowanie promptu. Większość złych poprawek od agenta bierze się z pominięcia kroku 1: bez reprodukcji Codex naprawia błąd, który sobie wyobraził, dokłada defensywne sprawdzenie na null i melduje sukces.

Reprodukcja. Codex zamienia zgłoszenie w test albo skrypt, który na obecnym kodzie nie przechodzi z tego samego powodu, który zobaczył użytkownik. Ten test jest kryterium akceptacji dla wszystkiego, co dalej.
Izolacja. Zawęź awarię do jednego modułu, jednego wejścia albo jednego commita. Przy regresjach git bisect run z nieprzechodzącym testem robi to mechanicznie.
Diagnoza. Codex podaje przyczynę źródłową z dowodami: plik i linię, błędną wartość i powód. Uszeregowane hipotezy są lepsze niż jedno pewne siebie zgadywanie.
Poprawka. Najmniejsza zmiana, po której reprodukcja przechodzi, zrobiona w osobnym worktree, żeby nie wymieszała się z twoją inną pracą.
Weryfikacja. Reprodukcja przechodzi, cały zestaw testów przechodzi, sprawdzanie typów i lint przechodzą, a reprodukcja znowu nie przechodzi, gdy cofniesz poprawkę. Ten ostatni krok dowodzi, że test rzeczywiście sprawdza błąd.

Rozdziel diagnozę i poprawkę na osobne prompty. Gdy jeden prompt mówi „znajdź i napraw”, Codex zwykle zatrzymuje się na pierwszej wiarygodnej przyczynie. Gdy diagnoza musi najpierw obronić się sama, możesz odrzucić błędną teorię, zanim zamieni się w kod.

Którą powierzchnię Codexa wybrać do którego błędu?

Codex uruchamia tego samego agenta na kilku powierzchniach, które dzielą konfigurację w ~/.codex/. Wybieraj według tego, gdzie błąd się odtwarza i ile twojej uwagi potrzebuje.

Błąd	Powierzchnia	Jak zacząć
Odtwarza się na twojej maszynie, wymaga wymiany zdań	CLI, tryb interaktywny	`codex` w katalogu głównym repozytorium
Masz już wyjście z błędem i chcesz diagnozy bez edycji	CLI, tryb bezobsługowy	`npm test 2>&1 \| codex exec -c default_permissions=":read-only" "..."`
Poprawka nie może ruszyć twoich niezacommitowanych zmian	CLI, w worktree	`codex --worktree` albo `/worktree` w trwającej sesji
Błąd UI, który łatwiej pokazać niż opisać	CLI ze zrzutem ekranu	`codex -i broken-header.png "..."`
Odtwarza się tylko w konkretnym środowisku albo jest na tyle niestabilny, że wymaga kilku prób	Codex cloud	`codex cloud exec --env ENV_ID --attempts 3 "..."`
Przebieg CI na pull requeście jest czerwony	GitHub	Komentarz `@codex` z instrukcjami na pull requeście
Błąd produkcyjny śledzony w Sentry	CLI z serwerem MCP Sentry	`codex mcp add sentry --url https://mcp.sentry.dev/mcp`

codex exec czyta przekierowane stdin: gdy podasz i prompt, i wyjście przez potok, Codex CLI 0.157.1 dołącza to wyjście jako blok <stdin>. Nadpisanie -c default_permissions=":read-only" wybiera wbudowany profil uprawnień, który w Codex CLI 0.157.1 jest funkcją w wersji beta. ENV_ID to identyfikator środowiska Codex cloud; jak je utworzyć, opisuje strona środowiska Codex cloud. Pracę w aplikacji desktopowej zamiast w CLI opisuje przewodnik po aplikacji desktopowej Codexa.

Odtwórz błąd, zanim Codex zmieni jakikolwiek kod

Podaj Codexowi kroki, oczekiwany wynik i faktyczny wynik, a potem zabroń poprawiania. Prompt reprodukcji, który pozwala na poprawkę, dostanie poprawkę. Uruchom sesję interaktywną poleceniem codex w katalogu głównym repozytorium i wklej:

Bug report: on /settings/profile, changing the display name and clicking Save shows the "Saved" toast, but after a page refresh the old name is back. PUT /api/users/:id/profile returns 200 and the server logs show no errors.

Your job in this step is ONLY to reproduce it:
1. Find the handler for PUT /api/users/:id/profile and the test file that covers it.
2. Write one failing test that performs the PUT, then a GET, and asserts the new display name is returned.
3. Run only that test and show me the failure output.
4. Confirm the failure matches the report (the value is stale), not a setup error such as a missing fixture or a connection failure.

Do not modify any source file outside the test directory. Do not propose a fix yet. If you cannot make the test fail, stop and tell me what you tried and what state you think is missing.

Zanim pójdziesz dalej, sprawdź w wyniku jedną rzecz: komunikat błędu. Test, który pada na ECONNREFUSED albo fixture not found, odtwarza twoje środowisko, a nie błąd. Odeślij go z dopiskiem „test pada z niewłaściwego powodu; napraw konfigurację testu, nie kod”.

Gdy błędu nie da się uruchomić lokalnie, odtwórz go z dowodów: dokładny komunikat, stack trace, żądanie, które go wywołało, i commit, od którego się zaczął. Tę ścieżkę opisuje sekcja o utykających sesjach.

Zdiagnozuj przyczynę źródłową na dowodach

Diagnoza ma być tylko do odczytu. Możesz to napisać w prompcie, ale wymusza to profil uprawnień. Jeśli masz już wyjście z błędem, przekaż je potokiem:

npx vitest run tests/api/profile.test.ts 2>&1 | codex exec -c default_permissions=":read-only" \
  "Diagnose the failing test in the attached output: name the root cause with file and line, show the evidence, and do not edit files."

W sesji interaktywnej kontynuuj po reprodukcji tak:

The failing test you wrote reproduces the bug. Now diagnose it without editing any file.

1. Trace the request from the route handler to the database call. Name every function on the path with file and line.
2. List up to three hypotheses for why the update is lost (for example: an update query that matches zero rows, a transaction that is never committed, a cache that serves the old value, a serializer that drops the field). Rank them.
3. For each hypothesis, run one command or add one temporary log line that confirms or rules it out, and show the result. Remove any temporary logging afterwards.
4. End with the confirmed root cause in two sentences, the exact line responsible, and the smallest change that would fix it.

If no hypothesis is confirmed, say so. Do not guess.

Dobra odpowiedź wskazuje linię i pokazuje dowód, na przykład: „update w Drizzle w src/routes/profile.ts:48 wywołuje .set() bez .where() na ID użytkownika, więc nie pasuje do żadnego wiersza, a handler zwraca rekord sprzed aktualizacji”. Słaba odpowiedź mówi „prawdopodobnie problem z cache” bez polecenia, które to potwierdziło. Zanim przyjmiesz teorię, poproś o dowód.

Przy błędach UI dołącz zrzut ekranu. -i (--image) działa i z codex, i z codex exec:

codex -i broken-header.png "The dashboard header in this screenshot should show the navigation items in one row; they stack vertically below 1280px. Find the CSS rule responsible and explain it before changing anything."

Wyizoluj regresję przez git bisect

Gdy funkcja działała tydzień temu, a teraz nie działa, przestań czytać commity ręcznie. Nieprzechodzący test reprodukcji zamienia git bisect w mechaniczne przeszukiwanie, które Codex może poprowadzić sam.

User search stopped returning results sometime in the last five days. The test tests/search/search.test.ts "returns matches for a partial name" fails on HEAD.

1. Find the most recent commit from before the last five days where that test passes. Show the test output at that commit.
2. Run git bisect between that commit (good) and HEAD (bad), using `npx vitest run tests/search/search.test.ts -t "returns matches for a partial name"` as the `git bisect run` command.
3. Report the first bad commit: hash, author date, message, and the part of its diff that explains the failure.
4. Run git bisect reset, then confirm you are back on the original branch with a clean working tree.

Do not fix anything in this step.

Jeśli test nie istniał w starszych commitach, niech Codex skopiuje go do pliku tymczasowego poza repozytorium i wskaże git bisect run mały skrypt, który go uruchamia. Inaczej bisekcja oznaczy jako „bad” każdy commit sprzed powstania testu.

Pobierz błędy produkcyjne przez serwer MCP Sentry

Przy błędach, które pojawiają się tylko na produkcji, stack trace wklejony do promptu gubi breadcrumbs, tagi i trace wokół niego. Oficjalny serwer MCP Sentry daje Codexowi zgłoszenie, jego zdarzenia i trace. Dodaj go raz w terminalu:

codex mcp add sentry --url https://mcp.sentry.dev/mcp
codex mcp login sentry

Serwer używa OAuth. Dla Sentry hostowanego u siebie użyj zamiast tego pakietu stdio @sentry/mcp-server. Jak Codex przechowuje serwery MCP, opisuje konfiguracja MCP w Codexie. Repozytorium getsentry/sentry-mcp miało 26 września 2026 roku 862 gwiazdki na GitHubie.

Use the Sentry MCP server. Find the most frequent unresolved error in the project "payments-api" over the last 24 hours. Show me its stack trace, the release it first appeared in, and one representative event's request data with personal data redacted.

Map the top application frames to files in this repository. Then write a test that reproduces the error with inputs shaped like that event, run it, and show that it fails with the same exception type and message. Do not fix the code yet.

Ostatnie zdanie trzyma pętlę w ryzach. Zdarzenie z Sentry to dowód do kroku 1, a nie przyzwolenie na łatanie ramki na szczycie stosu.

Napraw błąd w worktree i udowodnij poprawkę

Poprawiaj w izolacji, żeby zmiana przyszła jako osobna gałąź. codex --worktree uruchamia sesję w nowym zarządzanym worktree Gita; w sesji, która już trwa, to samo robi /worktree. Worktree zawiera tylko zacommitowany kod, więc najpierw zacommituj test reprodukcji.

Fix the confirmed root cause: the profile update in src/routes/profile.ts has no WHERE clause on the user ID, so it updates zero rows and the handler returns the old record.

Rules:
- Make the smallest change that makes the reproduction test in tests/api/profile.test.ts pass.
- Add a guard: if the update affects zero rows, return 404 instead of 200.
- Do not change the API response shape. Do not modify, skip or loosen any existing test.
- Add one more test for the 404 path.

Then prove it, and paste the output of each step:
1. The reproduction test and the new 404 test pass.
2. The full suite passes: npm test (all of it, not only the new tests).
3. Type check and lint pass: npm run typecheck and npm run lint.
4. Revert only your change to src/routes/profile.ts, run the reproduction test, and show that it fails again. Then restore the fix.

Finish with a three-line summary: root cause, fix, evidence.

Krok 4 recenzenci pomijają najczęściej, a to on jest najważniejszy. Test regresji, który przechodzi także bez poprawki, nie sprawdza błędu. Możesz to zweryfikować bez czytania testu: wynik musi pokazać najpierw czerwień, potem zieleń.

Uruchom tę samą poprawkę bezobsługowo

Gdy diagnoza jest pewna i chcesz poprawki bez sesji, uruchom ją przez codex exec. --worktree izoluje zmianę, :workspace pozwala Codexowi pisać w worktree, a -o zapisuje końcowe podsumowanie do opisu pull requesta:

codex exec --worktree -c default_permissions=":workspace" \
  -o fix-summary.md \
  "$(cat prompts/fix-profile-persistence.md)"

Plik prompts/fix-profile-persistence.md zawiera powyższy prompt poprawki. Zanim otworzysz pull request, zrób lokalny przegląd zmiany poleceniem codex review --base main. Formaty wyjścia codex exec i użycie w CI opisuje strona Codex w trybie nieinteraktywnym.

Debuguj niestabilne testy, wycieki pamięci i skutki aktualizacji

Niektórych klas błędów nie pokona pojedyncze uruchomienie testu. Każda wymaga innego rodzaju dowodu.

Niestabilne testy i wyścigi. Jeden zielony przebieg niczego nie dowodzi. Poproś o liczbę powtórzeń:

The test "processes concurrent orders" in tests/services/order.test.ts fails intermittently with "Expected 2 but received 1".

1. Run it 50 times in a loop and report the failure count as a baseline.
2. Read OrderService in src/services/order.ts and identify shared state that two concurrent calls can read and write. Explain the interleaving that produces 1 instead of 2.
3. Fix it with a real synchronization mechanism (a transaction with the right isolation level, a row lock or an atomic update). Do not add sleeps, retries or longer timeouts to the test.
4. Run the test 50 times again and report the new failure count. Anything above zero means the fix is not done.

Jeśli błąd znika za każdym razem, gdy Codex dodaje logowanie, zmieniły się zależności czasowe. Zamiast linii logu poproś o licznik albo asercję w podejrzanym miejscu przeplotu i trzymaj je tylko na czas śledztwa.

Wycieki pamięci. Podaj Codexowi tempo przyrostu i okno czasowe, a zamiast listy podejrzanych poproś o ścieżkę retencji:

Our Node.js service's heap grows by about 50 MB per hour under steady load. It started within the last two weeks.

1. List the commits from the last two weeks that touch src/services/ or src/lib/.
2. In those diffs, look for event listeners that are never removed, timers or subscriptions that are never cleared, module-level maps or arrays with no eviction, and closures that capture request objects.
3. Pick the most likely candidate and explain the retention path from a GC root to the leaked objects.
4. Write a test that creates and tears down the component 1,000 times and asserts that the listener count, the map size or the heap usage stays bounded. Show that it fails before your fix and passes after.

Awarie po aktualizacji zależności. Podaj zmianę wersji i zablokuj drogę na skróty: „CI pada po aktualizacji TypeScriptu z 5.3 do 5.5. Przeczytaj informacje o wydaniach pomiędzy tymi wersjami, popraw błędy typów w src/types/, nie cofaj wersji TypeScriptu i nie dodawaj @ts-ignore. Po każdym pliku uruchom sprawdzanie typów”. Jeśli Codex potrzebuje informacji o wydaniach z sieci, uruchom sesję z flagą --search, która włącza wyszukiwanie w sieci na żywo.

Błędy zależne od środowiska. Gdy awaria pojawia się tylko w konkretnej wersji środowiska uruchomieniowego albo na konkretnych danych, uruchom reprodukcję w Codex cloud, gdzie kontener definiuje konfiguracja środowiska. --attempts zamawia kilka niezależnych prób (best-of-N), co pomaga, gdy pierwsza teoria często okazuje się błędna:

codex cloud exec --env ENV_ID --attempts 3 \
  "The expired-subscriptions cron job skips records on Node 20. Reproduce it with tests/fixtures/expired-subscriptions.json, write a failing test, find the root cause, fix it, and report the test output before and after."
codex cloud status TASK_ID      # sprawdzaj, aż zadanie się zakończy
codex cloud diff TASK_ID        # obejrzyj wynik
codex cloud apply TASK_ID       # nałóż go na swoje drzewo robocze

codex cloud jest w Codex CLI 0.157.1 oznaczone jako [EXPERIMENTAL]. TASK_ID wypisuje codex cloud exec.

Czerwone CI na pull requeście. Wspomnij @codex na pull requeście z tymi samymi zasadami: przeczytaj log nieudanego joba, odtwórz błąd, popraw testowany kod i nie luzuj testów ani konfiguracji CI. Pełny komentarz do skopiowania i wymaganą konfigurację repozytorium opisuje strona Połączenie Codexa z GitHubem.

Dodaj skill do debugowania, żeby metoda przetrwała każdą sesję

Prompty rozjeżdżają się między ludźmi. Skill sprawia, że dyscyplina „najpierw reprodukcja, potem diagnoza” staje się domyślna. Skill systematic-debugging z obra/superpowers przechodzi cztery fazy: badanie przyczyny źródłowej, analizę wzorców, testowanie hipotez i implementację. Instalujesz go dla Codexa przez CLI skills (wersja 1.7.0 sprawdzona 26 września 2026 roku):

npx skills add obra/superpowers --skill systematic-debugging -a codex

W migawce listy skills.sh z 26 września 2026 roku (LinklyAI/best-skills, źródło wtórne) miał około 272 tysięcy instalacji. Zanim na nim polegasz, przeczytaj zainstalowany SKILL.md. Otwarte zgłoszenie #2277 (10 września 2026) opisuje, że katalog skilla zawiera fixture’y testowe, które trafiają do folderu skilli agenta. Inne skille do testowania i debugowania opisuje strona skille do testowania i debugowania.

Jeśli nie chcesz dodawać skilla, wpisz pętlę do AGENTS.md: „Przy każdym błędzie napisz nieprzechodzący test i pokaż jego wynik, zanim zmienisz pliki źródłowe”. Codex wczytuje AGENTS.md na początku każdej sesji w zaufanym projekcie.

Skąd wiesz, że poprawka od Codexa jest dobra, bez czytania każdej linijki?

Poprawka to twierdzenie. Te sprawdzenia zamieniają je w dowód, który potwierdzisz w kilka minut, niezależnie od tego, kto napisał kod.

Dowód	Czego dowodzi	Kto sprawdza
Wynik testu reprodukcji: czerwony przed poprawką, zielony po	Test oddaje zgłoszone zachowanie, a poprawka je zmienia	Programista, który odpowiada za błąd, na podstawie wklejonego wyniku
Test reprodukcji znowu nie przechodzi po cofnięciu poprawki	Test nie przechodzi przypadkiem	Ta sama osoba, na podstawie kroku 4 promptu poprawki
Pełny zestaw testów, sprawdzanie typów i lint w CI na pull requeście	Nic innego się nie zepsuło	Ochrona gałęzi; człowiek nie jest potrzebny
Liczba udanych przebiegów na 50 lub więcej, przy niestabilnych błędach	Wyścig zniknął, a nie się ukrył	Programista, na podstawie wyniku pętli
Uwagi z `codex review --base main` albo `@codex review`	Drugie przejście szukało skutków ubocznych w diffie	Programista triażuje; uwagi z numerem linii są obsługiwane
Diff ograniczony do plików wskazanych w diagnozie	Poprawka nie wyszła poza zakres	Recenzent, na podstawie listy plików, nie całego diffu

Decyzja człowieka jest wąska: czy test reprodukcji odpowiada zgłoszeniu użytkownika? Jeśli tak, a każdy wiersz powyżej jest zielony, zatwierdzasz na podstawie dowodów. Jeśli diff dotyka plików, których diagnoza nie wymieniała, odeślij go i zapytaj dlaczego, zanim zaczniesz czytać. O przeglądzie takich zmian piszemy w strategiach przeglądu zmian od Codexa.

Gdy sesja debugowania z Codexem utyka: jak z tego wyjść

Codex nie potrafi odtworzyć błędu. Błąd zależy od stanu, którego brakuje w twoim środowisku deweloperskim: konkretnych danych, odpowiedzi usługi zewnętrznej, ruchu produkcyjnego. Daj Codexowi dokładny komunikat, stack trace, wywołujące żądanie i pierwsze złe wydanie, a potem poproś o test, który buduje ten stan z fixture’ów albo mocka usługi zewnętrznej. Jeśli stan jest środowiskowy, przenieś reprodukcję do Codex cloud, do środowiska, którego konfiguracja go zasiewa.

Poprawka leczy objaw. Codex owija padającą linię sprawdzeniem na null albo try/catch i test przechodzi. Zapytaj: „Dlaczego w tym miejscu wartość jest null? Prześledź ją do miejsca, w którym jest ustawiana”. Odrzucaj poprawki, które dokładają kod defensywny bez diagnozy wyjaśniającej złą wartość.

Codex zmienia test zamiast kodu. Asercja zostaje poluzowana, przypadek dostaje .skip albo timeout rośnie dwukrotnie. W każdym prompcie poprawki napisz, że testów nie wolno zmieniać, pomijać ani luzować, i sprawdź listę plików: poprawka, której diff dotyka tylko plików testowych, nie jest poprawką.

Poprawka psuje inne testy. Codex uruchomił tylko nowy test. Podaj polecenie pełnego zestawu wprost (npm test, a nie „uruchom testy”) i wymagaj jego wyniku w podsumowaniu.

Codex obwinia niewłaściwy commit. Czytanie git log zachęca do wiarygodnie brzmiących historii. Zastąp historię poleceniem git bisect run z nieprzechodzącym testem, jak w prompcie do bisekcji.

Niestabilny błąd znika w trakcie debugowania. Logowanie zmieniło zależności czasowe. Używaj liczników albo asercji, uruchamiaj test w pętli 50 razy lub więcej i porównuj liczbę porażek, a nie pojedyncze przebiegi.

Sesja gubi wątek. Po długim śledztwie Codex powtarza hipotezy, które już wykluczył. Poproś o podsumowanie: co potwierdzone, co wykluczone, i zacznij nową sesję od tego podsumowania. codex fork --last (uruchomione w nowym terminalu) tworzy odgałęzienie ostatniej sesji, więc zachowujesz jej historię i sprawdzasz inną teorię. Jak utrzymać ostry kontekst, opisują wzorce kontekstu w Codexie.

Poprawka z chmury działa w kontenerze, a lokalnie nie. Środowisko w chmurze i twoja maszyna mają różne wersje. Przypnij w konfiguracji środowiska wersje środowiska uruchomieniowego i zależności zgodne z CI i traktuj CI jako rozstrzygające.

Wzmianka @codex zostaje bez odpowiedzi. Repozytorium nie jest połączone z Codexem albo nie ma środowiska w chmurze. Sprawdź konfigurację na stronie Połączenie Codexa z GitHubem. Jeśli problem dotyczy samego Codexa (logowanie, sandbox, zatwierdzenia), zajrzyj do przywracania Codexa po błędach.

Dokąd dalej z debugowaniem w Codexie

Generowanie i uruchamianie testów z Codexem Zamień każdy test reprodukcji w trwałe pokrycie i zestaw testów, któremu ufasz.

Środowiska Codex cloud Zbuduj środowisko, w którym uruchamiasz reprodukcje zależne od środowiska.

Wzorce debugowania dla każdego agenta Przepisy niezależne od narzędzia: stack trace, logi i niestabilne testy.

Reagowanie na incydenty z AI Gdy błąd jest trwającym incydentem: triaż, mitygacja i pętla po incydencie.

Ten sam workflow w innych narzędziach: debugowanie z Claude Code i polowanie na błędy w Cursor.