Przejdź do głównej zawartości

Polityka automatyzacji review pull requestów to zestaw reguł całej organizacji, który określa, co agenty review mogą robić z pull requestem: które checki deterministyczne są rozstrzygające, do którego toru ryzyka trafia zmiana, kiedy znalezisko AI blokuje merge, kto akceptuje i co oznacza awaria reviewera. Reguła nadrzędna: żaden pull request nie trafia do brancha na podstawie samej opinii AI.

Po kwartale eksperymentów w twojej organizacji działają trzy boty do review. Zespół platformowy włączył Claude Code Review, zespół webowy Bugbota, a ktoś dodał @codex review w kilku repozytoriach. Jeden pull request zbiera 41 komentarzy, których nikt nie czyta. Inny trafia do brancha po tym, jak bot napisał „no issues found”, a zawierał migrację, której nie obejrzał żaden człowiek. Wtedy lider bezpieczeństwa pyta, który z tych botów może cokolwiek zaakceptować, i nikt nie zna odpowiedzi.

Ta strona jest dla CTO lub VP Engineering, który za tę odpowiedź odpowiada, oraz dla tech leadów, którzy ją egzekwują. Opisuje wyłącznie politykę. Konfigurację poszczególnych agentów review znajdziesz w warstwowym review pull requestów, porównanie botów w zestawieniu botów do AI code review, a codzienną obsługę kolejki w kolejce code review.

Q9 · Bramki jakości Dowód na maksymalny wynik: checki deterministyczne, skupione review specyfikacji i ryzyka, odtwarzalne ustalenia, routing według ryzyka oraz nazwana ludzka bramka merge.

  • Jednostronicowy szablon review-policy.md, który przyjmujesz bez zmian i dostosowujesz per repozytorium.
  • Tabelę torów ryzyka, która mówi każdemu repozytorium, jakich dowodów, jakich reviewerów i jakiego akceptującego wymaga zmiana.
  • Egzekwowanie w forge’u (wymagane checki i code ownerzy), dzięki czemu polityka działa także wtedy, gdy bot leży.
  • Definicje sześciu metryk, które pokazują, czy każdy reviewer AI jest wart swojego kosztu.
  • Prompty do wklejenia, które inwentaryzują obecne boty review i audytują zmergowane pull requesty względem polityki.

Dlaczego automatyzacja review potrzebuje polityki, a nie kolejnych botów

Dział zatytułowany „Dlaczego automatyzacja review potrzebuje polityki, a nie kolejnych botów”

Agenty zwiększają liczbę i rozmiar pull requestów szybciej, niż rośnie przepustowość review. Raport Faros AI „AI Engineering Report 2026” (kwiecień 2026; telemetria 22 000 deweloperów z platformy Faros, czyli próba złożona z jej własnych klientów) zmierzył wzrost rozmiaru pull requestów o 51% i liczby pull requestów zmergowanych na dewelopera o 16,2%, a jednocześnie wzrost mediany czasu w review o 441,5%, liczby pull requestów zmergowanych bez żadnego review o 31,3% i liczby incydentów na pull request o 242,7%.

Samo dokładanie reviewerów tego nie naprawia. Każdy bot dodaje komentarze, a komentarz nie jest dowodem. Bez spisanej polityki zespoły dryfują do jednego z dwóch stanów awarii: akceptują bez czytania, bo kolejka jest za długa, albo traktują milczenie bota jak akceptację. Polityka istnieje, żeby zatrzymać oba. Mówi, które sygnały są faktami, które są opiniami wymagającymi dowodu i która osoba bierze na siebie decyzję.

Rozstrzygnij tych osiem decyzji raz, na poziomie organizacji. Repozytorium może zaostrzyć regułę; nie łagodzi jej bez zarejestrowanego wyjątku.

DecyzjaZalecane ustawienie domyślneWłaściciel
Checki rozstrzygająceFormatowanie, typy, lint, testy jednostkowe i integracyjne, audyt zależności, skan sekretów. Pass/fail, wymagane w forge’u.Zespół platformowy
Tory ryzykaTrzy tory przypisywane według zmienionych ścieżek, nigdy według etykiety nadanej przez autora.CTO razem z bezpieczeństwem
Reviewerzy AI na torNajwyżej jeden reviewer ogólny plus jeden przebieg bezpieczeństwa w torze wrażliwym. Drugi tylko wtedy, gdy uzasadnią to metryki.Tech leadzi
Co może zablokować znalezisko AITylko znalezisko z reprodukcją, padającym testem lub cytowaną klauzulą polityki. Wszystko inne jest doradcze.Tech leadzi
Uprawnienie do akceptacjiTory 1 i 2 akceptuje nazwany człowiek. Akceptacja maszynowa, jeśli w ogóle, tylko w torze 0.CTO
Awaria revieweraReviewer, który zwraca błąd, przekracza czas lub nie jest skonfigurowany, raportuje „dowody niekompletne”. Nigdy nie liczy się jako pass.Zespół platformowy
Granice danychKtóre repozytoria mogą wysyłać kod do którego dostawcy review i na jakich warunkach retencji.Bezpieczeństwo i dział prawny
Pomiar i przeglądSześć metryk opisanych niżej, przeglądanych co miesiąc; reviewer poniżej progu precyzji przez dwa miesiące jest strojony albo usuwany.Kierownictwo inżynierii

Tor decyduje, ile dowodów potrzebuje zmiana, zanim człowiek może ją zaakceptować. Klasyfikuj według zmienionych ścieżek przez CODEOWNERS, żeby zmiana nie mogła sama wybrać sobie toru.

TorCo zawieraDowody automatyczneBramka ludzkaAkceptacja maszynowa
0 · Niskie ryzykoDokumentacja, zmiany tylko w testach, pliki generowane objęte checkiem generatoraChecki rozstrzygająceDowolny członek zespołu albo nikt, jeśli polityka na to pozwalaOpcjonalna
1 · StandardKod aplikacji poza torem 2Checki rozstrzygające, jedno review AI względem spec.md i diffuJeden akceptujący z zespołu-właścicielaNie
2 · WrażliwyUwierzytelnianie, autoryzacja, płatności, dane osobowe, migracje, kontrakty publicznego API, infrastruktura, workflowy CI, konfiguracja agentów (CLAUDE.md, AGENTS.md, .claude/, .codex/, .cursor/, konfiguracja MCP) oraz pliki zarządzające review (CODEOWNERS, REVIEW.md, plik polityki)Dowody toru 1, przebieg review bezpieczeństwa i notatka o wycofaniu w PRCode owner danego systemu, z imienia i nazwiskaNie

Konfiguracja agentów trafia do toru 2 celowo. Zmiana w AGENTS.md, hooku albo wpisie serwera MCP zmienia zachowanie każdego późniejszego uruchomienia agenta, także samych agentów review, więc wymaga tej samej uwagi co workflow CI. Zagnieżdżone pliki instrukcji to także konfiguracja agentów: Claude Code wczytuje CLAUDE.md z podkatalogów, a Codex czyta AGENTS.md osobno dla każdego katalogu, więc src/payments/AGENTS.md steruje review kodu płatności. Reguły dla zmian w hookach opisuje zarządzanie wspólnymi hookami.

Pliki zarządzające review trafiają do toru 2 z tego samego powodu. CODEOWNERS wyznacza każdy tor, REVIEW.md mówi agentom review, czego szukać, a plik polityki ustala reguły, które oba muszą spełniać. Gdyby zostały pod linią catch-all, byłyby plikami toru 1, a jedna akceptacja z domyślnego zespołu wystarczyłaby, żeby przepisać same tory.

Skopiuj ten plik do centralnego repozytorium (na przykład podręcznika inżynierii) i podlinkuj go z REVIEW.md każdego repozytorium. REVIEW.md w repozytorium wdraża politykę dla jego agentów review; ten plik określa, co musi spełnić. Szablon zostawiamy po angielsku, bo w takiej formie czytają go agenty i zespoły międzynarodowe.

review-policy.md
# Pull request review policy (version 1.0, owner: VP Engineering)
## 1. Authoritative checks
Formatting, type check, lint, unit and integration tests, dependency audit and
secret scan run on every pull request and are required status checks on the
default branch. Their result is fact. No reviewer, human or AI, overrides a
failing check; the check is fixed or the policy owner grants a written exception.
## 2. Risk lanes
Lane is set by changed paths through CODEOWNERS, never by the author.
- Lane 0: docs, test-only, generated files with a generator check.
- Lane 1: application code outside lane 2.
- Lane 2: auth, authorization, payments, personal data, migrations, public API
contracts, infrastructure, CI workflows, agent configuration (CLAUDE.md,
AGENTS.md, .claude/, .codex/, .cursor/, MCP config), review governance
(CODEOWNERS, REVIEW.md, this policy file).
A pull request touching several lanes takes the highest one.
## 3. AI review
- Lane 1: one AI review against spec.md (or the linked issue) and the diff.
- Lane 2: lane 1 plus one security review pass.
- A second general AI reviewer is added only after a 30-day trial shows it
finds confirmed defects the first one missed.
## 4. Blocking findings
An AI finding blocks merge only if it has a reproducer, a failing test, or a
cited clause of this policy. Other findings are advisory. The author resolves
each blocking finding with a commit or a written rejection the approver accepts.
## 5. Approval
- Lane 0: any team member. Machine approval: [allowed | not allowed].
- Lane 1: one approver from the owning team.
- Lane 2: the code owner for the affected system, by name. No machine approval.
The approver answers for intent, risk and evidence, not for having read every
line.
## 6. Reviewer failure
A review agent that errors, times out or is missing reports "evidence
incomplete". The pull request waits or the approver records why it proceeds.
Silence is never approval.
## 7. Data boundaries
Repositories on the restricted list do not send code to external review
services. Current list and approved vendors: [link].
## 8. Measurement
Monthly: finding precision, duplicate rate, escaped defects, time in review,
unreviewed merges, review cost per merged PR. A reviewer below 50% precision for
two consecutive months is retuned or removed.

Próg 50% precyzji to punkt wyjścia, a nie benchmark. Ustal go na podstawie własnych danych z trybu cienia (krok 4 niżej) i zapisz uzasadnienie.

Boty komentują, decyduje forge. Umieść władzę w ochronie brancha albo w rulesecie na branchu domyślnym, żeby działała, gdy bot leży, jest źle skonfigurowany albo zostaje wymieniony:

  • Ustaw checki rozstrzygające jako wymagane status checki.
  • Wymagaj review od code ownerów i wybierz jedno z dwóch ustawień akceptacji. Wymagana liczba akceptacji dotyczy całego brancha, a nie poszczególnych torów:
    • Opcja A: zero wymaganych akceptacji plus wymagane review code ownerów. Tor 0 trafia do brancha bez człowieka; tory 1 i 2 nadal wymagają swojego właściciela. Działa to tylko z układem CODEOWNERS pokazanym niżej, w którym każda ścieżka toru 1 ma domyślnego właściciela.
    • Opcja B: jedna wymagana akceptacja. Każdy tor, także tor 0, wymaga jednej akceptacji człowieka.
  • Przypisz ścieżki do torów w CODEOWNERS. Wygrywa ostatni pasujący wzorzec, a wzorzec bez właściciela zostawia swoje ścieżki bez właściciela. Dlatego linia catch-all daje torowi 1 domyślnego właściciela, linie bez właściciela pod nią wyłączają ścieżki toru 0, a linie toru 2 idą na końcu:
.github/CODEOWNERS
# Lane 1: every path defaults to the engineering team
* @acme/engineering
# Lane 0: no owner, so no code-owner review is required
/docs/
/tests/
# Lane 2: sensitive paths need the owning team's approval
/src/auth/ @acme/identity
/src/billing/ @acme/payments
/db/migrations/ @acme/data-platform
/infra/ @acme/platform
/.github/ @acme/platform
/REVIEW.md @acme/platform
/.claude/ @acme/platform
/.codex/ @acme/platform
/.mcp.json @acme/platform
# No leading slash: matches in every directory, after /docs/ and /tests/
CLAUDE.md @acme/platform
AGENTS.md @acme/platform
.cursor/ @acme/platform

/.github/ obejmuje workflowy i sam plik CODEOWNERS, więc pull request, który zmienia jedno albo drugie, potrzebuje zespołu platformowego, a nie dowolnego inżyniera. Trzy ostatnie linie nie zaczynają się od ukośnika, więc pasują do CLAUDE.md, AGENTS.md i .cursor/ w każdym katalogu. Stoją po /docs/ i /tests/, dlatego docs/AGENTS.md czy src/payments/CLAUDE.md nadal trafia do zespołu platformowego, zamiast spaść do toru 0 albo 1. GitHub stosuje CODEOWNERS z brancha bazowego pull requesta, więc zmiana tego pliku nie może zaakceptować sama siebie: zaczyna działać dopiero po akceptacji właściciela i merge’u. Trzymaj plik w .github/: GitHub szuka go najpierw tam, potem w katalogu głównym, potem w docs/ i używa pierwszego znalezionego. W centralnym repozytorium z review-policy.md daj temu plikowi właściciela z nazwy w ten sam sposób, na przykład /review-policy.md @acme/eng-leadership, i także tam wymagaj review code ownerów.

Zastąp @acme/... swoimi zespołami na GitHubie. Checki reviewerów AI zostaw w forge’u jako doradcze, dopóki nie zmierzysz ich precyzji. Check bota staje się wymagany dopiero wtedy, gdy polityka mówi, że jego znaleziska mogą blokować.

Jak Claude Code, Codex i Cursor wpisują się w politykę

Dział zatytułowany „Jak Claude Code, Codex i Cursor wpisują się w politykę”

Trzech dostawców najbardziej różni jedno pytanie: czy agent review może akceptować. Odpowiada na nie polityka, a nie ustawienie domyślne dostawcy. Kroki konfiguracji są w warstwowym review pull requestów i w zestawieniu botów do AI code review.

  • Zarządzane Code Review (research preview, plany Team i Enterprise) recenzuje każdy pull request na GitHubie kilkoma agentami, publikuje komentarze inline z oznaczeniem wagi i dodaje check run o nazwie Claude Code Review. Nigdy nie akceptuje ani nie blokuje, więc blokowanie wynika wyłącznie z twojej polityki i forge’a. Dokumentacja Anthropic podaje średni koszt 15–25 USD za review, rozliczany w kredytach użycia (sprawdzone 2026-09-26).
  • Na PR wywołujesz je przez @claude review albo @claude review always, żeby recenzowało też każdy kolejny push. Czyta CLAUDE.md oraz REVIEW.md w katalogu głównym repozytorium z regułami tylko dla review (lokalne /code-review nie czyta REVIEW.md); reguły torów wpisz do REVIEW.md.
  • Ani Code Review, ani claude ultrareview nie są dostępne dla organizacji z Zero Data Retention. Zapisz to w sekcji 7 polityki.
  • Check run zawsze kończy się jako neutralny, także gdy review się nie powiedzie albo przekroczy czas. Żeby egzekwować sekcję 6, dodaj mały wymagany job CI, który oblewa się z komunikatem „evidence incomplete”, gdy na head commicie brakuje check runu Claude Code Review albo raportuje on nieudane lub przerwane review. Tam, gdzie znaleziska mogą blokować, ten sam job czyta maszynowo czytelną linię wag, którą Code Review zapisuje na końcu szczegółów check runu. Miesięczny limit wydatków na usługę Claude Code Review ustawisz w claude.ai/admin-settings/usage (dokumentacja Code Review Anthropic, sprawdzone 2026-09-26).
  • Przebieg bezpieczeństwa dla toru 2 uruchomisz komendą /security-review w sesji przed otwarciem pull requesta albo GitHub Action anthropics/claude-code-security-review w CI.
  • Na każdym planie /code-review recenzuje diff lokalnie, a anthropics/claude-code-action@v1 uruchamia własne review w GitHub Actions. Uprawnienia i reguły triggerów opisuje AI w CI/CD.
  1. Zinwentaryzuj to, co działa dziś. Pierwszym promptem niżej wypisz każdego bota review, REVIEW.md, plik CODEOWNERS i wymagane checki w każdym repozytorium. Spodziewaj się botów włączonych przez pojedyncze osoby i branchy domyślnych bez wymaganych checków.
  2. Opublikuj wersję 1.0 polityki. Przyjmij szablon, uzupełnij decyzję o akceptacji maszynowej w torze 0, listę repozytoriów zastrzeżonych i właścicieli. Ogłoś, że polityka obejmuje pull requesty napisane przez agentów i przez ludzi na tych samych zasadach.
  3. Przypisz ścieżki do torów. Drugim promptem wygeneruj propozycję CODEOWNERS i poproś każdy zespół-właściciela o potwierdzenie swoich ścieżek. Niesklasyfikowane ścieżki domyślnie trafiają do toru 1.
  4. Uruchom reviewerów AI w trybie cienia na dwa do czterech tygodni. Komentują, ale nic, co piszą, nie blokuje. Oznacz każde znalezisko jako potwierdzone, odrzucone albo zduplikowane; to daje precyzję każdego reviewera.
  5. Włącz egzekwowanie. Ustaw checki rozstrzygające i review code ownerów jako wymagane. Znaleziska reviewera AI awansuj do blokujących tylko tam, gdzie jego precyzja z trybu cienia przekracza ustalony próg.
  6. Audytuj co miesiąc. Uruchom trzeci prompt na próbce zmergowanych pull requestów, przejrzyj sześć metryk i podbij wersję polityki przy każdej zmianie reguły.

Raportuj te metryki per reviewer i per tor. Podepnij je do swojego panelu metryk AI zamiast budować osobny dashboard; metryki dostarczania całej organizacji, obok których się pojawiają, definiują ramy metryk.

MetrykaDefinicjaCo mówi
Precyzja znaleziskZnaleziska potwierdzone (doprowadziły do zmiany albo uznano je za realne) ÷ wszystkie znaleziskaCzy ludzie w ogóle powinni czytać tego reviewera
Odsetek duplikatówZnaleziska już zgłoszone przez check lub innego reviewera ÷ wszystkie znaleziskaCzy drugi reviewer cokolwiek wnosi
Defekty, które uciekłyIncydenty lub zgłoszenia błędów powiązane ze zmergowanym PR, per tor, per miesiącCzy poprzeczka dowodów w torze jest dość wysoko
Czas w reviewMediana czasu od „ready for review” do merge’a oraz mediana czasu do pierwszego ludzkiego reviewCzy review jest wąskim gardłem
Merge’e bez reviewPR z torów 1 i 2 zmergowane bez ludzkiej akceptacji ÷ wszystkie merge’e z torów 1 i 2Czy polityka jest egzekwowana; cel to zero
Koszt review na zmergowany PRWydatki na review AI ÷ zmergowane PR, per repozytoriumCzy koszt rośnie razem z wartością

Nie licz komentarzy, pokrycia botami ani „PR zrecenzowanych przez AI”. Reviewer, który komentuje każdy pull request i ma rację w co trzecim przypadku, zabiera uwagę, której nie zwraca.

Uruchamiaj je w Claude Code, Codex albo agencie Cursora z uwierzytelnionym CLI gh. Każdy z nich tylko czyta albo zapisuje wyłącznie do nowego brancha.

Skąd wiesz, że polityka działa, bez czytania każdego diffu?

Dział zatytułowany „Skąd wiesz, że polityka działa, bez czytania każdego diffu?”

Akceptujący ocenia dowody, a nie linie. Dla każdego pull requesta polityka gwarantuje stały zestaw dowodów: checki rozstrzygające przeszły, tor jest znany ze ścieżek, blokujące znaleziska mają reprodukcję albo padający test, a opis PR zapisuje zamiar, dotknięte systemy i dane, odwracalność oraz otwarte ryzyka (ten zapis definiuje pakiet dowodów). Akceptujący sprawdza, czy dowody pokrywają zachowanie o najwyższym ryzyku; jeśli nie, zwraca pull request. Sześciokrokową procedurę tej oceny opisuje code review PR-a agenta.

Na poziomie organizacji trzy sygnały dowodzą, że polityka obowiązuje: merge’e bez review w torach 1 i 2 pozostają na zerze, comiesięczny audyt nie znajduje cichych passów, a liczba defektów, które uciekły, w każdym torze nie rośnie razem z wolumenem. Gdy rośnie, podnieś poprzeczkę dowodów w tym torze, zanim dołożysz kolejnego bota. Przejście zespołu od czytania każdego diffu do oceniania dowodów opisuje strona jak pomóc zespołowi przestać czytać każdy diff.

Co się psuje, gdy organizacja automatyzuje review PR?

Dział zatytułowany „Co się psuje, gdy organizacja automatyzuje review PR?”

Przed tą stroną umieść review na pełnej mapie kontroli dzięki stronie governance i autonomia. Po niej skonfiguruj agentów review i uruchom pętlę po stronie serwera.