Ocena i iteracja oparte na dowodach
ENPętla oceny oparta na dowodach punktuje artefakt handoffu, taki jak kierunek wizualny, prototyp, kontrakt designu czy specyfikacja, względem spisanych kryteriów akceptacji. Ocenia go recenzent, który artefaktu nie tworzył, każdy punkt cytuje odtwarzalny dowód, wynikiem handoffu jest najniższy wymiar, a pętla kończy się na jawnym progu lub nazwanym warunku stopu.
Agent poprawił kontrakt designu checkoutu cztery razy i raportował kolejno 7/10, 8/10, 8,5/10, a na końcu 9,5/10. Otwierasz czwartą wersję: stanu odrzuconej karty nadal nie ma, pojawił się nowy kolor, a nikt nie potrafi powiedzieć, które wcześniejsze uwagi naprawiono, a które po cichu zniknęły. Ta strona jest dla developerów i tech leadów, którzy przekazują artefakty etapu planowania między ludźmi i agentami i chcą wyniku, na którym da się oprzeć bramkę, a nie liczby wystawionej przez autora samemu sobie.
Co daje pętla oceny oparta na dowodach
Dział zatytułowany „Co daje pętla oceny oparta na dowodach”- Rubrykę z czterema wymiarami, w której decyduje minimum, i JSON Schema wymuszającą ten sam kształt każdej oceny.
- Polecenie uruchamiające recenzję tylko do odczytu dla Claude Code i Codeksa oraz odpowiednik tej procedury w Cursorze.
- Bramkę w
jq, która sama liczy wynik, zamiast ufać arytmetyce recenzenta. - Rejestr uwag (ledger) z dyspozycją dla każdej uwagi, dzięki któremu poprawki są śledzone, a nie pamiętane.
- Trzy prompty do skopiowania: ocena, poprawka i ponowna ocena.
- Warunki stopu, procedurę kalibracji recenzenta i sposoby wyjścia z typowych awarii pętli.
Kiedy warto uruchomić pętlę oceny?
Dział zatytułowany „Kiedy warto uruchomić pętlę oceny?”Pętla kosztuje jedno review na iterację plus decyzję człowieka na końcu. Stosuj ją tam, gdzie błędny handoff oznacza przeróbki w dalszych etapach, a nie przy każdym artefakcie.
| Sytuacja | Zastosowanie |
|---|---|
| Artefakt z pipeline’u czterech artefaktów wrócił z review więcej niż raz | Pełna pętla |
Kontrakt designu lub spec.md, z którego skorzysta kilka zadań implementacyjnych | Pełna pętla, próg 9 |
| Ścieżka widoczna dla klienta z ryzykiem dostępności lub prawnym | Pełna pętla plus akceptacja tych wymiarów przez nazwaną osobę |
| Wewnętrzny ekran zbudowany wyłącznie z istniejących komponentów | Jedna ocena, bez iteracji, chyba że pojawi się bloker |
| Poprawka tekstu lub odstępów | Bez pętli; zwykłe review zmiany |
Pętla ocenia artefakty, które akceptuje człowiek. Zakłada, że kryteria już istnieją; jeśli nie, najpierw je napisz, korzystając z wykonywalnych kryteriów akceptacji. Ocena kodu, który powstaje z artefaktu, to inne zadanie — opisują je kontrole oceniane przez model i review PR przez agenta.
Jak rubryka punktuje handoff
Dział zatytułowany „Jak rubryka punktuje handoff”Cztery wymiary obejmują to, co psuje się w handoffach etapu planowania. Każdy dostaje od 0 do 10, a wynikiem handoffu jest minimum, nie średnia: dopracowany system wizualny nie rekompensuje brakującego stanu błędu.
| Wymiar | 10, gdy | Typowy dowód |
|---|---|---|
| Zgodność z intencją | Każde kryterium akceptacji i każdy non-goal z intent.md lub spec.md są spełnione i cytowane po ID | ID kryterium, sekcja lub ramka, która je spełnia |
| Kompletność stanów | Jest każdy wymagany stan, breakpoint, wariant treści, ścieżka klawiatury i błąd | Wiersz w states.md, nazwa fixture’a, ścieżka zrzutu ekranu |
| Spójność systemu | Używane są tylko kanoniczne tokeny, komponenty, wzorce interakcji i terminy | Wynik bramki tokenów, lista komponentów, termin ze słownika |
| Jakość dowodów | Inny recenzent odtworzy każdą uwagę z podanej trasy, stanu, viewportu i kontroli | Polecenie lub trasa do ponownego uruchomienia, wersja artefaktu |
10 nie znaczy „wygląda świetnie”. Znaczy, że każde zadeklarowane kryterium ma odtwarzalny dowód i nie ma otwartego blokera. Dla zwykłej pracy ustaw próg wydania na 9: bez otwartego blokera, bez kryterium w stanie fail lub not-tested i z zapisaną akceptacją człowieka.
Zapisz ten schemat jako design/rating.schema.json. Recenzent zwraca dzięki niemu za każdym razem tę samą strukturę, więc skrypt może na niej oprzeć bramkę. Każdy obiekt ma additionalProperties: false i wymienia wszystkie swoje pola jako wymagane, bo --output-schema w Codeksie oczekuje schematu w trybie strict. Zakres 0–10 zostaw w prompcie, a oceny spoza niego niech odrzuca bramka jq z kroku 4 — wtedy zakres egzekwuje skrypt, a nie zaufanie do recenzenta.
{ "type": "object", "additionalProperties": false, "required": ["artifact_version", "criteria", "dimensions", "findings"], "properties": { "artifact_version": { "type": "string" }, "criteria": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "result", "evidence"], "properties": { "id": { "type": "string" }, "result": { "type": "string", "enum": ["pass", "fail", "not-tested"] }, "evidence": { "type": "string" } } } }, "dimensions": { "type": "object", "additionalProperties": false, "required": ["intent", "states", "system", "evidence"], "properties": { "intent": { "type": "integer" }, "states": { "type": "integer" }, "system": { "type": "integer" }, "evidence": { "type": "integer" } } }, "findings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "criterion", "severity", "evidence", "fix"], "properties": { "id": { "type": "string" }, "criterion": { "type": "string" }, "severity": { "type": "string", "enum": ["blocker", "major", "minor"] }, "evidence": { "type": "string" }, "fix": { "type": "string" } } } } }}Uruchom pętlę oceny
Dział zatytułowany „Uruchom pętlę oceny”-
Zamroź ocenianą wersję.
Zapisz artefakt w commicie albo przypnij link z narzędzia designu do konkretnej wersji i zapisz jej identyfikator w
design/checkout/VERSION. Oceny, która nie wskazuje dokładnej wersji, nie da się porównać z następną. Wszystkie oceny jednego artefaktu trzymaj wdesign/<feature>/ratings/, numerowaner1.json,r2.jsoni tak dalej. Przy każdym przebiegu zwiększaj numer rundy i nigdy nie nadpisuj istniejącego pliku oceny: ponowna ocena porównuje wynik z poprzednim. -
Najpierw uruchom kontrole deterministyczne.
Co może rozstrzygnąć maszyna, rozstrzyga maszyna: spec stanów w Playwright, skan axe i bramka tokenów z pipeline’u czterech artefaktów albo linter specyfikacji dla artefaktów tekstowych. Umieść te polecenia w
design/checkout/checks/run.sh, żeby każda runda i wykonawca poprawek uruchamiali dokładnie te same kontrole, i niech skrypt zapisuje wynik wdesign/checkout/checks/. Recenzent cytuje go jako dowód; kontrola, która nie przechodzi, ogranicza ocenę wymiaru, którego dotyczy, niezależnie od tego, co recenzent sądzi o reszcie. -
Oceń artefakt w świeżym kontekście, tylko do odczytu.
Recenzentem nie może być sesja, która wytworzyła artefakt, a sam recenzent nie może mieć prawa do jego edycji. Zapisz poniższy prompt jako
design/checkout/rate-prompt.md.Uruchom go w trybie headless, żeby wynik trafił do pliku:
Okno terminala claude -p --permission-mode dontAsk \--allowedTools "Read Grep Glob" \--disallowedTools "Edit Write NotebookEdit Bash" \--output-format json \--json-schema "$(cat design/rating.schema.json)" \"$(cat design/checkout/rate-prompt.md)" \| jq '.structured_output' > design/checkout/ratings/r1.jsondontAskodrzuca każde wywołanie narzędzia, które wymagałoby pytania (odczyty w katalogach roboczych i polecenia tylko do odczytu nadal działają), a--disallowedToolsodbiera narzędzia zapisu nawet wtedy, gdy plik ustawień na nie zezwala, więc recenzent może czytać, ale nie pisać; z--json-schemazwalidowany obiekt trafia do polastructured_output(sprawdzone na Claude Code 2.1.283).Okno terminala codex exec --ephemeral \-c 'default_permissions=":read-only"' \--output-schema design/rating.schema.json \-o design/checkout/ratings/r1.json \< design/checkout/rate-prompt.md:read-onlyto wbudowany profil uprawnień (beta w Codex CLI 0.157.1; nie łącz go ze starszą flagą-s read-only, bo według OpenAI tych dwóch mechanizmów nie da się łączyć),-ozapisuje do pliku końcową wiadomość w kształcie schematu, a--ephemeralnie zapisuje plików sesji, więc review nie da się przez pomyłkę wznowić jako zadania poprawki.Otwórz nowy czat Agenta, nie ten, w którym powstał artefakt. Wklej prompt, dołącz przez
@artefakt, kryteria, wynik kontroli idesign/rating.schema.json, a następnie poproś o JSON w jednym bloku kodu. Ten blok zapisz samodzielnie jakodesign/checkout/ratings/r1.json. Review ma tylko czytać, więc odrzuć każdą edycję pliku zaproponowaną przez czat; edycja unieważnia ocenę i trzeba ją powtórzyć.W Claude Code to samo rozdzielenie przy pracy interaktywnej w ramach sesji daje własny subagent z dostępem tylko do odczytu.
-
Opieraj bramkę na skrypcie, nie na podsumowaniu recenzenta.
Recenzent dostarcza osądy, skrypt liczy. Ta bramka kończy się kodem różnym od zera, chyba że ocena wskazuje zamrożoną wersję, każdy wymiar mieści się w zakresie 0–10, najniższy wymiar ma co najmniej 9, nie ma otwartego blokera, a każde kryterium przechodzi. Uruchamiaj ją na najnowszym pliku oceny:
Okno terminala jq -e --arg v "$(cat design/checkout/VERSION)" '{version_ok: (.artifact_version == $v),in_range: ([.dimensions[]] | all(. >= 0 and . <= 10)),score: ([.dimensions[]] | min),blockers: ([.findings[] | select(.severity == "blocker")] | length),not_passing: ([.criteria[] | select(.result != "pass")] | length)}| ., (.version_ok and .in_range and .score >= 9 and .blockers == 0 and .not_passing == 0)' design/checkout/ratings/r1.jsonPolecenie wypisuje pięć wartości, a potem
truelubfalse;-eustawia kod wyjścia na podstawie tej ostatniej wartości, więc to samo polecenie działa w terminalu, w zadaniu przed mergem i w skrypcie pętli. Ocena niewłaściwej wersji albo z wynikiem spoza zakresu 0–10 oblewa bramkę, zamiast po cichu przejść. -
Nadaj każdej uwadze dyspozycję w rejestrze.
Skopiuj uwagi do
design/checkout/findings.md, po jednym wierszu na uwagę, a dyspozycję niech ustawi właściciel artefaktu. Uwag nigdy się nie usuwa; zmienia się tylko ich status.| ID | Round | Criterion | Severity | Status | Owner | Note || F-1 | r1 | AC-4 | blocker | fixed | design lead | fixed in r2, verified r3 || F-2 | r1 | AC-7 | major | accepted | product | ships without offline state || F-3 | r2 | AC-4 | minor | open | design lead | |acceptedoznacza, że nazwana osoba zdecydowała się wydać artefakt z tą luką;duplicatewskazuje inne ID;fixedustawia właściciel artefaktu na podstawiefix-notes.mdi ten status pozostaje tymczasowy, dopóki następna ponowna ocena nie potwierdzi go dowodem;opento wszystko pozostałe. -
Poprawiaj w osobnym zadaniu.
Wykonawca poprawek dostaje rejestr, a nie całą rozmowę z recenzentem. Może zmieniać artefakt i nic więcej.
-
Oceń ponownie w nowym kontekście, z rejestrem.
Świeży recenzent ocenia nową wersję i sprawdza też poprzedni rejestr, więc weryfikuje stare uwagi i szuka nowych. Zapisz poniższy prompt jako
design/checkout/rerate-prompt.md.Uruchom go jak w kroku 3, z dwiema zmianami. Nowa ocena trafia najpierw do pliku tymczasowego i przenosi się do
ratings/dopiero wtedy, gdy jest poprawnym JSON-em, a poprzednią rundę wskazuje ostatnia linia promptu. Zwykłe> r2.jsonnie byłoby tu bezpieczne: powłoka tworzy pusty plik docelowy, zanim recenzent wystartuje, więc recenzent, który miałby czytać „najnowszy plik”, porównałby wynik z pustymr2.jsoni nie znalazłby żadnej regresji. Przy pierwszej ponownej ocenieprevtor1.json, anexttor2.json:Okno terminala prev=design/checkout/ratings/r1.jsonnext=design/checkout/ratings/r2.jsontmp=$(mktemp)test -s "$prev" && test ! -e "$next" \&& claude -p --permission-mode dontAsk \--allowedTools "Read Grep Glob" \--disallowedTools "Edit Write NotebookEdit Bash" \--output-format json \--json-schema "$(cat design/rating.schema.json)" \"$(cat design/checkout/rerate-prompt.md)Previous rating file: $prev" \| jq -e '.structured_output' > "$tmp" \&& mv "$tmp" "$next"Okno terminala prev=design/checkout/ratings/r1.jsonnext=design/checkout/ratings/r2.jsontmp=$(mktemp)test -s "$prev" && test ! -e "$next" \&& { cat design/checkout/rerate-prompt.mdprintf 'Previous rating file: %s\n' "$prev"; } \| codex exec --ephemeral \-c 'default_permissions=":read-only"' \--output-schema design/rating.schema.json \-o "$tmp" - \&& jq -e . "$tmp" > /dev/null \&& mv "$tmp" "$next"Końcowy
-sprawia, żecodex execczyta cały prompt, razem z dopisaną linią, ze standardowego wejścia.Otwórz kolejny nowy czat Agenta, wklej prompt ponownej oceny i dopisz na końcu linię
Previous rating file: design/checkout/ratings/r1.json, dołącz przez@te same pliki orazfindings.md,fix-notes.mdi ten poprzedni plik oceny, a JSON zapisz jakodesign/checkout/ratings/r2.jsondopiero po odpowiedzi czatu.Łańcuch zawodzi bezpiecznie i niczego nie zmienia w
ratings/, gdy poprzedni plik nie istnieje lub jest pusty, gdy następny plik już istnieje albo gdy recenzent kończy się błędem lub nie zwraca oceny (jq -ezwraca niezerowy kod przy pustym wyniku lubnull). W następnej rundzieprevtor2.json, anexttor3.jsoni tak dalej. Potem uruchom bramkę z kroku 4 na nowym pliku i zaktualizuj rejestr. -
Zatrzymaj pętlę i przekaż decyzję człowiekowi.
Gdy bramka przechodzi albo zachodzi któryś z warunków stopu poniżej, pętla się kończy. Nazwana osoba akceptuje artefakt i rejestr, a oba trafiają dalej do
spec.md,plan.mdi do pakietu dowodów pull requestu.
Pozwól recenzentowi zbierać dowody w przeglądarce
Dział zatytułowany „Pozwól recenzentowi zbierać dowody w przeglądarce”Recenzent, który tylko czyta pliki, może cytować wyłącznie zapisany wynik kontroli. Aby sam otworzył działającą aplikację i zebrał dowody dla stanów i viewportów, załaduj serwer Playwright MCP (@playwright/mcp, wersja 0.0.82 w npm 26.09.2026) tylko na przebieg review. Przypnij tę wersję, żeby każda runda zbierała dowody tymi samymi narzędziami przeglądarki.
Zastąp linię --allowedTools w poleceniu z kroku 3 tymi trzema opcjami. --strict-mcp-config ładuje tylko ten serwer i pomija serwery MCP z konfiguracji użytkownika i projektu, z których część może zapisywać; mcp__playwright zezwala na wszystkie narzędzia tego jednego serwera.
--strict-mcp-config \--mcp-config '{"mcpServers":{"playwright":{"command":"npx","args":["@playwright/mcp@0.0.82"]}}}' \--allowedTools "Read Grep Glob mcp__playwright"Dodaj te nadpisania konfiguracji przed --output-schema w poleceniu z kroku 3. codex mcp add też zadziała, ale zapisuje serwer w ~/.codex/config.toml dla wszystkich przyszłych sesji, a nie tylko dla tego review.
-c 'mcp_servers.playwright.command="npx"' \-c 'mcp_servers.playwright.args=["@playwright/mcp@0.0.82"]' \Kiedy pętla oceny powinna się zatrzymać?
Dział zatytułowany „Kiedy pętla oceny powinna się zatrzymać?”Przestań iterować i oddaj kontrolę człowiekowi, gdy zachodzi którykolwiek z warunków:
- Bramka przechodzi, a każda pozostała uwaga ma dyspozycję.
- Dwie rundy z rzędu nie poprawiają tego samego nieprzechodzącego kryterium. Kolejne rundy rzadko pomagają; błędne jest kryterium, artefakt albo narzędzie.
- Brakuje decyzji produktowej, prawnej albo decyzji w sprawie marki, prywatności lub dostępności. Agent jej nie podejmie, niezależnie od tego, ile razy go poprosisz.
- Poprawka uwagi zmieniłaby zaakceptowaną intencję, non-goal lub architekturę. To nowa decyzja, a nie iteracja.
- Recenzent nie potrafi odtworzyć artefaktu ani zebrać dowodu, którego wymaga kryterium.
- Dochodzisz do limitu rund. Ustal go przed startem; trzy rundy to rozsądna wartość domyślna dla jednego artefaktu.
Kto zatwierdza i jak zaufać recenzentowi?
Dział zatytułowany „Kto zatwierdza i jak zaufać recenzentowi?”Ocena jest dowodem dla decyzji człowieka, nigdy samą decyzją. Agent, który wytworzył artefakt, może skrytykować własną pracę w pierwszym przejściu, ale nie może jej certyfikować, bo może przeoczyć ten sam błąd, który sam wprowadził.
| Decyzja | Podejmuje | Na podstawie |
|---|---|---|
| Kryteria i próg | Właściciel artefaktu, przed rundą 1 | acceptance.md, ryzyko zmiany |
| Dyspozycja każdej uwagi | Właściciel artefaktu; produkt dla zakresu, właściciel design systemu dla tokenów | Dowody w rejestrze |
accepted dla luki w dostępności, kwestii prawnej lub prywatności | Nazwany właściciel tego obszaru | Dowód z uwagi i zapisany powód |
| Akceptacja handoffu | Właściciel artefaktu | Przechodząca bramka, rejestr, ostatni plik oceny |
Sprawdzaj recenzenta tak jak każdy test. Dwie procedury utrzymują go w ryzach:
- Wstaw znany defekt. Zanim zaczniesz polegać na nowej rubryce lub prompcie, usuń jeden wymagany stan z kopii zaakceptowanego artefaktu i oceń ją. Jeśli recenzent nie zgłosi blokera przy tym kryterium, prompt albo kryteria są zbyt słabe.
- Porównaj z oceną człowieka. Dla próbki handoffów niech osoba oceni tę samą wersję tą samą rubryką, zanim przeczyta ocenę agenta. Tam, gdzie oceny różnią się w danym wymiarze o więcej niż punkt, zaostrz kryteria tego wymiaru. O zamienianiu takich próbek w zestaw regresyjny piszemy w ewaluacji agentów.
Co psuje się w pętli oceny?
Dział zatytułowany „Co psuje się w pętli oceny?”Wynik rośnie, artefakt nie. Recenzent ocenia notatki wykonawcy zamiast artefaktu. Wyjście: oceniaj wyłącznie zamrożoną wersję, porównuj identyfikatory wersji między rundami i traktuj każdą uwagę fixed bez dowodu w bieżącej wersji jako bloker, tak jak robi to prompt ponownej oceny.
Wszystko dostaje 9 lub 10. Kryteria są zbyt luźne, żeby cokolwiek oblało. Wyjście: uruchom kontrolę ze wstawionym defektem, dodaj do acceptance.md stany negatywne i ścieżki błędów oraz obniż w prompcie limit dla twierdzeń bez dowodu.
Recenzent edytuje artefakt. Review działało z prawem zapisu, zwykle w sesji, która artefakt wytworzyła. Wyjście: odrzuć edycje, powtórz ocenę poleceniem read-only i trzymaj poprawki w osobnym zadaniu.
Uwagi znikają między rundami. Świeży recenzent nie wie, co znalazł poprzedni. Wyjście: zawsze przekazuj rejestr do ponownej oceny i nigdy nie usuwaj wierszy rejestru.
Pętla nie zbiega się. Każda runda naprawia jedną uwagę i tworzy kolejną. Wyjście: zatrzymaj się na limicie rund, porównaj obok siebie dwa ostatnie pliki oceny i sprawdź, czy kryteria nie są sprzeczne albo czy artefakt nie potrzebuje decyzji właściciela.
Gust wygrywa z funkcją. Rundy krążą wokół odstępów i sformułowań, a stanu wciąż brakuje. Wyjście: najpierw naprawiaj blokery dotyczące intencji, stanów i dostępności, a uwagi minor o spójności systemu odłóż na późniejszą rundę.
Sprawdź ocenę przed handoffem
Dział zatytułowany „Sprawdź ocenę przed handoffem”- Plik oceny wskazuje dokładną wersję artefaktu, którą oceniono.
- Każde kryterium
failinot-testedcytuje dowód, który inny recenzent odtworzy. - Bramka
jqprzechodzi na ostatnim pliku oceny. - Każda uwaga w rejestrze ma status, a każdy wiersz
acceptedwskazuje właściciela. - Ostatnia ocena odbyła się w świeżym kontekście tylko do odczytu.
- Zaakceptowana ocena i rejestr są dołączone do artefaktu następnego etapu.
Dokąd dalej po pętli oceny
Dział zatytułowany „Dokąd dalej po pętli oceny”- Oceń kierunek wizualny, zanim ruszy implementacja, według przewodnika Akceptacja wizualna przed implementacją frontendu.
- Stosuj pętlę na każdym handoffie pipeline’u design-to-code z czterema artefaktami.
- Kryteria, względem których warto oceniać, napiszesz według przewodnika Wykonywalne kryteria akceptacji.
- Trzymaj kontrole, na których polega recenzent, poza zasięgiem agenta dzięki ochronie wyroczni.
- Zastosuj ten sam wzorzec do pull requestów w ograniczonej pętli review-fix dla PR.