Przejdź do głównej zawartości

Pę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.

  • 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.

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.

SytuacjaZastosowanie
Artefakt z pipeline’u czterech artefaktów wrócił z review więcej niż razPełna pętla
Kontrakt designu lub spec.md, z którego skorzysta kilka zadań implementacyjnychPełna pętla, próg 9
Ścieżka widoczna dla klienta z ryzykiem dostępności lub prawnymPełna pętla plus akceptacja tych wymiarów przez nazwaną osobę
Wewnętrzny ekran zbudowany wyłącznie z istniejących komponentówJedna ocena, bez iteracji, chyba że pojawi się bloker
Poprawka tekstu lub odstępówBez 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.

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.

Wymiar10, gdyTypowy 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 IDID kryterium, sekcja lub ramka, która je spełnia
Kompletność stanówJest każdy wymagany stan, breakpoint, wariant treści, ścieżka klawiatury i błądWiersz w states.md, nazwa fixture’a, ścieżka zrzutu ekranu
Spójność systemuUżywane są tylko kanoniczne tokeny, komponenty, wzorce interakcji i terminyWynik bramki tokenów, lista komponentów, termin ze słownika
Jakość dowodówInny recenzent odtworzy każdą uwagę z podanej trasy, stanu, viewportu i kontroliPolecenie 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" }
}
}
}
}
}
  1. 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 w design/<feature>/ratings/, numerowane r1.json, r2.json i 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.

  2. 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 w design/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.

  3. 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.json

    dontAsk odrzuca każde wywołanie narzędzia, które wymagałoby pytania (odczyty w katalogach roboczych i polecenia tylko do odczytu nadal działają), a --disallowedTools odbiera narzędzia zapisu nawet wtedy, gdy plik ustawień na nie zezwala, więc recenzent może czytać, ale nie pisać; z --json-schema zwalidowany obiekt trafia do pola structured_output (sprawdzone na Claude Code 2.1.283).

    W Claude Code to samo rozdzielenie przy pracy interaktywnej w ramach sesji daje własny subagent z dostępem tylko do odczytu.

  4. 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.json

    Polecenie wypisuje pięć wartości, a potem true lub false; -e ustawia 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ść.

  5. 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 | |

    accepted oznacza, że nazwana osoba zdecydowała się wydać artefakt z tą luką; duplicate wskazuje inne ID; fixed ustawia właściciel artefaktu na podstawie fix-notes.md i ten status pozostaje tymczasowy, dopóki następna ponowna ocena nie potwierdzi go dowodem; open to wszystko pozostałe.

  6. Poprawiaj w osobnym zadaniu.

    Wykonawca poprawek dostaje rejestr, a nie całą rozmowę z recenzentem. Może zmieniać artefakt i nic więcej.

  7. 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.json nie 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 pustym r2.json i nie znalazłby żadnej regresji. Przy pierwszej ponownej ocenie prev to r1.json, a next to r2.json:

    Okno terminala
    prev=design/checkout/ratings/r1.json
    next=design/checkout/ratings/r2.json
    tmp=$(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"

    Ł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 -e zwraca niezerowy kod przy pustym wyniku lub null). W następnej rundzie prev to r2.json, a next to r3.json i tak dalej. Potem uruchom bramkę z kroku 4 na nowym pliku i zaktualizuj rejestr.

  8. 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.md i do pakietu dowodów pull requestu.

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.

Okno terminala
--strict-mcp-config \
--mcp-config '{"mcpServers":{"playwright":{"command":"npx","args":["@playwright/mcp@0.0.82"]}}}' \
--allowedTools "Read Grep Glob mcp__playwright"

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.

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ł.

DecyzjaPodejmujeNa podstawie
Kryteria i prógWłaściciel artefaktu, przed rundą 1acceptance.md, ryzyko zmiany
Dyspozycja każdej uwagiWłaściciel artefaktu; produkt dla zakresu, właściciel design systemu dla tokenówDowody w rejestrze
accepted dla luki w dostępności, kwestii prawnej lub prywatnościNazwany właściciel tego obszaruDowód z uwagi i zapisany powód
Akceptacja handoffuWłaściciel artefaktuPrzechodzą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.

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ę.

  • Plik oceny wskazuje dokładną wersję artefaktu, którą oceniono.
  • Każde kryterium fail i not-tested cytuje dowód, który inny recenzent odtworzy.
  • Bramka jq przechodzi na ostatnim pliku oceny.
  • Każda uwaga w rejestrze ma status, a każdy wiersz accepted wskazuje 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.