Człowiek w pętli: osąd przy bramkach, nie w każdym diffie

Człowiek w pętli, gdy kod pisze agent, podejmuje cztery decyzje: o intencji (czy warto), specyfikacji (co znaczy „gotowe”), dowodach (czy sprawdzenia to udowodniły) i klasie ryzyka (czy ktoś musi przeczytać kod). Między bramkami agent planuje, buduje i sam się sprawdza. Diffy czyta się tylko w klasach eskalacji: uwierzytelnianie, pieniądze, schematy, migracje i zmiany samych sprawdzeń.

Ta strona jest dla developerów, którzy codziennie pracują z agentami, i dla tech leadów, którzy muszą z tego zrobić powtarzalny proces. Oto sytuacja, na którą odpowiada. Agent przepisał twój moduł uwierzytelniania: 15 plików, 800 linii, wszystko na zielono. Przejrzałeś to pobieżnie i zatwierdziłeś, bo wyglądało wiarygodnie. Dwa tygodnie później okazuje się, że przepisanie usunęło sprawdzanie CSRF. Uważniejsze czytanie by tu nie pomogło, bo o szesnastej nikt nie czyta uważnie 800 linii. Zabrakło dwóch bramek: żadne kryterium akceptacji nie mówiło „żądania POST z obcej domeny są odrzucane” i nic nie kierowało zmiany w uwierzytelnianiu do wskazanej osoby, która ją przeczyta.

Co daje osąd przy bramkach

Cztery bramki z decyzją, której wymaga każda, artefaktem, na który patrzysz, i budżetem czasu, żebyś wiedział, gdzie idzie twoja uwaga.
Listę sygnałów, które uzasadniają przerwanie agenta w trakcie pracy, i dłuższą listę rzeczy, których nie ruszasz.
Cztery prompty do skopiowania: specyfikację z odsłoniętymi założeniami, kontrakt zakresu, pakiet dowodów z klasą ryzyka i przekierowanie w trakcie przebiegu.
Dwa artefakty do zacommitowania: blok CODEOWNERS, który egzekwuje bramkę klasy ryzyka, i klauzulę „zatrzymaj się i zapytaj” do AGENTS.md albo CLAUDE.md.
Mechanizmy w Claude Code, Codeksie i Cursorze, które utrzymują każdą bramkę.
Sposoby, na jakie review oparte na bramkach zawodzi, i wyjście z każdego z nich.

Dlaczego czytanie każdego diffa to zła pętla

Przegląd linia po linii miał sens, gdy diff pisał człowiek, a czas review rósł razem z czasem pisania. Agent psuje tę proporcję. Pisze szybciej, niż ty czytasz, więc review staje się wąskim gardłem, a potem przegląda się już tylko pobieżnie. Pobieżne przejrzenie to zatwierdzenie z gorszym śladem audytowym. Dane o obciążeniu review i argumenty za zmianą są na stronie o czytaniu dowodów zamiast kodu. Ta strona przyjmuje tę zmianę za punkt wyjścia i pokazuje, dokąd w zamian idzie twój osąd.

Przeciwny błąd to zatwierdzanie każdego zapisu pliku na bieżąco. Jesteś wtedy zajęty, ale nie skuteczny: widzisz każdy krok, ale nigdy całej zmiany na tle tego, o co prosiłeś. Na oba błędy jest jedno lekarstwo. Umieść ludzkie decyzje tam, gdzie tylko człowiek może je podjąć, a resztę zostaw deterministycznym sprawdzeniom.

Które decyzje zostają przy człowieku? Cztery bramki

Każda bramka to jedna decyzja. Agent przygotowuje artefakt, ty decydujesz. Budżety czasu to punkt wyjścia dla funkcji średniej wielkości, a nie wynik badań.

Bramka	Decyzja	Na co patrzysz	Budżet	Co idzie źle bez niej
1. Intencja	Czy warto to budować i co jest poza zakresem?	Jeden akapit: rezultat, dla kogo, czego nie robimy	2–5 min	Agent sprawnie buduje coś, czego nikt nie potrzebował
2. Specyfikacja	Co znaczy „gotowe” i które założenia są zgadywane?	Kryteria akceptacji, lista założeń oznaczonych `CONFIRMED` lub `GUESS` i kontrakt zakresu (pliki, zależności)	10–20 min	Reguły biznesowe zostają wymyślone, zakres się rozrasta
3. Dowody	Czy sprawdzenia udowodniły każde kryterium i czy mogły w ogóle nie przejść?	Zmiana specyfikacji, wyniki akceptacji, zmiany wyroczni, sygnały z działania	5–15 min	„Zielone” znaczy tylko tyle, że testy agenta zgadzają się z agentem
4. Klasa ryzyka	Merge na podstawie dowodów czy wskazana osoba czyta kod?	Zmienione ścieżki zestawione z klasami eskalacji	1 min na skierowanie; czas czytania tam, gdzie jest wymagane	Uwierzytelnianie, billing albo migracja trafiają do main nieprzeczytane

Najwięcej czasu spędź przy bramce 2. Błędne założenie wyłapane tutaj kosztuje jedno zdanie. Wyłapane przy bramce 3 kosztuje ponowny przebieg, a na produkcji — incydent. Bramka 2 to także moment, w którym kryteria akceptacji stają się czerwonymi testami, zanim agent napisze kod, i właśnie dzięki temu bramka 3 idzie szybko.

Bramka 3 ma własną stronę. Czytanie dowodów zamiast kodu opisuje, co czytać, w jakiej kolejności i jak sprawdzić, czy wyrocznia mogła w ogóle nie przejść. Code review PR-a agenta zamienia to w 15-minutowy protokół.

Bramka 4 to decyzja o skierowaniu, nie review. Klasy eskalacji to uwierzytelnianie i autoryzacja, pieniądze, schematy, migracje danych, zmiany samej wyroczni (testów, CI, lintera i konfiguracji typów) oraz wszystko, czego nie pokrywa żadne sprawdzenie. W tych klasach wskazana osoba czyta kod oprócz dowodów, za każdym razem. Wszędzie indziej zatwierdzasz na podstawie dowodów. Trzymaj tę listę krótką: lista, która obejmuje pół repozytorium, cofa cię na poziom 3.

Produkcja to ostatnia bramka w cyklu wytwarzania AI-native, a klasa ryzyka decyduje, jak jest pilnowana. Klasy niskiego ryzyka wychodzą przez progressive delivery z automatycznym rollbackiem. Klasy eskalacji wymagają wyraźnej zgody człowieka.

Między bramkami pozwól agentowi działać

Między bramkami twoim zadaniem jest wypatrywanie sygnałów, a nie pilnowanie każdego naciśnięcia klawisza. Przerwanie jest tanie na początku i drogie na końcu, więc używaj go tylko wtedy, gdy pojawi się któryś z tych sygnałów:

Agent edytuje plik spoza kontraktu zakresu.
Usuwa kod albo test i nie mówi dlaczego.
Dodaje zależność, o której nikt nie rozmawiał.
Pomija, luzuje albo wycisza sprawdzenie (.skip, // @ts-ignore, wygenerowany od nowa snapshot).
Jego podejście odbiega od zatwierdzonego planu.

Nie przeszkadzaj, gdy idzie po planie po kolei, dotyka plików, których się spodziewałeś, i sam poprawia swoje czerwone testy. Ta pętla to agent sprawdzający własną pracę i właśnie o nią chodzi.

Pierwsze cztery sygnały są mechaniczne, więc nie polegaj na tym, że je zauważysz. Hook PreToolUse może blokować edycję chronionych ścieżek, a krok CI może odrzucać pull request, który zmienia testy razem z kodem, który te testy oceniają. Zobacz hooki jako deterministyczne zabezpieczenia i ochronę wyroczni. Przy tobie zostaje piąty sygnał, bo tylko ty wiesz, czy odejście od planu to lepszy pomysł, czy nieporozumienie.

Przeprowadź jedno zadanie przez cztery bramki

Przykład dodaje limit żądań na użytkownika do app/api/checkout/route.ts w aplikacji Next.js. Każdy krok nazywa bramkę i podaje prompt, który ją przygotowuje.

Bramka 1, intencja: napisz ją sam. Wystarczą dwa zdania: „Nie pozwól jednemu kontu zasypywać checkoutu żądaniami; prawdziwy kupujący nigdy nie może trafić na limit. Poza zakresem: limity po IP i API administracyjne”. Agent tego nie dostarczy, więc go o to nie proś.

Bramka 2, specyfikacja: niech agent pokaże, co zgaduje. Uruchom poniższy prompt w trybie planowania (mechanizmy dla każdego narzędzia są w następnej sekcji). Najpierw przeczytaj listę założeń i popraw każde istotne GUESS, dopiero potem czytaj plan.

Plan only; do not edit any file. Goal: add per-user rate limiting to
app/api/checkout/route.ts. Out of scope: IP-based limits and the admin API.

1. Assumptions: list every business rule you are guessing at (limit value,
   window, response when limited, identity source, behaviour when the
   limit store is unavailable). Mark each CONFIRMED (cite the file or doc)
   or GUESS.
2. Acceptance criteria: 4-8 observable behaviours, each one a sentence a
   test can check, including the error cases.
3. Plan: numbered steps, each small enough to verify on its own, with the
   command that proves the step is done.
Stop after the plan and wait for my corrections.

Bramka 2, zakres: zatwierdź kontrakt, zanim powstanie kod. Kontrakt zamienia „agent wyszedł poza zakres” z czegoś, co zauważasz po fakcie, w coś, co może wyłapać sprawdzenie.

Before you write or modify any code, give me a scope contract:

1. Every file you plan to create or modify, with one line on what changes.
2. Every new dependency, with the reason it is needed.
3. Every file on this list that touches auth, billing, schema, migrations,
   tests, CI, or lint config.

Wait for my approval. If you later need a file outside this list, stop
and ask before touching it. Never modify an existing test to make it pass;
report the failure instead.

Między bramkami: pozwól mu budować. Zatwierdź plan i przełącz się na wykonanie. Agent najpierw pisze testy z kryteriów akceptacji, potem kod, i uruchamia zestaw testów, aż przejdzie. Ty wypatrujesz pięciu sygnałów z poprzedniej sekcji i poza tym nie przeszkadzasz.

Bramki 3 i 4, dowody i klasa ryzyka: poproś o pakiet, nie o diff. Poniższy prompt w jednym przebiegu prosi o cztery artefakty dowodowe i werdykt o skierowaniu. Pełniejsza wersja, z audytem wyroczni, jest na stronie o czytaniu dowodów zamiast kodu.

Do not edit any file. Report on this branch against main, in four parts:

1. Spec delta: each behaviour that changed, tied to the acceptance
   criterion that asked for it. List separately any change nobody asked for.
2. Acceptance results: criterion -> check (file:line or command) -> result.
   Run the checks; do not infer results. Mark a criterion with no check
   as UNVERIFIED.
3. Oracle changes: every test, snapshot, fixture, CI, lint, or type-config
   file this branch modifies, and whether the change is stricter, looser,
   or neutral.
4. Risk class: every changed file that matches auth, money, schema,
   migrations, or oracle paths, plus every UNVERIFIED criterion. End with
   one verdict: EVIDENCE (approve on evidence) or READ (list the files a
   named person must read, and the question to answer in each).

Zdecyduj. Werdykt EVIDENCE, każde kryterium sprawdzone, żadna wyrocznia nie poluzowana: zatwierdzasz. Werdykt READ: wskazana osoba czyta te pliki i tylko te, z pytaniem podanym w pakiecie. Tutaj limiter dotyka ścieżki checkoutu, którą twój zespół może zaliczać do pieniędzy. Jeśli tak jest, czytający sprawdza jedną rzecz: czy żądanie objęte limitem nadal może utworzyć zamówienie?

Gdy przebieg zaczyna dryfować, poprawiaj go wcześnie. Korekta po pierwszym pliku jest tańsza niż przepisywanie po piętnastym, a czysty restart jest lepszy niż długa dyskusja w zaśmieconym kontekście.

Stop. Your approach no longer matches the approved plan: the plan puts the
limit state in our existing Redis client (lib/redis.ts), and you added an
in-memory store. Revert the changes since step 2, reread lib/redis.ts, then
tell me which plan step you are on and what you will change before you
continue.

Zacommituj bramki, a nie tylko nawyk

Bramka, która istnieje tylko w twojej głowie, znika w dniu, w którym cię nie ma. Dwa małe artefakty sprawiają, że bramki obowiązują cały zespół.

Bramka klasy ryzyka należy do CODEOWNERS, z ochroną gałęzi ustawioną tak, by wymagała review od właścicieli kodu. Wtedy wskazanego czytającego pilnuje platforma, a nie czyjaś pamięć. Poniższe ścieżki to punkt wyjścia; dopasuj je do swojego repozytorium.

# .github/CODEOWNERS: escalation classes need a named reader.
# Later lines win, so keep the escalation block at the end.
/src/auth/                 @acme/security-reviewers
/src/middleware/           @acme/security-reviewers
/src/billing/              @acme/payments-owners
/app/api/checkout/         @acme/payments-owners
/db/migrations/            @acme/data-owners
*.sql                      @acme/data-owners
/.github/workflows/        @acme/platform-owners
/.eslintrc*                @acme/platform-owners
/eslint.config.*           @acme/platform-owners
/tsconfig*.json            @acme/platform-owners
*.test.ts                  @acme/tech-leads
**/__snapshots__/          @acme/tech-leads
*.snap                     @acme/tech-leads

Sygnały spomiędzy bramek należą do instrukcji, które czyta każda sesja: AGENTS.md dla Codeksu i CLAUDE.md dla Claude Code (który czyta też AGENTS.md, gdy projekt nie ma CLAUDE.md, od v2.1.277 na kanale latest). Cursor czyta własne Rules.

## Stop and ask

Stop and ask before you: edit a file outside the approved scope contract;
modify, skip, or delete an existing test, snapshot, CI step, or lint rule;
add a dependency; touch src/auth, src/middleware, src/billing,
app/api/checkout, or db/migrations. When a check fails, report the failure; do not weaken the check.

Miejscem, w którym organizacja spisuje te klasy raz, dla wszystkich repozytoriów, jest polityka governance i autonomii.

Jak Claude Code, Codex i Cursor utrzymują każdą bramkę

Bramki są takie same we wszystkich narzędziach. Różni się mechanizm, który utrzymuje każdą z nich.

Bramka 2 (specyfikacja): tryb planowania blokuje edycję, gdy agent planuje. Włączysz go przez /plan, przełączysz się na niego Shift+Tab albo uruchomisz sesję przez claude --permission-mode plan.
Między bramkami: od v2.1.283 (kanał latest) interaktywne sesje w terminalu i VS Code startują w trybie auto, w którym każdą akcję ocenia klasyfikator zamiast pytać ciebie. Przebiegi claude -p nadal startują w trybie Manual. Do każdego z nich dołóż hook PreToolUse, który blokuje chronione ścieżki z twojej listy „zatrzymaj się i zapytaj”.
Przekierowanie: Esc przerywa bieżącą akcję. Dwukrotne Esc przy pustym polu promptu albo /rewind przywraca wcześniejszy punkt kontrolny.
Bramka 3 (dowody): uruchom prompt z pakietem dowodów w sesji albo bez interfejsu przez claude -p. /code-review daje drugą opinię o lokalnym diffie.
Bramka 4 (klasa ryzyka): zarządzany Code Review (research preview, plany Team i Enterprise) czyta reguły przeznaczone tylko dla review z pliku REVIEW.md w katalogu głównym repozytorium, więc wpisz tam klasy eskalacji. Jego check run nigdy nie blokuje merge’a; bramką jest CODEOWNERS.

Bramka 2 (specyfikacja): przełącz się w tryb Plan przez /plan w TUI albo uruchom sesję planowania tylko do odczytu przez codex -c default_permissions=":read-only" (profile uprawnień są w becie; --sandbox read-only to starszy odpowiednik, więc używaj jednego albo drugiego).
Między bramkami: wykonanie uruchamiaj przez codex -c default_permissions=":workspace" -a on-request (model sam decyduje, kiedy cię zapytać) albo samodzielnie przez codex --approve-for-me (automatyczne review próśb o zgodę na starszym sandboksie workspace-write). Wybierz jedno, jak przy bramce 2: według OpenAI profile i starszy system sandboksa się nie łączą (sprawdzone na codex-cli 0.157.1). Klauzula „zatrzymaj się i zapytaj” w AGENTS.md obejmuje to, czego sandbox nie widzi.
Przekierowanie: wyślij prompt przekierowujący jako kolejną wiadomość w tej samej sesji albo zacznij nową sesję od poprawionego planu, gdy kontekst jest zaśmiecony.
Bramka 3 (dowody): uruchom prompt z pakietem dowodów przez codex exec. codex review --base main daje osobne code review gałęzi (sprawdzone na codex-cli 0.157.1).
Bramka 4 (klasa ryzyka): na GitHubie @codex review w pull requeście uruchamia ten sam rodzaj review; wpisz klasy eskalacji do AGENTS.md, żeby review wskazywało je z nazwy. Bramką jest CODEOWNERS.

Kiedy review oparte na bramkach zawodzi i jak z tego wyjść

Bramka specyfikacji zamienia się w pieczątkę. Zatwierdzasz plany bez czytania założeń, bo ostatnie dziesięć było w porządku. Wyjście: czytaj linie GUESS przed wszystkim innym, a plan bez żadnej linii GUESS traktuj jako sygnał ostrzegawczy: zapytaj agenta, które pozycje CONFIRMED faktycznie oparł na źródłach, i odrzuć plan, jeśli tych źródeł brakuje.

Lista eskalacji po cichu się rozrasta. Każdy incydent dopisuje katalog, aż pół repozytorium wymaga wskazanego czytającego, a review znowu jest wąskim gardłem. Wyjście: zmieniaj listę tylko przez przejrzany pull request do CODEOWNERS, z uzasadnieniem w opisie commita, i usuwaj ścieżkę, gdy pokrywa ją silniejsze sprawdzenie.

Dowody to parafraza diffa. „Zaktualizowałem handler, żeby walidował wejście” opisuje kod, niczego nie dowodzi. Wyjście: odrzucaj każdą linię akceptacji bez plik:linia albo komendy i jej wyniku, a agent niech uruchamia to, na co się powołuje.

Testy zmieniają się w tym samym pull requeście co kod. Agent, który edytuje własną wyrocznię, może sprawić, że każde sprawdzenie się z nim zgodzi. Wyjście: skieruj pliki testów, snapshotów, CI, lintera i konfiguracji typów do wskazanego czytającego w CODEOWNERS i dodaj do pliku z instrukcjami zdanie „nigdy nie zmieniaj istniejącego testu, żeby przeszedł”.

Błąd przecieka w klasie, którą zatwierdzasz na podstawie dowodów. Wyjście: napisz sprawdzenie, które by go wyłapało, dodaj je do wyroczni i przywróć tej klasie czytanie kodu, dopóki znowu nie zapracuje na zaufanie. Mechanizmem jest dziennik zaufania per klasa ze strony o czytaniu dowodów zamiast kodu; na cały zespół przenosi go strona o tym, jak pomóc zespołowi przestać czytać każdy diff.

Przestajesz rozumieć kod, za który odpowiadasz. Bramki przesuwają twoją uwagę na intencję i dowody, a zrozumienie może się przy tym rozmywać. Wyjście: raz w tygodniu przeczytaj w całości jeden wylosowany pull request w klasie, którą się zajmujesz, po tym, jak agent wyjaśni ci projekt. Strona o tym, co zostaje człowiekowi, opisuje obowiązki, których nie da się przekazać.

Dokąd dalej z osądem przy bramkach

Czytanie dowodów zamiast kodu Bramka 3 w szczegółach: co czytać, w jakiej kolejności i które zmiany wciąż wymagają czytania kodu.

Code review PR-a agenta Sześciokrokowy triaż, który stosuje bramki 3 i 4 do każdego pull requesta.

Wykonywalne kryteria akceptacji Bramka 2 w wersji wykonywalnej: kryteria stają się czerwonymi testami, zanim agent zacznie kodować.

Tryb agenta czy tryb zapytań Dyscyplina „najpierw tylko odczyt, potem wykonanie”, na której stoi bramka specyfikacji.

Co zostaje człowiekowi Sześć obowiązków, których nie przejmie agent.

Governance i autonomia Klasy ryzyka spisane raz, dla wszystkich repozytoriów.