System AI code review z wielu agentów — w samym Markdownie

Recenzja kodu to jedna z najważniejszych — i najbardziej czasochłonnych części każdego procesu developerskiego. Narzędzia AI mogą pomóc, ale pojedyncze polecenie "przerecenzuj ten kod" prawie zawsze generuje szum: fałszywe alarmy, uwagi o stylu, mgliste sugestie, które marnują więcej czasu, niż oszczędzają.

Postanowiłem podejść do tego inaczej. Zamiast jednego uniwersalnego promptu, zbudowałem system wieloagentowy z wykorzystaniem Claude Code i architektury fan-out/fan-in. Dziewięciu wyspecjalizowanych agentów analizuje ten sam merge request równolegle, każdy przez inny pryzmat. Całość działa jako pojedyncza komenda slash (/codereview).

Oto, jak to działa od podszewki.

Architektura: fan-out / fan-in

Cały system to ~2 900 linii plików Markdown z instrukcjami. Żadnego Pythona, Node.js, ani kroku budowania — tylko prompt engineering. Jedna komenda (/codereview) uruchamia Orkiestrator, który rozsyła zadania do dziewięciu agentów, a potem scala wyniki w strukturalny raport. Krok | Komponent | Rola | |------|-------------------|----------------------------------------------------------------------| | 1 | /codereview | Punkt wejścia — uruchamia cały pipeline | | 2 | Orkiestrator | Pobiera diff, rozsyła pliki, uruchamia wszystkie agenty równolegle | | 3 | 9 Agentów | Każdy analizuje MR przez własny filtr, jednocześnie | | 4 | Orkiestrator | Zbiera wyniki, usuwa duplikaty, filtruje, rozwiązuje konflikty | | 5 | Raport MR | Strukturalny komentarz dodawany z powrotem do merge request |

Orkiestrator — koordynacja, nie recenzja

Orkiestrator nie recenzuje kodu samodzielnie. Jego zadaniem jest zarządzanie procesem:

Zbieranie kontekstu — pobiera diff i pełne treści wszystkich zmienionych plików w merge request.
Routing plików — kieruje pliki do odpowiednich agentów. Plik .tsx trafia jednocześnie do agentów React i TypeScript. Plik .module.css — tylko do agenta Stylów.
Agregacja — zbiera wyniki od wszystkich dziewięciu agentów i scala je w jeden raport.
Filtrowanie — tutaj dzieje się prawdziwa magia. Dedyplikacja, rozwiązywanie konfliktów i usuwanie niskiej jakości znalezisk, zanim dotrą do developera.

Dziewięć wyspecjalizowanych agentów

Specjalizacja to klucz. Wąski agent jest dokładniejszy niż generalista, bo nie musi myśleć o wszystkim naraz.

Zrobiłem też świadomy wybór dotyczący modeli — nie każdy agent potrzebuje najpotężniejszego modelu: | Agent | Model | Obszar działania | |---------------------------|---------|-------------------------------------------------------| | Agent React | Sonnet | Architektura komponentów, anty-wzorce w hookach, zarządzanie stanem | | Standardy TypeScript | Haiku | Bezpieczeństwo typów, konwencje nazewnictwa, wzorce importów | | Agent Bezpieczeństwa | Sonnet | Wektory XSS, twarde zakodowane sekrety, niebezpieczne URL-e i iframy | | Algorytmy i Wydajność | Sonnet | Złożoność O(n²), wycieki pamięci, niepotrzebne re-rendery | | Ponowne użycie kodu | Sonnet | Wykrywa powtarzaną logikę, która już istnieje w współdzielonych utilach | | Style i CSS | Haiku | Design tokens, semantyczny HTML, dostępność (ARIA, teksty alternatywne) | | Agent Storybook | Haiku | Pokrycie wariantów, typowanie story, rejestracja komponentów | | System UX/UI | Sonnet | Hierarchia atomic design, linki do Figmy, pokrycie stanów interaktywnych |

Haiku sprawdza się w dopasowywaniu wzorców — szybki, tani, wystarczająco dokładny. Sonnet radzi sobie z analizą wymagającą rozumowania — wolniejszy, ale z prawdziwą głębią.

Sekret użyteczności: Bramy jakości (Quality Gates)

Największy problem z AI code review to szum. Deweloperzy przestają ufać narzędziu, gdy zaczyna zgłaszać brakujące spacje lub sugerować "można by zrefaktorować". Dlatego zbudowałem surową politykę Zero-Nitpicks.

Zanim jakiekolwiek znalezisko trafi do komentarza w MR, musi przejść przez trzy bramy:

Sprawdzenie istnienia — Orkiestrator weryfikuje, czy kod zasygnalizowany przez agenta rzeczywiście istnieje w diffie. Agenci mogą "halucynować" zmiany, których nikt nie dotykał.
Twardy dowód — każde znalezisko musi zawierać dokładny cytat (1–3 linie) z zmienionego kodu. Bez dowodu — nie ma znaleziska.
Filtr językowy — znaleziska zawierające niepewne sformułowania ("może", "potencjalnie", "rozważ") lub czysto stylistyczne sugestie są automatycznie odrzucane.

System ma też hierarchię dedyplikacji. Jeśli Agent React i Agent Bezpieczeństwa zgłoszą ten sam problem, wygrywa Bezpieczeństwo. Istnieje zdefiniowany łańcuch priorytetów, aby konflikty były rozwiązywane deterministycznie, a nie losowo.

Odporność i telemetria

System został zaprojektowany defensywnie. Jeśli jeden agent zawiedzie, pozostałe osiem kontynuuje pracę. Orkiestrator zawsze dostarcza częściowe wyniki — nigdy nie blokuje całej recenzji z powodu błędu jednego agenta.

Dodałem też telemetrię, która śledzi skuteczność każdego agenta w czasie. Dzięki temu wiem, które prompty wymagają dopracowania i gdzie system generuje najwięcej fałszywych alarmów.

Co było naprawdę trudne?

Jeśli miałbym wymienić dwie rzeczy, na które poświęciłem najwięcej czasu, to:

Dostrajanie Bram Jakości i poziomów powagi to był ciągły proces iteracyjny. Łatwo powiedzieć "odfiltruj szum" — trudno precyzyjnie zdefiniować, gdzie kończy się czepialstwo, a zaczyna realny problem. Zbyt restrykcyjne filtry pomijały ważne znaleziska. Zbyt luźne — wpuszczały szum z powrotem. Znalezienie równowagi zajęło wiele cykli testowych i ręcznej weryfikacji wyników.
Formatowanie końcowego raportu okazało się równie ważne jak dokładność samych znalezisk. Jeśli deweloper otrzymuje ścianę tekstu bez struktury, albo ją ignoruje, albo traci czas na jej analizę. Poświęciłem sporo czasu na to, by raport był łatwy do przeskanowania wzrokiem — co jest merge blockerem, co sugestią, do której linii się odnosi i dlaczego to ważne.

Dobry raport to taki, w którym deweloper wie w 10 sekund, co trzeba poprawić przed merge’em.

Czego się nauczyłem

Architektura — fan-out/fan-in, hierarchia modeli, wyspecjalizowani agenci — okazała się łatwiejsza, niż myślałem. Trudniejsze było odpowiedzenie na inne pytanie:

Czego deweloper naprawdę chce zobaczyć?

Technicznie poprawne ≠ praktycznie użyteczne. Budowa tego systemu nauczyła mnie, by traktować wyjście (output) równie poważnie, jak logikę, która je generuje.

Jeśli budujesz coś podobnego — poświęć co najmniej tyle samo czasu na warstwę filtrowania, co na same agenty. System jest tylko tak dobry, jak to, czego decyduje się nie powiedzieć.