Debugowanie z Codex na wielu powierzchniach

Pager dyżurowy dzwoni o 14:00. Użytkownicy zgłaszają, że zapisywanie ustawień profilu “działa” — widzą toast sukcesu — ale zmiany nie utrzymują się po odświeżeniu strony. Logi pokazują odpowiedzi 200. Baza danych pokazuje stare dane. Gdzieś między optymistyczną aktualizacją frontendu a commitem backendu coś cicho zawodzi. Musisz to znaleźć, naprawić i zweryfikować poprawkę, nie psując niczego innego. Codex daje ci wiele powierzchni, aby zaatakować to jednocześnie.

Czego się nauczysz

• Przepływ debugowania oparty na reprodukcji, który działa na wszystkich powierzchniach Codex
• Prompty do debugowania w CLI z szybkimi pętlami zwrotnymi, debugowania w aplikacji z trwałym kontekstem i delegowania na GitHub dla awarii CI
• Techniki używania zadań w chmurze do reprodukowania błędów specyficznych dla środowiska
• Wzorzec @codex na GitHub do delegowania poprawek błędów bezpośrednio z issues i PR

Przepływ pracy

Wybierz swoją powierzchnię debugowania

Różne błędy wymagają różnych powierzchni:

CLI (szybka pętla)

Najlepsze, gdy możesz odtworzyć błąd lokalnie i chcesz szybki cykl badanie-naprawa-weryfikacja. CLI pozwala przekierować wyjście błędów bezpośrednio do Codex, uruchamiać polecenia inline i szybko iterować.

codex

Aplikacja (głęboka analiza)

Najlepsza dla złożonych błędów wymagających dłuższego badania w wielu plikach. Aplikacja utrzymuje historię konwersacji, pozwala uruchamiać równoległe wątki badawcze w worktree i ma panel recenzji do inspekcji zmian.

GitHub (@codex)

Najlepsze dla awarii CI i błędów zgłoszonych w issues. Skomentuj @codex fix the CI failures na PR, a Codex utworzy zadanie w chmurze, które zbada i zaproponuje poprawkę. Nie jest wymagana lokalna konfiguracja.

Chmura (błędy środowiskowe)

Najlepsza dla błędów, które reprodukują się tylko w konkretnych środowiskach — inny system operacyjny, inna wersja Node, brakujące zależności. Zadania w chmurze uruchamiają się w kontrolowanym kontenerze, gdzie możesz skonfigurować dokładne środowisko.

Krok 1: Najpierw reprodukuj

Najważniejszy krok debugowania to uzyskanie niezawodnej reprodukcji. Podaj Codex jawne kroki reprodukcji, a nie tylko opis błędu.

Wskazówka

Prompt do skopiowania — reprodukcja błędu (CLI):

Bug: Clicking "Save" on the profile settings page shows "Saved" toast but changes do not persist after page refresh.

Repro:
1) Start the app: npm run dev
2) Go to /settings/profile
3) Change the display name field
4) Click Save
5) Refresh the page -- the display name reverts to the old value

Constraints:
- Do not change the API shape
- Keep the fix minimal
- Add a regression test

Start by reproducing the bug locally, then investigate the root cause before proposing any fix.

W CLI Codex uruchomi serwer deweloperski, spróbuje reprodukcji, odczyta odpowiednie pliki źródłowe i wyśledzi problem. Szybka pętla zwrotna — polecenie, wyjście, rozumowanie, następne polecenie — to obszar, w którym CLI błyszczy przy debugowaniu.

Krok 2: Badaj z kontekstem

Gdy masz reprodukcję, faza badania korzysta z trwałego kontekstu aplikacji Codex. Otwórz projekt w aplikacji, utwórz wątek Local i opisz, co dotychczas znalazłeś:

Wskazówka

Prompt do skopiowania — analiza przyczyny źródłowej (aplikacja):

I've confirmed a bug where profile settings appear to save (200 response, success toast) but the database is not updated.

What I know so far:
- PUT /api/users/:id/profile returns 200
- The request body contains the correct updated data
- The response body shows the old data
- No errors in the server logs

Read the profile update handler and trace the exact database query being executed. Check if there is a transaction that is not being committed, a cache layer returning stale data, or a serialization issue between the request body and the ORM update call.

Aplikacja zachowuje pełną konwersację, więc możesz zadawać pytania uzupełniające bez ponownego wyjaśniania kontekstu. Jeśli Codex zidentyfikuje problem w handlerze, możesz zostawić komentarz inline przy konkretnej linii w panelu recenzji, a następnie poprosić go o naprawienie tylko tej części.

Krok 3: Napraw w worktree

Nigdy nie naprawiaj błędów bezpośrednio w katalogu roboczym, jeśli masz inne niezacommitowane zmiany. Przełącz się na tryb Worktree i opierz go na gałęzi z błędem:

Fix the profile settings persistence bug. The root cause is that the Drizzle update call in src/routes/profile.ts uses .set() but does not call .where() with the user ID, so it matches zero rows and returns silently.

Fix the query, add a check that the update affected exactly one row (throw 404 if zero), and write a regression test that:
1. Creates a user
2. Updates their profile via PUT
3. Reads the profile via GET
4. Asserts the updated values are returned

Run the full test suite after the fix.

Krok 4: Deleguj awarie CI z GitHub

Gdy pipeline CI zawodzi na pull requeście, nie musisz checkout’ować gałęzi lokalnie. Skomentuj bezpośrednio na PR:

@codex fix the CI failures

Codex tworzy zadanie w chmurze, czyta diff PR i logi CI, identyfikuje awarię i proponuje poprawkę. Wyniki publikuje z powrotem na PR jako komentarz z linkiem do zadania. Jeśli poprawka wymaga zmian w kodzie, możesz otworzyć PR z zadania w chmurze.

Dla bardziej ukierunkowanego badania bądź konkretny:

@codex The integration tests for the payment webhook handler are failing with "connection refused" on the Redis mock. Investigate and fix.

Krok 5: Debuguj problemy specyficzne dla środowiska w chmurze

Niektóre błędy reprodukują się tylko w konkretnych środowiskach. Zadania w chmurze uruchamiają się w kontenerze codex-universal, gdzie możesz przypiąć wersje Node.js, zainstalować zależności systemowe i skonfigurować zmienne środowiskowe.

Z CLI:

codex cloud exec --env production-mirror "The cron job that processes expired subscriptions is silently skipping records when run with Node 20. Reproduce the issue using the test data in tests/fixtures/expired-subscriptions.json, identify the root cause, and propose a fix."

Użyj --attempts 3 dla podejścia best-of-N, gdy błąd jest przerywany:

codex cloud exec --env production-mirror --attempts 3 "Reproduce the race condition in the WebSocket reconnection handler. It happens approximately 1 in 5 times when the server restarts during an active connection."

Kiedy to nie działa

Codex nie może odtworzyć błędu. Jeśli reprodukcja wymaga stanu, który nie istnieje w środowisku deweloperskim (konkretne dane użytkownika, odpowiedzi API zewnętrznych, wzorce ruchu produkcyjnego), błąd nie odtworzy się lokalnie. Zamiast kroków reprodukcji podaj Codex dokładne komunikaty błędów, stack trace’y i odpowiednie linie logów. Użyj środowisk chmurowych z zasianymi danymi testowymi dla bliższej produkcji reprodukcji.

Poprawka psuje inne testy. Dlatego zawsze umieszczasz “Run the full test suite after the fix” w swoim prompcie. Jeśli Codex uruchomi tylko test, który napisał, a nie istniejący zestaw, odkryjesz regresje po scaleniu. Bądź wyraźny: “Run npm test (the full suite), not just the new test.”

@codex na GitHub nie odpowiada. Codex musi być włączony dla przeglądu kodu i zadań w chmurze w twoim repozytorium. Sprawdź ustawienia Codex na chatgpt.com/codex/settings. Upewnij się również, że komentarz używa @codex (małe litery) — wielkość liter ma znaczenie.

Zadanie w chmurze produkuje poprawkę, która działa w kontenerze, ale nie lokalnie. Różnice środowiskowe między uniwersalnym kontenerem a twoją lokalną maszyną mogą to powodować. Przypiąć wersje w ustawieniach środowiska chmurowego, aby pasowały do twojej lokalnej konfiguracji, lub dodaj konkretne wersje do skryptu konfiguracyjnego.

Co dalej

Generowanie i wykonywanie testów Zamień swoje poprawki błędów w kompleksowe zestawy testów zapobiegające regresjom

CI/CD z Codex GitHub Action Automatyzuj wykrywanie błędów i propozycje poprawek w pipeline CI