KI-Review

Aufbau eines Reviews

Ein KI-Review ist ein Lauf der mitgelieferten Pipeline pr_review über einen offenen Pull Request. Die Pipeline öffnet den Review-Bereich des Pull Requests und schickt Reviewer-Agenten los. Die lesen den Diff im isolierten Checkout dieses Bereichs, und jeder erfasst seine Befunde als strukturierte Review-Knoten. Ein Lead-Agent fasst sie zu einem Walkthrough zusammen, ein Finalizer berechnet ein Verdikt: Ship, Hold oder Block. Veröffentlichen tut die Pipeline nicht. Das Posten nach GitHub ist ein eigener, bewusster Schritt eines Menschen.

Der Rest dieser Seite erklärt die Teile und warum sie so gebaut sind.

Ein Review-Bereich pro Pull Request

Der Review-Kontext eines Pull Requests ist ein Bereich für Nachrichten, Modus review, Art pr. Eine Zuordnung des Review-Bereichs verbindet ihn mit dem Pull Request. Angelegt wird er idempotent. Die PR-Seite, die Review-Pipeline und die Chat-Oberflächen lösen alle denselben einen Bereich dahinter über denselben Codepfad auf. Eine Vorlage, die den Pull Request prüft, und ein Mensch, der ihn öffnet, landen so nie in zwei Bereichen mit zwei verschiedenen Checkouts.

Der isolierte Worktree des Bereichs hat den Pull Request an seinem Head-Ref ausgecheckt. Ein Bereich bedeutet auch einen Checkout. Alle Reviewer arbeiten in demselben Bereich, keiner bekommt einen eigenen Klon des Arbeitsbereichs.

Jeder Reviewer schreibt in diesem einen Bereich in einen eigenen benannten Stream. Befunde sind Nachrichten review_node, kein Fließtext. Der Zusammenzug über den ganzen Bereich am Ende ist Absicht. Ein Verdikt nur aus den Befunden eines Threads wäre still ein Verdikt über einen einzelnen Reviewer.

Die Zuordnung trägt eine Statusleiter: requested → in progress → awaiting approval → completed. Sie entscheidet, ob Auf GitHub veröffentlichen auf dem Tab Review des Pull Requests freigegeben ist.

Review-Stufen

Wie tief ein Review geht, ist eine Richtlinie des Arbeitsbereichs mit drei Stufen. Eingestellt wird sie unter Einstellungen → Arbeitsbereich → Allgemein, auf der Karte Arbeitsbereichs-Richtlinien:

Stufe	Reviewer, die starten	Meldung
`light`	nur Engineer	nur das, was wirklich zählt
`balanced`	Engineer, QA, architect (der Standard)	der übliche Durchgang
`thorough`	alle fünf, einschließlich Sicherheit und Performance	nichts wird zurückgestuft

Die Stufe bewegt zwei Regler zugleich. Welche Reviewer losgeschickt werden, erzwingen die Zustands-Gates runWhen in der Pipeline-Vorlage, nicht der Wortlaut des Prompts. Den Wortlaut kann ein Modell ignorieren, ein Gate nicht. Der zweite Regler bestimmt, wo Befunde unter der Schwelle erscheinen. Keiner der beiden löscht einen Befund. Eine Stufe, die weniger meldet, erfasst trotzdem genauso viel und gruppiert den Rest.

Die Durchgänge für Sicherheit und Performance verwenden die mitgelieferten Agenten architect und engineer weiter, statt neue einzuführen. Die Spezialisierung ist der Auftrag, mit dem der Reviewer gestartet wird, nicht ein eigener Agent pro Achse. Ein eigener Agent pro Achse brächte in jedem Arbeitsbereich fünf Zeilen mehr und keine zusätzliche Fähigkeit. Die Auswahl der Reviewer sieht sich den Diff nie auf Sprache oder Domäne an.

Review-Knoten: Befunde als Daten, nicht als Fließtext

Ein mit add_review_node erfasster Befund wird auf dem Pull Request zu einem Review-Knoten. Den zeigt der Tab Review, daraus wird das Verdikt berechnet, und daraus macht „Auf GitHub veröffentlichen“ einen Inline-Kommentar. Ein Reviewer, der nur Fließtext zurückgibt, erzeugt einen Pipeline-Lauf, der erfolgreich aussieht, und eine leere Review-Oberfläche. Tragend ist das Erfassen.

Jeder Knoten trägt:

Feld	Werte
Art	`bug`, `suggestion`, `recommendation`, `question`, `ticket`
Priorität	P0 (kritisch) → P3 (Kleinigkeit)
Triage-Tripel	Kategorie (`security`, `stability`, …), Schweregrad, Aufwand
Anker	Dateipfad, Zeilenanfang und Zeilenende
Mitgeführte Korrektur	vorgeschlagene Ersatzzeilen, ein optionaler Diff, ein optionaler Fix-Prompt
Konfidenz	ein Wert in [0, 1]
Begründung	die Analyse, geschrieben vor dem Befund

Zwei Details sind Absicht. Ein GitHub-Vorschlag per Klick erscheint nur, wenn der Reviewer exakte Ersatzzeilen geliefert hat. Sie aus einem Unified Diff abzuleiten geht leise schief, und ein Commit per Klick auf eine falsche Ableitung ist schlimmer als gar keine Schaltfläche. Das Schema von add_review_node stellt reasoning vor den Befund, damit ein Modell, das das Objekt in der Reihenfolge des Schemas füllt, die Analyse zuerst schreibt. Das Feld ist optional. Es wegzulassen lehnt den Knoten nicht ab. Ein Knoten mit fehlerhafter Nutzlast verschwindet, statt das Review zu verunreinigen.

Peer-Konsens

Ein Knoten durchläuft open → consensus-ready → resolved oder dismissed. Der mittlere Schritt ist der Kern des Modells: Ein Befund wird erst konsensreif, wenn ein Peer-Reviewer ihn bestätigt, und ein Agent kann den eigenen Befund nie bestätigen. Das MCP-Tool publish_review_to_github und der RPC-Standard veröffentlichen weiterhin nur von einem Peer bestätigte Befunde. Die Schaltfläche Auf GitHub veröffentlichen auf dem Tab Review sendet dagegen jeden verbleibenden offenen Befund.

Die Regel wird an drei unabhängigen Stellen erzwungen, im Bestätigungs-Tool, im Finalizer und beim Veröffentlichen. Sie bleibt also stehen, auch wenn der Aufrufer an einer der drei Stellen fehlerhaft ist. Jeder Statuswechsel läuft über einen Dienst. Genau das gibt einem Status eine Bedeutung. Vorher konnten sich zwei halbe Pfade widersprechen, ob derselbe Befund erledigt war.

Wenn sich Reviewer widersprechen, gleiche Datei und Zeile, Prioritäten um mindestens zwei Stufen auseinander, oder einer sagt bug und der andere suggestion, erscheint der Widerspruch über der Befundliste. Dort laufen die Einschätzungen auseinander, und das Urteil eines Menschen ist am meisten wert.

Einen Befund abzulehnen schreibt außerdem, mit niedriger Konfidenz, ein weiches Unterdrückungsfaktum in die Gedächtnis-Domäne. Eine Ablehnung ist eine Präferenz, keine Regel.

Kohorten: wonach sich das Review gruppiert

Der Durchgang von Review-Compute gruppiert die geänderten Dateien eines Pull Requests in Kohorten aus dem Code-Graph. Geänderte Dateien werden den Symbolen zugeordnet, die sie berühren, Symbole den Zusammenhangskomponenten, und die Kohorten werden nach Wirkungsradius geordnet. Eine Kohorte trägt eine geführte Lesereihenfolge, Diagramme und Einsichten, keine flache Dateiliste.

Zwei Regeln der Ehrlichkeit geben dem die Form. Kohorten-Schlüssel stammen aus dem Inhalt und bleiben über Pushes stabil, sodass Befunde und der Review-Fortschritt einen Rebase oder Force-Push überstehen, statt zu verwaisen. Hat das Repo keinen Code-Index, fällt die Gruppierung auf bloße Pfade zurück und sagt das. Der Fallback täuscht nie semantische Konfidenz vor.

Review-Achsen und Gates

Neben den Befunden der Reviewer sammelt ein Review Achsen-Ergebnisse, sechs Achsen in zwei Arten.

Achse	Art	Herkunft
`correctness`, `security`	tokenbasiert	die eigenen Befunde der Reviewer
`testGap`	tokenbasiert	die Befunde der Reviewer
`visual`, `apiContract`	deterministisch	berechnet, ohne Tokens auszugeben
`performance`	deterministisch	nur das Enum. Im Produkt berechnet nichts ein Ergebnis

Das Achsen-Verdikt ist pass, warn, fail, partial oder unavailable, und nur pass oder warn besteht ein Gate. Der Unterschied zwischen fail, partial und unavailable ist tragend. Eine Achse mit Gate, die nicht zu Ende kam oder gar nicht laufen konnte, hält das Gesamtverdikt an, statt es durchzulassen. Fehlende Evidenz wird nie zu einem grünen Gate.

Manche Achsen sind absichtlich nur beratend. Die Testlücken-Achse aus den Kohorten sieht keine Abdeckung durch Dependency Injection oder Factories. Ein nicht indexiertes Repo mit gründlicher Testsuite und eines ganz ohne Tests sehen von dort identisch aus. Beides zu behaupten wäre eine Lüge. Die Achse erscheint im Dashboard und setzt kein Gate. Die Token-Achsen sind beratend, weil die Prioritäten der Befunde das Verdikt schon treiben. Ein weiteres Gate darauf würde doppelt zählen.

Das Verdikt

Der Finalizer berechnet das Verdikt über die Befunde im Status open oder consensus-ready:

jeder Befund P0 mit Konfidenz ≥ 0,7 → Block
sonst jedes P0 mit niedriger Konfidenz oder jedes P1 → Hold
sonst → Ship

Das Verdikt trägt eine aggregierte Konfidenz aus der Streuung der beitragenden Werte. Übereinstimmung hebt sie, Abweichung senkt sie.

Die Konsolidierung des Lead-Agenten (CEO) ist ein redaktioneller Durchgang, keine zweite Liste. Eine von Hand geschriebene Zweitfassung der Befunde ist genau das, was sich vom echten Stand entfernt. Doppelte Befunde werden zurückgestuft, nicht wiederholt. Mehrere Reviewer sind auf einen Diff angesetzt, mit absichtlich überlappenden Aufträgen. Erreicht derselbe Defekt den Finalizer dreimal, arbeitet das System. Ihn dreimal zu veröffentlichen schüttet die eigene Architektur in den Posteingang. Bei einem erneuten Review erhalten die Befunde einen Fingerabdruck und werden mit der vorigen Runde abgeglichen, sodass das Delta sichtbar wird.

Zum Schluss kommen die Achsen dazu. Sie können das Verdikt nur strenger machen. Eine Achse mit Gate, die fehlschlägt, erzwingt Block. Befunde können das nicht überstimmen. Eine Achse mit Gate, die nicht zu Ende kam, erzwingt mindestens Hold.

Das Veröffentlichen bleibt bei dir

Die Pipeline postet absichtlich nichts nach GitHub. Veröffentlichen ist an dich gebunden, damit ein Review nie doppelt erscheint. Wenn du Auf GitHub veröffentlichen drückst:

Es wird ein GitHub-Review eingereicht. Schon erledigte oder abgelehnte Befunde werden übersprungen. Die Schaltfläche veröffentlicht jeden verbleibenden offenen Befund (selection: all_open). Das MCP-Tool publish_review_to_github bleibt standardmäßig bei nur von einem Peer bestätigten Befunden (consensus).
Befunde mit Anker auf Datei und Zeile werden Inline-Kommentare. Alles andere wandert in den Text der Zusammenfassung, jeder mit der Fußzeile “— Control Center AI review”, damit die Quelle eindeutig ist.
Anker werden zum Veröffentlichungszeitpunkt erneut gegen den aktuellen Diff des Pull Requests geprüft. Ein Kommentar an Code, der schon umgeschrieben wurde, untergräbt Vertrauen am stärksten. Lehnt GitHub einen Inline-Anker trotzdem ab, wird das gesamte Review erneut gesendet und jeder Befund in den Text genommen, damit nichts stillschweigend verloren geht.
Ein Verdikt Block wird als REQUEST_CHANGES eingereicht, Hold als COMMENT und Ship als APPROVE von der Schaltfläche (approve_on_ship: true). Das MCP-Tool lässt Ship bei COMMENT, solange du nicht approve_on_ship übergibst.
Das Review wird unter der App-Identität des Servers gepostet. Wer Auf GitHub veröffentlichen gedrückt hat, wird für das Rollen-Gate und das Audit-Log festgehalten. Autor auf GitHub ist das nicht.

Das Veröffentlichen deklariert die Aktionsklasse prPublish. Der Engpass der Schutzregeln behandelt es deshalb wie jede verändernde Aktion. Standard ist eine Rückfrage, und ohne verbundene freigebende Person fällt es geschlossen aus. Siehe Schutzregeln.

Was ein Reviewer tun darf

Reviewer-Agenten laufen im Modus review: eine Nur-Lese-Sandbox und eine kuratierte Zulassungsliste von Tools für Befunde, Kommentare, Tickets und Peer-Review, ohne Mutationen. Ein Reviewer kann den kritisierten Code nicht selbst korrigieren. Er kann einen Korrekturvorschlag anhängen, den ein Mensch anwendet. Die Absage des Modus weist einen Agenten, der trotzdem handeln will, an, das Review abzuschließen und die veröffentlichte Zusammenfassung dem Nutzer zu überlassen.