Przejdź do głównej zawartości

Czytanie dowodów zamiast kodu

Czytanie dowodów zamiast kodu oznacza zatwierdzanie zmiany agenta na podstawie czterech artefaktów, a nie diffa: zmiany specyfikacji, wyników akceptacji, siły wyroczni oraz sygnałów z działającego buildu. Wskazana osoba nadal czyta kod przy uwierzytelnianiu, pieniądzach, schematach i migracjach, zmianach samych testów oraz wszystkim, czego nie pokrywa żadne sprawdzenie.

Agenci otworzyli w nocy 14 pull requestów. Każdy jest zielony, każdy ma 300 linii, a o dziesiątej masz planowanie. Rzetelne przeczytanie wszystkich zajmie cały dzień. Przejrzenie ich po łebkach zajmie godzinę i niczego nie udowodni, bo przejrzany pobieżnie diff to akceptacja z gorszym śladem audytowym. Ta strona pokazuje, jak lepiej wykorzystać tę godzinę.

  • Kolejność czytania dowolnego pull requesta agenta: zmiana specyfikacji, wyniki akceptacji, siła wyroczni, sygnały z działania, z pytaniem, na które odpowiada każdy element.
  • Tabelę eskalacji z klasami zmian, w których ktoś wciąż czyta kod, uzasadnieniem dla każdej klasy i wzorcami ścieżek na start.
  • Trzy prompty do skopiowania, które każą agentowi przygotować dowody, zaudytować własną wyrocznię i sklasyfikować zmianę.
  • Osobisty dziennik zaufania, który przesuwa jedną klasę zmian naraz od „czytam wszystko” do „czytam dowody”.
  • Sygnały ostrzegawcze, że za wcześnie przestałeś czytać, i sposób wyjścia z każdej sytuacji.
  • Dla tech leadów, CTO i zarządu: trzy definicje metryk, które odróżniają review dowodów od braku review.

To obciążenie zostało zmierzone. Raport Acceleration Whiplash firmy Faros AI (kwiecień 2026; dwa lata telemetrii z 22 000 programistów i 4000 zespołów) pokazał wzrost mediany czasu w review o 441,5% i o 31,3% więcej pull requestów scalanych bez żadnego review. W tych samych danych liczba ukończonych epików na programistę wzrosła o 66,2%, a liczba incydentów na pull request o 242,7%. Generowanie się przeskalowało, czytanie nie.

Programiści sami przyznają, że nie weryfikują tego, czemu nie ufają. W ankiecie Sonar (styczeń 2026, ponad 1100 respondentów) 96% programistów nie ufa w pełni kodowi wygenerowanemu przez AI, a tylko 48% zawsze go weryfikuje przed commitem.

Wybór nie jest więc między czytaniem każdej linii a nieczytaniem niczego. Poziom 3 drabiny kończy się wtedy, gdy przepustowość review staje się sufitem. Drogą dalej jest zmiana tego, co czytasz: wyników sprawdzeń, które się wykonały, zamiast tekstu, który wygląda wiarygodnie.

Czytaj cztery artefakty, w tej kolejności. Każdy odpowiada na pytanie, na które diff odpowiada słabo, i każdy może zawieść w widoczny sposób.

#ArtefaktNa jakie pytanie odpowiadaSkąd pochodziJak wygląda, gdy zawodzi
1Zmiana specyfikacjiCzy agent zmienił zachowanie, o które prosiliśmy, i tylko je?Specyfikacja lub ticket plus krótka lista zmian zachowania prostym językiemZmiany, o które nikt nie prosił; „przy okazji zrefaktorowałem X”
2Wyniki akceptacjiCzy każde kryterium akceptacji ma sprawdzenie, które się wykonało i przeszło?Wyniki testów, e2e i ewaluacji, jedno kryterium do jednego sprawdzeniaKryterium bez sprawdzenia albo pominięte sprawdzenie
3Siła wyroczniCzy te sprawdzenia mogły nie przejść i czy agent ich dotykał?Diff testów, wyniki testów mutacyjnych na zmienionym kodzie i to, czy decydujące sprawdzenie istniało przed zmianąTesty edytowane w tym samym pull requeście, poluzowane asercje, wygenerowane od nowa snapshoty
4Sygnały z działaniaCzy działające oprogramowanie zachowuje się zgodnie ze specyfikacją?Uruchomienia na preview lub stagingu, zrzuty ekranu z przeglądarki, trace’y, a po wdrożeniu metryki canary i odsetek błędówBrak uruchomienia albo zrzut ekranu tylko ze ścieżki pozytywnej

Zmiana specyfikacji to najkrótszy artefakt i najbardziej wart twojego czasu. Mówi w zdaniach, które zachowanie się zmieniło: „GET /orders zwraca teraz 50 pozycji na stronę i next_cursor; stary parametr page zwraca 400”. Porównujesz to z tym, o co prosiłeś. Rozrost zakresu, źle zrozumiane wymaganie i cicha zmiana kontraktu wychodzą tu w kilka sekund i żadne z nich nie wymaga czytania kodu. Jeśli nikt nie zapisał, o co prosiliście, zapisz to najpierw; zobacz, jak pisać kryteria akceptacji, których agent nie odczyta źle.

Każde kryterium ze specyfikacji dostaje dokładnie jedną linię: kryterium, sprawdzenie, które je dowodzi, i wynik. „Stary parametr page zwraca 400 → orders.contract.test.ts:88 → pass”. Kryterium bez takiej linii jest niezweryfikowane, niezależnie od tego, jak zielony jest pipeline. Agent przygotuje to zestawienie tanio, bo zna zarówno kryteria, jak i testy, które sam napisał; właśnie dlatego liczy się następne sprawdzenie, czyli siła wyroczni.

Potem zapytaj, czy wyrocznia w ogóle mogła nie przejść

Dział zatytułowany „Potem zapytaj, czy wyrocznia w ogóle mogła nie przejść”

Wyrocznia to zestaw sprawdzeń, który decyduje, że praca jest „gotowa”. Agent mógł napisać zarówno funkcję, jak i jej testy, więc zielony wynik niewiele znaczy, dopóki nie znasz dwóch rzeczy. Po pierwsze: czy pull request zmienił jakikolwiek test, fixture, snapshot, krok CI albo regułę lintera? Jeśli tak, przeczytaj tę część diffa; tylko ona może sprawić, że wszystkie pozostałe sprawdzenia kłamią. Po drugie: czy testy by nie przeszły, gdyby kod był błędny? Testy mutacyjne odpowiadają na to mechanicznie: celowo psują zmieniony kod i liczą, ile mutantów testy wyłapały. Ogranicz je do zmienionych plików, bo przebieg na całym projekcie jest w CI wolny. Dla JavaScriptu i TypeScriptu (@stryker-mutator/core 10.0.0 w npm) przekaż zmienione pliki źródłowe do --mutate: npx stryker run --mutate "$(git diff --name-only --diff-filter=d main -- 'src/*.ts' ':!*.test.ts' | paste -sd, -)", a gdy lista jest pusta, pomiń ten krok. Dla Pythona (mutmut 3.8.0 w PyPI) mutmut run nie przyjmuje ścieżek, więc przed uruchomieniem wypisz zmienione pliki w only_mutate w sekcji [tool.mutmut] w pyproject.toml (albo [mutmut] w setup.cfg); source_paths zostaje katalogiem pakietu (zastąpiło paths_to_mutate w mutmut 3.6.0). Pełna metoda jest na stronie o tym, jak silna jest twoja wyrocznia, a odcięcie od niej agenta opisuje ochrona wyroczni.

Stripe pokazuje, dlaczego liczy się wyrocznia starsza niż agent. Jego agenci Minions tworzą tygodniowo „ponad 1300 pull requestów” w Stripe, które są „sprawdzane przez ludzi, ale nie zawierają kodu napisanego przez człowieka” (blog inżynierski Stripe, 19 lutego 2026). Działają na istniejącym zestawie „ponad trzech milionów” testów, z limitem „najwyżej dwóch rund CI” (część 1 tej samej serii, 9 lutego 2026). Wyrocznia jest starsza niż agent i właśnie dlatego review może być krótkie.

Testy dowodzą tego, co ktoś pomyślał, żeby przetestować. Działający build pokazuje, co zmiana naprawdę robi. Przed merge’em oznacza to uruchomienie na preview lub stagingu ze zrzutem ekranu albo trace’em każdej ścieżki akceptacji. Skill agent-browser pozwala agentowi samodzielnie obsłużyć działającą aplikację i zebrać te dowody. Po merge’u oznacza to metryki canary, odsetek błędów i automatyczny rollback. Progressive delivery to siatka bezpieczeństwa, dzięki której czytanie przed merge’em staje się opcjonalne w klasach niskiego ryzyka.

Cztery artefakty razem tworzą pakiet dowodów, czyli kontrakt pull requesta egzekwowany przez CI. Ta strona opisuje stronę czytającego; strona o pakiecie zawiera szablon i sprawdzenie w CI, które odrzuca niekompletny pakiet.

Które zmiany wciąż wymagają, żeby człowiek przeczytał kod?

Dział zatytułowany „Które zmiany wciąż wymagają, żeby człowiek przeczytał kod?”

Dowody działają, gdy wyrocznia jest silna, informacja zwrotna szybka, a błąd tani do cofnięcia. Poniższe klasy nie spełniają przynajmniej jednego z tych warunków, więc wskazana osoba czyta kod za każdym razem, oprócz dowodów. Trzymaj tę listę krótką; lista, która obejmuje pół repozytorium, cofa cię na poziom 3.

Klasa zmianyDlaczego dowody nie wystarcząWzorce ścieżek na start (dopasuj do repozytorium)
Uwierzytelnianie i autoryzacjaTesty dowodzą dozwolonych ścieżek; błąd kryje się w ścieżce, której nikt nie przetestował. Szkodą jest wyciek, nie bug.**/auth/**, **/middleware/**, **/*permission*, **/*policy*
PieniądzeZaokrąglenia, waluty, idempotencja i przypadki brzegowe zwrotów wychodzą po tygodniach, na kontach klientów.**/billing/**, **/payments/**, **/pricing/**, handlery webhooków
SchematyKontrakt, od którego zależą inne usługi i starsze wersje klientów; awaria ujawnia się poza testami tego repozytorium.**/schema.*, **/*.sql, **/openapi*, **/*.proto
Migracje danychCzęsto nieodwracalne, uruchamiane raz na danych produkcyjnych, do których fixture’y testowe nie są podobne.**/migrations/**
Sama wyroczniaZmiana testów, CI, lintera albo konfiguracji typów zmienia znaczenie „zielonego” dla każdej innej zmiany.**/*.test.*, **/__snapshots__/**, .github/workflows/**, pliki lintera i tsconfig
Wszystko, czego nie pokrywa żadne sprawdzenieBez wyroczni jedynym dowodem jest kod.Rozstrzygane per pull request: linia akceptacji bez sprawdzenia

Pierwsze cztery klasy pokrywają się z tymi, które zadanie człowieka utrzymuje pod nadzorem w każdej pętli. Dwie ostatnie to warunki, nie katalogi: obowiązują wszędzie, gdzie wystąpią. Skieruj wszystkie sześć przez CODEOWNERS, żeby wymaganego czytającego pilnowała platforma, a nie czyjaś pamięć. Polityka autonomii i klas ryzyka to miejsce, w którym organizacja spisuje tę listę raz.

Prompty z następnej sekcji działają we wszystkich trzech narzędziach. Różni się to, gdzie powstają dowody i kto może zablokować merge.

Uruchom prompt dowodowy w trybie headless w CI albo z terminala. Sesje -p startują w trybie uprawnień Manual, więc każde polecenie Bash spoza listy dozwolonych narzędzi zostaje odrzucone. Prompt każe agentowi uruchomić testy akceptacyjne, więc lista musi zawierać twoje polecenia testowe. Poniżej git diff, git log i narzędzia testowe to jedyne polecenia powłoki, które przebieg może wykonać; zastąp je poleceniami z własnego repozytorium:

Okno terminala
# Terminal albo CI, z katalogu głównego repozytorium (Claude Code 2.1.283)
claude -p "$(cat .github/prompts/evidence.md)" \
--allowedTools "Read,Grep,Glob,Bash(git diff:*),Bash(git log:*),Bash(npm test:*),Bash(npx vitest:*),Bash(npx stryker run:*)" \
--output-format json > evidence.json

Przebieg uruchamia polecenia testowe z pull requesta, mając w środowisku twój klucz API. W CI uruchamiaj go na zdarzeniu pull_request z gałęzi tego repozytorium, nigdy na pull_request_target z checkoutem kodu kontrybutora.

Jeśli chcesz drugiej opinii o samym kodzie, /code-review przegląda lokalny diff w sesji, a claude ultrareview uruchamia z powłoki wieloagentowe review w chmurze. Zarządzany check Code Review (research preview, plany Team i Enterprise) „zawsze kończy się neutralnym wynikiem, więc nigdy nie blokuje merge’a”: traktuj go jak komentarze recenzenta, nie jak bramkę.

Dowody z działania zbiera się tak samo we wszystkich trzech narzędziach. CLI agent-browser instalujesz raz i jest wspólne; skill, który uczy agenta z niego korzystać, instaluje się osobno dla każdego agenta, więc wymień każdego, którego używasz. Flagi -a i -y sprawiają, że skills add nie zadaje pytań:

Okno terminala
# Terminal. agent-browser 0.38.1 w npm, sprawdzone 2026-09-26
npm install -g agent-browser && agent-browser install
npx skills add vercel-labs/agent-browser -a claude-code -a codex -a cursor -y

Prompty do skopiowania dla review opartego na dowodach

Dział zatytułowany „Prompty do skopiowania dla review opartego na dowodach”

Prompty zostają po angielsku, tak jak wklejasz je do agenta.

Zaufanie do dowodów zdobywa się per klasa zmian, nie per narzędzie ani per agent. Dziennik zaufania to krótki plik, w którym dla każdej klasy zapisujesz, co przeczytałeś i czy czytanie kodu znalazło coś, czego nie pokazały dowody. Trzymaj go w notatkach albo w repozytorium w docs/, jeśli zespół korzysta z niego wspólnie.

# Dziennik zaufania: Anna, orders-service
| Data | PR | Klasa | Etap | Dowody | Czytanie kodu znalazło | Uciekło na prod? |
| ---------- | ---- | ----------------- | ----------- | ------------ | ------------------------------- | ---------------- |
| 2026-09-22 | #412 | paginacja API | read-all | pass | nic ponad dowody | nie |
| 2026-09-23 | #418 | paginacja API | read-all | pass | nieproszona zmiana nazwy pola | nie |
| 2026-09-24 | #421 | teksty w UI | sampled | pass | nie czytano (poza próbką) | nie |
| 2026-09-25 | #425 | webhook billingu | always-read | pass | brak sprawdzenia idempotencji | nie |
  1. Każdą klasę zaczynaj od read-all. Czytasz najpierw dowody, potem kod, i zapisujesz, czy kod pokazał ci coś, czego nie pokazały dowody.

  2. Awansuj klasę do sampled po czystej serii. Nasza reguła na start to 20 kolejnych pull requestów, w których czytanie kodu nie znalazło niczego istotnego, a zmiana specyfikacji wyłapała to, co było istotne. Ta liczba to polityka zespołu, nie wynik badań; obniż ją dla trywialnych klas, podnieś dla wszystkiego, co widzi użytkownik. W etapie sampled czytasz kod jednego pull requesta na pięć, wybranego, zanim zajrzysz do dowodów.

  3. Awansuj do evidence-only po drugiej czystej serii: po kolejnych 20 pull requestach na etapie sampled, w których czytanie próbek nie znalazło niczego istotnego, a żaden błąd z tej klasy nie trafił na produkcję. Czytasz cztery artefakty i zatwierdzasz.

  4. Cofnij klasę o jeden etap przy pierwszym potknięciu. Błąd, który trafił na produkcję, albo czytanie kodu, które znalazło realny problem pominięty przez dowody, cofa klasę o jeden etap. Najpierw załataj lukę w dowodach (brakujące sprawdzenie akceptacyjne, słaby test), potem zapracuj na etap od nowa.

  5. Nigdy nie awansuj klas eskalacji. Uwierzytelnianie, pieniądze, schematy, migracje i zmiany wyroczni zostają na always-read. Poprawiają się tam dowody czytane obok kodu, a nie to, czy czytasz kod.

Dziennik jest też twoją odpowiedzią, gdy ktoś zapyta, dlaczego zatwierdziłeś zmianę bez czytania. „Ta klasa ma w moim dzienniku 40 czystych pull requestów i żadnej ucieczki” to stwierdzenie, za które można odpowiadać. „Wyglądało dobrze” nim nie jest. Jak wdrożyć ten sam protokół w całym zespole, opisuje strona jak pomóc zespołowi przestać czytać każdy diff.

Problem opisany w danych Faros to nie „krótsze review”. To o 31,3% więcej pull requestów scalanych bez żadnego review. Rozwiązaniem nie jest żądanie większej ilości czytania, bo te same dane pokazują, że czytanie się nie skaluje. Rozwiązaniem jest sprawienie, by lżejsze review było prawdziwym review, i mierzenie, że takie jest. Trzy definicje do przyjęcia bez zmian:

MetrykaDefinicjaCo oznacza zły trend
Kompletność dowodówOdsetek scalonych pull requestów agentów, które mają wszystkie cztery artefakty (zmianę specyfikacji, przypisanie kryteriów akceptacji, opis zmian wyroczni, dowody z działania)Zatwierdzenia opierają się na zaufaniu, nie na dowodach
Odsetek ucieczek według etapuBłędy produkcyjne przypisane do pull requestów zatwierdzonych na etapie evidence-only, podzielone przez wszystkie pull requesty zatwierdzone na tym etapie, per klasa zmian, per miesiącKlasa awansowała za wcześnie; cofnij ją
Pokrycie eskalacjiOdsetek scalonych pull requestów dotykających klasy eskalacji, które mają zapisaną wskazaną osobę czytającą kodLista eskalacji jest obchodzona

Raportuj je per klasa zmian, nigdy jako jedną uśrednioną liczbę. Kanoniczne definicje i punkty odniesienia są na stronie o frameworkach metryk dla inżynierii agentowej. Pytanie, które członek zarządu powinien zadać CTO, jest krótkie: „Które klasy zmian trafiają do main bez czytania kodu przez człowieka, kto o tym zdecydował i jaki jest odsetek ucieczek w tych klasach?”.

Testy zmieniają się w tym samym pull requeście co oceniany przez nie kod i nikt tego nie zauważa. To najczęstszy sposób, w jaki zielony przebieg agenta traci znaczenie. Wyjście: zrób ze zmian wyroczni klasę eskalacji w CODEOWNERS i dodaj krok CI, który wypisuje każdy zmodyfikowany plik testowy w podsumowaniu pull requesta.

Podsumowanie dowodów streszcza diff zamiast raportować wyniki. „Zaktualizowano handler, żeby walidował wejście” to opis kodu, nie dowód. Wyjście: odrzucaj każdą linię akceptacji bez plik:linia albo komendy z kodem wyjścia i wymagaj, żeby agent uruchamiał sprawdzenia, na które się powołuje.

Błąd ucieka w klasie, którą zatwierdzasz na samych dowodach. Wyjście: cofnij klasę o jeden etap w dzienniku zaufania, napisz sprawdzenie, które wyłapałoby ten błąd, i dodaj je do wyroczni, zanim znów awansujesz klasę. Oznacz incydent kontrolą, która zawiodła, tak jak opisuje taksonomia błędów.

Nie umiesz już wyjaśnić modułu zatwierdzonego miesiąc temu. Wewnętrzne badanie Anthropic (Saffron Huang i współpracownicy, 2 grudnia 2025; ankieta wśród 132 inżynierów i badaczy, 53 wywiady) nazywa to „paradoksem nadzoru” (paradox of supervision): nadzorowanie agentów wymaga dokładnie tych umiejętności, które nadmierne delegowanie osłabia. Wyjście: raz w tygodniu przeczytaj w całości jeden pull request z próbki, w klasie, za którą odpowiadasz, i zanim zaczniesz czytać, poproś agenta o wyjaśnienie projektu. Twój warsztat i kariera opisuje, które umiejętności podtrzymywać świadomie.

Lista eskalacji po cichu rośnie albo po cichu maleje. Lista, która rozrasta się do połowy repozytorium, cofa cię na poziom 3; lista, która maleje bez spisanej decyzji, to droga, którą kod uwierzytelniania trafia do main nieprzeczytany. Wyjście: zmieniaj listę tylko w zrecenzowanym pull requeście do CODEOWNERS, z uzasadnieniem w opisie commita.

Dowody z działania zawsze pokazują ścieżkę pozytywną. Jeden zrzut ekranu udanego zamówienia dowodzi jednej ścieżki. Wyjście: wymagaj dowodów z działania dla każdego kryterium akceptacji, łącznie z przypadkami błędów, które wymienia specyfikacja.

Najczęstsze pytania

Co czytać zamiast diffa agenta?

Cztery rzeczy, w tej kolejności: zmianę specyfikacji (jakie zachowanie zmiana deklaruje), wyniki akceptacji (każde kryterium przypisane do sprawdzenia, które się wykonało), siłę wyroczni (czy testy mogły w ogóle nie przejść i czy agent ich dotykał) oraz sygnały z działającego środowiska: preview, stagingu albo canary.

Które zmiany wciąż wymagają, żeby człowiek przeczytał kod?

Uwierzytelnianie i autoryzacja, pieniądze, schematy i migracje danych, a także każda zmiana, która modyfikuje własną wyrocznię (testy, CI, konfigurację lintera lub typów), oraz każda zmiana, której nie pokrywa żadne sprawdzenie. W tych klasach wyrocznia jest słaba, informacja zwrotna wolna albo szkoda trudna do cofnięcia, więc kod czyta wskazana z nazwiska osoba.

Po czym poznać, że za wcześnie przestałem czytać kod?

Błędy trafiają na produkcję w klasie, którą zatwierdzasz na samych dowodach, testy zmieniają się w tym samym pull requeście co oceniany przez nie kod, nie umiesz już wyjaśnić modułu zatwierdzonego miesiąc temu albo podsumowanie dowodów streszcza diff zamiast raportować wyniki sprawdzeń. Każdy z tych sygnałów cofa daną klasę o jeden etap zaufania.

Czy zatwierdzenie na podstawie dowodów to to samo co merge bez review?

Nie. Merge bez review nie ma nikogo odpowiedzialnego ani śladu. Review dowodów ma wskazaną osobę zatwierdzającą, spisaną zmianę specyfikacji, sprawdzenia, które się wykonały, i klasę ryzyka, która zdecydowała, czy trzeba czytać kod.