Systematyczne debugowanie na różnych powierzchniach

Jest 3 w nocy i twój pager się odzywa. Serwis płatności zwraca błędy 500. Log błędów pokazuje stack trace wskazujący na zależność, którą zaktualizowałeś wczoraj. Musisz zdiagnozować problem, zidentyfikować przyczynę źródłową i wdrożyć poprawkę — zanim klienci się obudzą. To właśnie tutaj wielopowierzchniowa architektura Codex zamienia stresujący incydent w metodyczną sesję debugowania.

Czego się nauczysz

• Ustrukturyzowany przepływ pracy debugowania działający na wszystkich powierzchniach Codex
• Techniki debugowania specyficzne dla powierzchni: aplikacja do wizualnego przeglądu diff-ów, CLI do skryptowalnej diagnostyki, chmura do izolowanej reprodukcji, IDE do edycji w czasie rzeczywistym
• Gotowe do skopiowania prompty dla najczęstszych scenariuszy debugowania
• Strategie debugowania wyścigów, sporadycznych awarii i bugów występujących tylko na produkcji

Framework debugowania

1. Odtwórz: Potwierdź, że bug istnieje i zidentyfikuj minimalne kroki reprodukcji.
2. Izoluj: Zawęź, który komponent, moduł lub zmiana wprowadziła buga.
3. Zdiagnozuj: Znajdź przyczynę źródłową w kodzie.
4. Napraw: Zaimplementuj minimalną zmianę, która rozwiązuje problem.
5. Zweryfikuj: Uruchom zestaw testów, dodaj test regresji i potwierdź poprawkę.

Debugowanie specyficzne dla powierzchni

CLI

Najlepsze do: Szybkiej diagnostyki, skryptowalnego debugowania i awarii CI.

# Diagnose a test failure
codex exec --full-auto \
  "Run npm test, capture the output, identify why the payments test
   is failing, find the root cause in the source code, and fix it.
   Run the test again to verify."

# Analyze a production error
codex "Here is a production stack trace from our payments service:
[paste stack trace]
Find the root cause in the codebase. The service was working until
we upgraded stripe-node from 14.x to 15.x yesterday."

Aplikacja

Najlepsze do: Wizualnego przeglądu diff-ów, równoległych wątków dochodzeniowych i izolacji worktree.

Otwórz wątek Worktree, aby debugowanie nie wpływało na twoją bieżącą pracę:

1. Wybierz tryb “Worktree”, opierając go na branchu produkcyjnym
2. Wrzuć zrzut ekranu lub wklej komunikat błędu do kompozytora
3. Pozwól Codex badać problem, podczas gdy kontynuujesz inną pracę
4. Przejrzyj diff w wizualnym panelu diff-ów aplikacji
5. Zsynchronizuj poprawkę do lokalnego checkout, gdy będziesz zadowolony

Chmura

Najlepsze do: Odtwarzania problemów specyficznych dla środowiska, ciężkiej analizy i diagnostyki best-of-N.

# Submit a cloud debugging task
codex cloud exec --env production-mirror \
  "The /api/payments endpoint returns 500 with the error
   'TypeError: Cannot read property of undefined'. Reproduce
   the issue, find the root cause, implement a fix, and add
   a regression test."

Prompt: Diagnozowanie wyścigu

“I have an intermittent test failure in tests/services/order.test.ts. The test ‘should process concurrent orders’ fails about 30% of the time with ‘Expected 2 but received 1’. This suggests a race condition. Analyze the OrderService in src/services/order.ts, identify the race condition, implement a fix using proper synchronization, and run the test 50 times to verify the fix is stable.”

Typowe scenariusze debugowania

Awaria CI po aktualizacji zależności

Our CI started failing after upgrading typescript from 5.3 to 5.5.
The errors are in src/types/. Read the TypeScript 5.5 migration guide
and fix the type errors. Do not downgrade TypeScript. Run the type
checker after each change.

Błąd produkcyjny ze stack trace

Here is a production error from Sentry:
[paste full error with stack trace]

Find the exact code path that leads to this error. The error started
appearing after commit abc1234. Use git diff abc1234~1..abc1234 to
identify what changed. Implement a fix and add a regression test.

Badanie wycieku pamięci

Our Node.js service's heap grows by 50MB/hour under load. The leak
was introduced sometime in the last 2 weeks. Analyze recent commits
to src/services/ for common leak patterns: event listeners not removed,
closures capturing large objects, growing arrays or maps without eviction.
Identify the likely cause and propose a fix.

Prompt: Bisection regresji

“The ‘user search’ feature stopped returning results after a recent change. Use git log to find commits from the last 5 days that touched src/services/search.ts or src/routes/search.ts. For each suspect commit, analyze whether it could cause the regression. Identify the breaking commit and fix the issue.”

Debugowanie oparte na obrazach

Aplikacja Codex i CLI obsługują wejście obrazów. Dla bugów UI wrzuć zrzut ekranu do kompozytora:

# CLI with screenshot
codex -i screenshot-broken-layout.png \
  "This screenshot shows a broken layout in the dashboard header.
   The navigation items should be horizontally aligned but they
   are stacking vertically. Find the CSS issue and fix it."

W aplikacji przytrzymaj Shift podczas upuszczania obrazu, aby dodać go jako kontekst.

Kiedy to nie działa

• Agent nie może odtworzyć buga: Bug może zależeć od stanu środowiska (baza danych, cache, zewnętrzna usługa). Podaj jak najwięcej kontekstu: komunikaty błędów, stack trace, ostatnie zmiany i szczegóły środowiska.
• Poprawka działa, ale wprowadza regresję: Agent skupił się zbyt wąsko. Poproś go o uruchomienie pełnego zestawu testów, nie tylko testu, który zawodził.
• Sporadyczny bug znika podczas debugowania: Dodaj jawne logowanie lub asercje. Poproś Codex o dodanie tymczasowej instrumentacji debugowej, która przechwytuje stan w momencie wystąpienia błędu.
• Agent obwinia zły commit: Podaj dokładny przedział czasowy, kiedy bug się pojawił i git log. Poproś agenta o analizę każdego podejrzanego commita indywidualnie.

Co dalej

• Strategie przeglądu — Przeglądaj poprawki debugowania z odpowiednią rygorem
• Wzorce kontekstu — Utrzymuj kontekst debugowania w formie podczas długich sesji dochodzeniowych
• Inżynieria promptów — Pisz lepsze prompty do debugowania