Recenzja AI

Kształt recenzji

Recenzja AI to jedno uruchomienie wbudowanego potoku pr_review względem jednego otwartego pull requesta. Potok otwiera przestrzeń recenzji PR-a, rozgałęzia agentów-recenzentów, którzy czytają diff w izolowanym checkoutcie tej przestrzeni, każdy zgłasza swoje ustalenia jako ustrukturyzowane węzły recenzji, agent prowadzący scala je w przewodnik, a finalizator oblicza jeden werdykt: Ship, Hold lub Block. Potok nigdy nie publikuje — zamieszczenie recenzji na GitHubie to osobny, świadomy krok, który wykonuje człowiek.

W dalszej części strony wyjaśniamy te elementy i to, dlaczego mają właśnie taki kształt.

Jedna przestrzeń recenzji na PR

Kontekst recenzji PR-a to przestrzeń komunikacyjna — tryb review, rodzaj pr — powiązana z pull requestem przez powiązanie z przestrzenią recenzji. Powstaje idempotentnie: strona PR-a, potok recenzji i powierzchnie czatu rozwiązują jedną przestrzeń bazową PR-a tą samą ścieżką kodu, więc szablon, który recenzuje PR, i człowiek, który go otwiera, nigdy nie trafią do dwóch różnych pokoi patrzących na dwa różne checkouty.

Izolowany worktree przestrzeni ma PR wyewidencjonowany na jego head ref. Jeden pokój oznacza też jeden checkout: każdy recenzent pracuje w tej samej przestrzeni, a nie w swoim własnym klonie obszaru roboczego.

Każdy recenzent publikuje we własnym nazwanym strumieniu wewnątrz tej jednej przestrzeni, a ustalenia to wiadomości review_node, a nie zwykły tekst. Zbieranie w całej przestrzeni na końcu jest celowe — werdykt obliczony na podstawie ustaleń z jednego wątku byłby po cichu werdyktem o jednym recenzencie.

Powiązanie ma drabinkę statusów — requested → in progress → awaiting approval → completed — która stanowi bramkę dla Opublikuj na GitHubie na karcie Recenzja PR-a.

Poziomy recenzji

To, jak głęboko sięga recenzja, określają zasady obszaru roboczego z trzema poziomami, ustawiane w Ustawienia → Obszar roboczy → Ogólne, na karcie Zasady obszaru roboczego:

Poziom	Recenzenci w rozgałęzieniu	Raportowanie
light	Tylko inżynier	Tylko to, co naprawdę istotne
balanced	Inżynier, QA, architekt (domyślnie)	Standardowy przebieg
thorough	Wszyscy pięciu, w tym bezpieczeństwo i wydajność	Nic nie jest degradowane

Poziom przestawia dwa pokrętła naraz: to, którzy recenzenci się rozgałęziają (wymuszane przez bramki stanu runWhen w szablonie potoku, a nie przez brzmienie promptu — brzmienie promptu można zignorować, bramki nie), oraz to, gdzie renderowane są ustalenia poniżej progu. Żadne z tych pokręteł nigdy nie usuwa ustalenia: poziom, który raportuje mniej, wciąż zgłasza dokładnie tyle samo i grupuje resztę.

Przebiegi bezpieczeństwa i wydajności ponownie wykorzystują wbudowanych agentów architekta i inżyniera, zamiast wprowadzać nowych. Specjalizacja to zadanie, z którym wysyła się recenzenta, a nie osobny agent na każdą oś — agent na każdą oś to pięć dodatkowych wierszy w każdym obszarze roboczym bez żadnych dodatkowych możliwości. Wybór recenzentów nigdy nie analizuje diffu pod kątem języka ani domeny.

Węzły recenzji: ustalenia jako dane, nie tekst

Ustalenie zgłoszone przez add_review_node staje się węzłem recenzji w PR-zie — to właśnie renderuje karta Recenzja, z tego obliczany jest werdykt, a „Opublikuj na GitHubie” zamienia je w komentarz w linii. Recenzent, który zwraca tylko tekst, daje uruchomienie potoku wyglądające na udane i pustą powierzchnię recenzji; to zgłaszanie jest tu elementem nośnym.

Każdy węzeł zawiera:

Pole	Wartości
Rodzaj	bug, suggestion, recommendation, question, ticket
Priorytet	P0 (krytyczny) → P3 (drobiazg)
Trójka segregacji	kategoria (security, stability, …), waga, nakład
Kotwica	Ścieżka pliku, początek i koniec wiersza
Propozycja poprawki	Sugerowane wiersze zamienne, opcjonalny diff, opcjonalny prompt poprawki
Pewność	Ocena w przedziale [0, 1]
Uzasadnienie	Analiza, zapisana przed ustaleniem

Dwa szczegóły są celowe. Sugestia GitHub jednym kliknięciem jest oferowana tylko wtedy, gdy recenzent podał dokładne wiersze zamienne — wywnioskowanie ich z ujednoliconego diffu po cichu się myli, a zatwierdzenie błędnego wniosku jednym kliknięciem jest gorsze niż brak przycisku. A schemat add_review_node przedstawia reasoning przed ustaleniem, więc model, który wypełnia obiekt w kolejności schematu, najpierw zapisuje analizę. To pole jest opcjonalne: jego pominięcie nie odrzuca węzła. Węzeł o niepoprawnie zbudowanym ładunku znika, zamiast zanieczyszczać recenzję.

Konsensus recenzentów

Węzeł przechodzi przez open → consensus-ready → resolved lub dismissed. Środkowy krok to serce modelu: ustalenie awansuje dopiero wtedy, gdy potwierdzi je inny recenzent, a agent nigdy nie może potwierdzić własnego ustalenia. Narzędzie MCP publish_review_to_github i domyślne zachowanie RPC nadal publikują wyłącznie ustalenia potwierdzone przez innych recenzentów. Przycisk Opublikuj na GitHubie na karcie Recenzja wysyła natomiast każde pozostałe otwarte ustalenie.

Reguła jest wymuszana w trzech niezależnych miejscach — w narzędziu potwierdzania, w finalizatorze i w module publikującym — więc przetrwa błąd w wywołującym w dowolnym z nich. Zmiany statusu przechodzą przez jedną usługę, i to sprawia, że status coś znaczy: wcześniej dwie niepełne ścieżki mogły się nie zgadzać co do tego, czy to samo ustalenie zostało rozwiązane.

Gdy recenzenci się nie zgadzają — ten sam plik i wiersz, priorytety różniące się o dwa poziomy lub więcej, albo jeden nazywa coś bug, a drugi suggestion — niezgodność jest pokazywana nad listą ustaleń. To tam opinie recenzentów się rozchodzą i tam osąd człowieka jest najcenniejszy.

Odrzucenie ustalenia zapisuje też miękki fakt wyciszający w domenie pamięci, przy niskiej pewności — jedno odrzucenie to preferencja, a nie reguła.

Kohorty: wokół czego grupuje się recenzja

Przebieg obliczeniowy recenzji grupuje zmienione pliki PR-a w kohorty wyprowadzone z grafu kodu: zmienione pliki mapują się na dotykane symbole, symbole na połączone komponenty, a kohorty są uszeregowane według zasięgu zmian. Kohorta zawiera prowadzoną kolejność czytania, diagramy i spostrzeżenia, a nie jest płaską listą plików.

Nadają temu kształt dwie zasady uczciwości. Klucze kohort wywodzą się z treści i są stabilne między wypchnięciami, więc ustalenia i postęp recenzji przetrwają rebase czy force-push, zamiast zostać osierocone. A gdy repozytorium nie ma indeksu kodu, grupowanie cofa się do zwykłych ścieżek i mówi o tym wprost — mechanizm zastępczy nigdy nie udaje semantycznej pewności.

Osie recenzji i bramki

Obok ustaleń recenzentów recenzja gromadzi wyniki osi: sześć osi dwojakiego rodzaju.

Oś	Rodzaj	Źródło
correctness, security	Sterowana tokenami	Własne ustalenia recenzentów
testGap	Sterowana tokenami	Ustalenia recenzentów
visual, apiContract	Deterministyczna	Obliczane bez zużywania tokenów
performance	Deterministyczna	Tylko enumeracja — nic w produkcie nie oblicza wyniku

Werdykt osi to pass, warn, fail, partial lub unavailable — a bramkę przechodzi tylko pass lub warn. Rozróżnienie między fail, partial i unavailable jest nośne: oś objęta bramką, która nie mogła się dokończyć albo nie mogła w ogóle wystartować, wstrzymuje ogólny werdykt, zamiast go przepuścić. Brak dowodów nigdy nie zamienia się w zieloną bramkę.

Niektóre osie są celowo doradcze. Oś luki testowej wyprowadzana z kohort nie widzi pokrycia wstrzykiwania zależności ani fabryk — niezaindeksowane repozytorium z dokładnym zestawem testów i takie bez żadnych testów wyglądają z tego miejsca identycznie, więc twierdzenie czegokolwiek byłoby kłamstwem; pojawia się na pulpicie, ale nie stanowi bramki. Osie tokenowe są doradcze, bo priorytety ustaleń już kierują werdyktem, a ponowne opieranie bramki na nich liczyłoby to samo dwa razy.

Werdykt

Finalizator oblicza werdykt na podstawie ustaleń o statusie open lub consensus-ready:

• dowolne ustalenie P0 z pewnością ≥ 0,7 → Block
• w przeciwnym razie dowolne P0 (o niskiej pewności) lub dowolne P1 → Hold
• w przeciwnym razie → Ship

Werdykt niesie zagregowaną pewność wyprowadzoną z rozrzutu pewności składowych — zgodność ją podnosi, rozbieżność obniża.

Scalenie przez agenta prowadzącego (CEO) to przebieg redakcyjny, a nie ponowne wypisanie: ręcznie napisana druga kopia ustaleń to dokładnie to, co się rozjeżdża z oryginałem. Zduplikowane ustalenia są degradowane, a nie powtarzane — kilku recenzentów kieruje się na jeden diff z celowo nakładającymi się zakresami, więc ten sam defekt docierający do finalizatora trzy razy to system działający poprawnie; opublikowanie go trzy razy to system wyciekający własną architekturą do skrzynki odbiorcy. Przy ponownej recenzji ustalenia dostają odcisk i są zestawiane z poprzednią rundą, więc na wierzch wychodzi właśnie różnica.

Na koniec dołączają osie i mogą wyłącznie zaostrzyć werdykt: oś objęta bramką, która zawodzi, wymusza Block — nie da się jej przegłosować ustaleniami — a oś objęta bramką, która nie mogła się dokończyć, wymusza co najmniej Hold.

Publikowanie zostaje po Twojej stronie

Potok celowo nie zamieszcza niczego na GitHubie; publikowanie jest uzależnione od użytkownika, więc recenzja nigdy nie opublikuje się dwa razy. Gdy naciśniesz Opublikuj na GitHubie:

• Przesyłana jest jedna recenzja GitHub. Ustalenia już rozwiązane lub odrzucone są pomijane. Przycisk publikuje każde pozostałe otwarte ustalenie (selection: all_open). Narzędzie MCP publish_review_to_github nadal domyślnie ogranicza się do ustaleń potwierdzonych przez innych recenzentów (consensus).
• Ustalenia zakotwiczone w pliku i wierszu stają się komentarzami w linii; wszystko inne trafia do treści podsumowania, a każde niesie stopkę „— Control Center AI review”, żeby źródło było jednoznaczne.
• Kotwice są ponownie weryfikowane wobec bieżącego diffu PR-a w momencie publikowania. Komentarz do kodu, który został już przepisany, to najbardziej niszcząca zaufanie rzecz, jaką recenzent może zostawić; jeśli GitHub i tak odrzuci kotwicę w linii, cała recenzja jest wysyłana ponownie, a każde ustalenie trafia do treści, żeby nic nie zniknęło po cichu.
• Werdykt Block jest przesyłany jako REQUEST_CHANGES; Hold jako COMMENT; Ship jako APPROVE z przycisku (approve_on_ship: true). Narzędzie MCP zostawia Ship jako COMMENT, chyba że przekażesz approve_on_ship.
• Recenzja jest zamieszczana pod tożsamością aplikacji serwera. Kto nacisnął Opublikuj, jest zapisywane na potrzeby bramki roli i dziennika audytu; nie jest to autor z GitHuba.

Publikowanie deklaruje klasę akcji prPublish, więc punkt kontrolny guardraili traktuje je jak każdą akcję zmieniającą stan — domyślnie pyta o zgodę, a gdy nie jest podłączony żaden zatwierdzający, odmawia działania. Zobacz Guardraile.

Co recenzent może robić

Agenci-recenzenci działają w trybie review: to sandbox tylko do odczytu i wyselekcjonowana lista dozwolonych narzędzi obejmująca ustalenia, komentarze, zgłoszenia i wzajemne recenzowanie — ale żadnych zmian. Recenzent nie może naprawić kodu, który krytykuje; może dołączyć sugerowaną poprawkę, którą zastosuje człowiek. Komunikat odmowy tego trybu mówi agentowi, który i tak próbuje działać, żeby sfinalizował recenzję i pozwolił użytkownikowi zadziałać na podstawie opublikowanego podsumowania.

Powiązane koncepcje

• Guardraile — silnik zasad, który stanowi bramkę dla publikowania
• Tryby — co tryb review zmienia dla agenta
• Potoki i automatyzacja — silnik, na którym działa recenzja
• Cykl życia wysyłania agentów — skąd bierze się izolowany worktree

Powiązane poradniki

• Używaj recenzji opartej na AI — przeprowadź recenzję i opublikuj ją
• Wyślij agentów-recenzentów — sam wybierz recenzentów
• Obliczenia recenzji — kohorty, osie i diffy