Przepisy obsługi błędów

Przepisy obsługi błędów to gotowe do wklejenia prompty dla Claude Code, Codeksa i Cursora na cztery zadania wokół awarii produkcyjnej: debugowanie, logowanie, odzyskiwanie i monitorowanie. Każdy przepis trzyma się jednej zasady: agent dołącza dowód, że sprawdzenie padało przed zmianą i przechodzi po niej, więc zatwierdzasz dowód, a nie czytasz każdej linii.

Ta strona jest dla programistów, którzy oddają błędy produkcyjne agentowi, i dla tech leadów, którzy zatwierdzają te poprawki. Znasz tę sytuację: API zwraca 500, w logach jest Error: undefined, a pierwsza poprawka agenta owija wywołanie w try/catch. Błąd znika z dashboardu, ale nie z ekranów twoich użytkowników.

Który przepis obsługi błędów pasuje do twojego problemu?

Zacznij od objawu. Ostatnia kolumna to dowód, który agent dołącza do pull requesta.

Twój problem	Przepis	Sprawdzenie, które to dowodzi
Błąd, który widzisz, ale nie umiesz wyjaśnić: stack trace, sporadyczna awaria, wyciek, wyścig	Wzorce debugowania	Reprodukcja, która pada na niepoprawionym kodzie i przechodzi po poprawce
Logi to napisy z console.log, bez identyfikatorów żądań, albo wyciekają w nich sekrety	Wzorce logowania	Test, który sprawdza pola strukturalne i to, że sekret nigdy nie trafia do wyjścia
Niestabilna zależność, która pociąga za sobą twoją usługę	Wzorce odzyskiwania	Test chaosu lub wstrzykiwania błędów, który wyłącza zależność i sprawdza ścieżkę awaryjną
Użytkownicy znajdują błędy przed tobą: brak alertów, zbyt głośne alerty, brak SLO	Wzorce monitorowania i logowania	promtool test rules i zapytanie, które zwraca prawdziwe dane

Zaczynasz od zera? Najpierw popraw logi, bo każdy inny przepis potrzebuje dowodów, które agent potrafi odczytać. Potem debuguj istniejące awarie, dodaj odzyskiwanie tam, gdzie zależność ciągle zawodzi, a na końcu alerty, żeby następna awaria dotarła do ciebie, zanim zauważy ją klient.

Proces wokół poprawki (alarmowanie, triaż, postmortem) opisuje strona reagowanie na incydenty z AI. Zasadę, która zamienia każdy błąd produkcyjny w test regresyjny, znajdziesz w error-driven development.

Daj agentowi reguły obsługi błędów przed każdym przepisem

Bez reguł agent optymalizuje pod cichy log: połyka wyjątki, dodaje optional chaining i zwraca wartości domyślne dla danych, które muszą istnieć. Zapisz reguły raz, tam, gdzie każde narzędzie wczytuje je automatycznie.

## Error-handling rules
- Never swallow an error: no empty catch, no catch that only logs and continues,
  no default value for data that must exist. Rethrow, or return a typed error.
- Classify every new catch: "expected sometimes" (handle it, log at warn) or
  "should never happen" (fail loudly, log at error with context).
- Log with the project logger in structured form, with the request ID. Never log
  tokens, passwords, cookies, or full request bodies.
- Every bug fix starts with a test or script that reproduces the bug and fails.
  Never edit, skip, or loosen that test to make it pass.
- Retries only for idempotent calls, with a cap, backoff, and jitter.

Cursor

Zapisz ten blok jako regułę projektu w .cursor/rules/, ustawioną na stosowanie zawsze. Trzymaj ten sam tekst co w plikach pozostałych narzędzi, żeby zmiana reguł docierała do każdego agenta.

Claude Code

Dodaj ten blok do CLAUDE.md w katalogu głównym repozytorium. Claude Code wczytuje go w każdej sesji, także w trybie headless claude -p.

Codex

Dodaj ten blok do AGENTS.md w katalogu głównym repozytorium. Codex czyta AGENTS.md, zanim zacznie pracę; w projekcie, którego nie oznaczysz jako zaufany, pomija projektowy AGENTS.md (Codex 0.150.0+).

Najważniejsza jest reguła „nie osłabiaj testu”, a sama reguła to zaufanie, nie egzekwowanie. Ochrona wyroczni pokazuje, jak ustawić test reprodukujący jako tylko do odczytu dla agenta.

Prompt do wklejenia: audyt obsługi błędów w kodzie

Read-only pass: do not edit files. Find every place in src/ where an error can
disappear: empty catch blocks, catch blocks that only log, promise chains with no
rejection handler, optional chaining or default values on data that must exist,
and retries without a cap. For each, give file:line, which rule it breaks
("swallowed", "no context", "unbounded retry", "secret in log"), and the user-
visible effect if it fires in production. Output one table sorted by that effect,
then name the error handling recipe that fixes the top three.

Prompt do wklejenia: napraw błąd produkcyjny, zaczynając od padającego testu

Here is a production error with its stack trace and request ID: <paste>.
1. Explain the cause in two sentences and quote the log lines or code that prove it.
   If the evidence is not enough, say what you need and stop.
2. Write a test that reproduces the error and run it. Show me that it fails.
3. Fix the cause, not the symptom: no new catch that hides the error.
4. Rerun the test, the full suite, the type check, and lint. Paste the output.
Do not edit the test after step 2.

Jak zweryfikować obsługę błędów przez agenta bez czytania każdej linii?

Każdy przepis kończy się sprawdzeniem, które wykonuje maszyna, a pull request zawiera jego wynik.

• Najpierw czerwono, potem zielono. Reprodukcja pada na niepoprawionym kodzie i przechodzi po poprawce. Test, który nigdy nie padł, niczego nie dowodzi.
• Bramki działają w CI. Pełny zestaw testów, sprawdzanie typów i lint uruchamiają się na pull requeście, nie tylko w sesji agenta.
• Drugi agent porównuje diff z diagnozą. Uruchom /code-review w sesji Claude Code, codex exec review --uncommitted w terminalu albo Bugbota na pull requeście w Cursorze i każ mu szukać ukrytych błędów: nowych bloków catch, osłabionych asercji, wartości domyślnych dla wymaganych danych.
• Produkcja potwierdza poprawkę. Po wdrożeniu odsetek tego błędu zostaje na zerze przez co najmniej jeden szczyt ruchu. Sprawdza to programista, który wdrożył poprawkę.

Programista odpowiada za dowody, a tech lead zatwierdza, gdy wszystkie są na miejscu. Pełną tabelę dowodów znajdziesz w części jak udowodnić poprawkę błędu bez czytania każdej linii. Celowe wstrzykiwanie błędów poza jedną zależnością opisuje strona testowanie przez wstrzykiwanie błędów.

Co się psuje, gdy agenci obsługują błędy?

Typowe awarie obsługi błędów i jak z nich wyjść

• Poprawka ukrywa błąd. Nowy try/catch, optional chaining albo wartość domyślna sprawiają, że stack trace znika, a użytkownicy nadal widzą awarię. Wyjście: odrzuć diff i powtórz przegląd drugim agentem z pytaniem „czy to gdziekolwiek ukrywa błędy?” na pierwszym miejscu.
• Reprodukcja zmienia się na zieloną, bo agent ją edytował. Wyjście: zrób git diff samego pliku testu, cofnij zmianę i ustaw tę ścieżkę jako tylko do odczytu dla agenta.
• Ponawianie żądań (retry) zamienia wolną zależność w awarię. Ponawianie bez jittera i limitu mnoży obciążenie usługi, która już ledwo działa. Wyjście: zastosuj circuit breaker i ponawianie z jitterem z przepisu na odzyskiwanie i udowodnij je jego testem chaosu.
• Przez logi wycieka sekret. „Zaloguj żądanie, żebyśmy mogli to zdebugować” zapisuje tokeny i ciasteczka w magazynie logów. Wyjście: dodaj test maskowania sekretów z przepisu na logowanie i zrotuj każde poświadczenie, które trafiło do logów.
• Agent diagnozuje na podstawie parafrazy. Twoje streszczenie błędu gubi szczegół, który ma znaczenie. Wyjście: daj mu surowy stack trace albo podłącz serwer MCP do śledzenia błędów w trybie tylko do odczytu, jak pokazuje przepis na debugowanie.

Dokąd dalej z obsługą błędów

Wzorce debugowania Pięć wzorców debugowania, od stack trace'a po wyścig, każdy udowodniony sprawdzeniem, które najpierw padło.

Wzorce logowania Strukturalne, skorelowane i bezpieczne dla sekretów logi, które agent potrafi przeszukać.

Wzorce odzyskiwania Circuit breakery, ponawianie z jitterem i ścieżki awaryjne, udowodnione testem chaosu.

Wzorce monitorowania i logowania Reguły alertów, burn rate SLO i dashboardy, które agent pisze i testuje.

Serwery MCP do obserwowalności Daj agentowi prawdziwy błąd i trace zamiast swojego streszczenia.

Monitorowanie i obserwowalność Workflow etapu eksploatacji, do którego podłączają się te przepisy.