Was macht Review?
Beurteile eine Änderung auf zwei getrennten Achsen – wurde das Richtige gebaut (Spezifikation) und ist es gut gebaut (Qualität) – mit frischem Blick, Erkenntnissen, die durch Beweise gestützt werden, und einem Schweregrad, der danach bemessen wird, was ein echter Nutzer erleben würde. Handle dann mit technischer Strenge, nicht aus Nachgiebigkeit.
Kernprinzip: Stimme einer Änderung zu, wenn sie die Codebasis eindeutig verbessert und das tut, was gefordert wurde – selbst wenn du es anders geschrieben hättest. Stimme niemals einer Änderung zu, die du nicht tatsächlich gelesen und geprüft hast.
Pipeline-Position: spec → plan → build (+ test) → review → merge.
Schritt 1: Den Geltungsbereich festlegen
- Der Benutzer benennt den Geltungsbereich (PR, Branch, Commit-Bereich, Dateien). Andernfalls: der aktuelle Branch gegen seine Merge-Basis mit dem Standard-Branch, plus unbestätigte Änderungen.
- Löse den Fixpunkt auf und bestätige, dass der Geltungsbereich nicht leer ist, bevor du etwas anderes tust:
git rev-parse <ref>,git log <ref>..HEAD --oneline,git diff <ref>...HEAD --statfür committete Arbeit undgit diff --cached --stat(gestaged),git diff --stat(unstaged) undgit status --short(ungetrackt) für unbestätigte Änderungen. Überprüfe die Vereinigung beider und teile, wenn unbestätigte Änderungen im Geltungsbereich sind, jedem Prüfer mit (der Prüfer-Prompt hat eine Zeile dafür). Ein ungültiger Ref oder ein Geltungsbereich, der in beiden Punkten leer ist, führt zum Abbruch. - Lies bei einem PR dessen Beschreibung und verlinkte Issues.
Schritt 2: Die Absicht erfassen
Finde in dieser Reihenfolge: die Spezifikation und den Plan, den die Änderung umsetzt (specs/<slug>/, Links in Commits/PR, ein vom Benutzer angegebener Pfad), die Ruling:-Zeilen des Build-Ledgers und das Issue, das sie schließt. Formuliere die Absicht in zwei oder drei Sätzen. Wenn es keine Spezifikation gibt, sage das: Die Spezifikationsachse beurteilt dann anhand der PR-Beschreibung und der berechtigten Erwartungen eines Benutzers.
Finde auch die Standards: CONTRIBUTING.md, CODING_STANDARDS.md, CLAUDE.md/AGENTS.md, Lint-Konfigurationen, ADRs, das Glossar.
Größenprüfung. ~100 geänderte Zeilen sind ideal, ~300 sind für eine logische Änderung in Ordnung, ~1000 sind zu groß, um sie gut zu überprüfen: Empfehle eine Aufteilung (Stack, nach Dateigruppen oder vertikale Schnitte) als Befund. Refactoring, das mit Feature-Arbeit vermischt ist, sind zwei Änderungen.
Schritt 3: Mit frischem Kontext überprüfen
Der Autor ist blind für seine eigenen Annahmen – und genauso die Sitzung, die den Code geschrieben hat. Wenn ein Subagenten-Tool verfügbar ist, setze Prüfer mit frischem Kontext ein, indem du reviewer-prompt.md verwendest: Gib ihnen das Diff (als Datei oder exakten Befehl), die Spezifikations-/Plan-Pfade, die Standard-Dateien und die Ledger-Entscheidungen. Niemals deine Sitzungshistorie. Prüfer sind schreibgeschützt und erstellen keine eigenen Prüfer.
Führe sie parallel aus, damit eine Achse die andere nicht überdecken kann:
- Spezifikationsprüfer: Fehlend, zusätzlich, missverstanden.
- Qualitätsprüfer: Korrektheit, Tests, Design, Sicherheit, Leistung.
- (Optional, bei riskanten oder umfangreichen Änderungen) Blastradius-Prüfer: Was diese Änderung bricht, wo grep nichts anzeigt.
Verwende das leistungsfähigste verfügbare Modell für eine Überprüfung des gesamten Branches. Ohne Subagenten-Tool führe jede Achse selbst als separaten Durchlauf durch und kennzeichne das Ergebnis als Selbstüberprüfung: Schwächer als ein frischer Prüfer, und der Benutzer entscheidet, ob das ausreicht.
Die direkte Überprüfung des eigenen gerade fertiggestellten Branches inline ist kein Ersatz für diesen Schritt.
Die Spezifikationsachse
Vergleiche das Diff mit dem, was gefordert wurde:
- Fehlend: Anforderungen oder Erfolgskriterien übersprungen, teilweise oder als implementiert behauptet, aber nicht umgesetzt. Zitiere die Spezifikationszeile.
- Zusätzlich: Verhalten, das niemand gefordert hat, spekulative Optionen, Hooks oder Abstraktionen (Scope-Creep, YAGNI).
- Missverstanden: Das richtige Feature auf die falsche Weise gebaut oder das falsche Problem gelöst.
- Aus dem Diff nicht überprüfbar: Anforderungen, die in unverändertem Code oder über mehrere Änderungen hinweg leben. Liste auf, was überprüft werden sollte, anstatt zu raten.
Die Spezifikation ist ein Vision-Dokument, keine erschöpfende Liste. Wo sie schweigt, ist die berechtigte Erwartung eines Benutzers die Anforderung. Schweigen zu einer Eingabe ist keine Erlaubnis für einen Absturz.
Die Qualitätsachse
Lies zuerst die Tests: Sie zeigen Absicht und Abdeckung.
Tests
- Hat jedes neue Verhalten einen Test, der fehlschlagen würde, wenn das Verhalten kaputt ginge? Beantworte durch Experiment, wo möglich: Drehe eine Bedingung, die die Änderung hinzufügt, und führe die Test-Suite aus, in einer wegwerfbaren Arbeitskopie, damit der überprüfte Checkout nie geändert wird. Eine Mutation, die grün bleibt, ist ein Befund: Nenne den fehlenden Test.
- Verhalten durch öffentliche Schnittstellen, nicht durch Interna; keine Assertions auf Mocks; keine erwarteten Werte, die vom getesteten Code berechnet werden; Mocks nur an Systemgrenzen.
- Fehlerbehebungen haben einen Regressionstest. Nichts ist übersprungen oder deaktiviert. Testausgabe ist sauber.
Korrektheit
- Entspricht der Spezifikation; Grenzfälle (null, leer, Null, maximal, Unicode, nebenläufig); Fehlerpfade, nicht nur der Happy Path; Off-by-one, Wettlaufsituationen, Zustände, die außer Synchron geraten können.
Lesbarkeit und Einfachheit
- Namen sagen, was Dinge sind und tun. Der Kontrollfluss ist einfach. Könnte dies weniger Zeilen sein? Verdient jede Abstraktion ihren Platz (keine Verallgemeinerung vor dem dritten Gebrauch)?
- Toter Code, No-Op-Variablen,
// removed-Kommentare, Kompatibilitäts-Shims, die niemand braucht. - Kommentare erklären warum, nicht was. Ein Kommentar, der einen Workaround beschreibt, markiert oft eine ungelöste Ursache.
Design
- Passt zu den bestehenden Mustern; ein neues Muster braucht einen Grund.
- Reduziert ein Refactoring die Konzepte, die ein Leser behalten muss, oder verschiebt es sie nur? Bevorzuge die Version, in der Branches, Modi oder Ebenen verschwinden.
- Feature-Logik, die in ein gemeinsames Modul ausläuft; ein Fast-Duplikat eines vorhandenen Helfers; eine Bedingung, die an einen nicht verwandten Ablauf angehängt wurde; wiederholte Switch-Anweisungen über dieselbe Struktur (ein fehlendes Modell oder ein fehlender Dispatcher); ein zweiter Boolean, der mit dem ersten synchron bleiben muss (eine fehlende Zustandsmaschine).
- Wrapper mit einem einzigen Aufrufer und Durchreiche-Ebenen (inline). Veränderlicher Zustand, der weiter ist als nötig.
- Validierung an den Grenzen, Vertrauen im Inneren. Keine stillen Fallbacks, die eine unklare Invariante überdecken; kein unnötiges
any/Casts. - Dateiwachstum: Eine Änderung, die eine Datei weit über eine gesunde Größe treibt, sollte zuerst zerlegt werden.
Sicherheit
- Nicht vertrauenswürdige Eingaben (HTTP, CLI, Dateien, Env, LLM-Ausgabe, Antworten Dritter) an der Grenze validiert. Abfragen parametrisiert. Ausgabe kodiert. Authentifizierung/Autorisierung geprüft, wo nötig. Geheimnisse außerhalb von Code, Logs und VCS. Neue Abhängigkeiten begründet, gewartet, lizenzkompatibel; Lockfile-Diff überprüft.
Leistung
- N+1-Abfragen, unbegrenzte Schleifen oder Abrufe, fehlende Paginierung, synchrone Arbeit, die blockiert, große Allokationen in heißen Pfaden, unnötige Neu-Renderings. Quantifiziere, wo du kannst („~50ms pro Zeile bei 1.000 Zeilen“).
Geruchs-Baseline (Ermessensentscheidungen; die dokumentierten Standards des Repos überschreiben): Geheimnisvoller Name, duplizierter Code, Feature Neid, Datenklumpen, primitive Besessenheit, wiederholte Switches, Schrotschuss-Chirurgie, divergente Änderung, spekulative Allgemeinheit, Nachrichtenketten, Mittelmann.
Die Blastradius-Achse (riskante oder umfangreiche Änderungen)
Aufrufer aufzulisten ist nicht die Aufgabe; grep erledigt das in einer Sekunde. Die Aufgabe ist der Bruch, den grep nicht zeigt:
- Finde die eine Tatsache, wegen der die Änderung sicher ist („dieser Aufruf entfernt nur Einträge, die bereits tot sind“). Beweise es durch Ausführen von Code: Ein Skript, das die echte Bibliothek in der festgelegten Version importiert und die exakte fragliche Funktion aufruft.
- Schau dort, wo die Symbolsuche aufhört: Bibliotheksquellen und lokale Patches, Ausführungszeitpunkt (async-Reihenfolge, Teardown), serialisierte Formate (JSON-Strukturen, DB-Spalten, Wire-Protokolle, andere Sprachen, die dieselben Bytes lesen), Feature-Flags, Verbraucher drei Hops entfernt.
- Für jedes Risiko: Wie es bricht,
datei:zeile, Wahrscheinlichkeit, Kosten und die billigste Prüfung. Liste geprüfte und ausgeschlossene Risiken separat auf.
Schritt 4: Jeden Befund überprüfen
Ein Befund, der richtig klingt, ist kein Befund, bis er überprüft wurde.
- Überprüfe ihn anhand der Aufrufer, Guards und Tests, die den Code erreichen. Verwerfe ihn, wenn sie ihn ausschließen.
- Beweise die wichtigen: Ein fehlschlagender Test, ein Reproduktionsskript oder eine Befehlsausgabe, die das falsche Verhalten zeigt. Bevorzuge Befunde, die durch einen Lauf belegt sind, gegenüber plausiblen.
- Kennzeichne bereits bestehende Mängel separat von Regressionen, die diese Änderung einführt.
- Führe Befunde zusammen, die eine gemeinsame Ursache haben.
- Null Befunde ist ein gültiges Ergebnis. Erfinde keinen, um gründlich zu wirken.
Die Hürde zum Blockieren eines Merges
Ein Befund kann nur dann als Kritisch oder Wichtig eingestuft werden (und damit den Merge blockieren), wenn er durch Beweise belegt ist:
- Ein Lauf (Test, Skript oder Befehl), der das falsche Verhalten zeigt, oder
- eine konkrete Eingabe, die Schritt für Schritt durch den Code zu einer falschen Ausgabe verfolgt wird, mit
datei:zeilebei jedem Schritt.
Ein plausibles Anliegen, das du auf diese Weise nicht belegen konntest („dies könnte X brechen“, „Grenzfälle könnten nicht behandelt werden“), wird als Gering eingestuft und mit unbestätigt gekennzeichnet. Es blockiert nicht. Liste es auf, damit der Autor es überprüfen kann.
Schritt 5: Einstufen und berichten
Bewerte nach Wirkung auf eine vernünftige Person, die die Software nutzt, wenn sie ausgeliefert wird, nicht danach, ob die Spezifikation den Auslöser erwähnt.
| Schweregrad | Bedeutung | Erforderliche Aktion |
|---|---|---|
| Kritisch | Sicherheitslücke, Datenverlust, kaputte Kernfunktionalität | Blockiert Merge |
| Wichtig | Falsches oder unzuverlässiges Verhalten, verpasste Anforderung, ungetestetes Verhalten, verschluckte Fehler, schädliche Duplizierung oder Design | Vor dem Merge beheben |
| Gering | Politur, kleine Vereinfachungen, breitere Abdeckung | Entscheidung des Autors; protokollieren, wenn aufgeschoben |
| NIT | Stilpräferenz | Optional |
| FYI | Kontext, keine Aktion | Keine |
Beginne mit dem Hebel: Korrektheit und Sicherheit zuerst, dann strukturelle Probleme und verpasste Vereinfachungen, dann der Rest. Wenn es ein strukturelles Problem und zehn Nits gibt, ist das strukturelle Problem das gesamte Review. Schlage die Bewegung vor, nicht nur das Problem: „Ersetze diese if-Kette durch eine Nachschlagetabelle mit kind als Schlüssel“, „Inline diesen Ein-Aufrufer-Wrapper“, „Verwende formatDate aus utils/date.ts wieder.“
Sei ehrlich: Kein abnickendes „LGTM“, kein Abschwächen eines echten Bugs zu „könnte ein geringes Problem sein“, kein Aufblähen von Nits zu Kritisch. Erkenne an, was gut gemacht wurde, konkret.
Verwende das Format in reviewer-prompt.md: Spezifikationsurteil, Stärken, Probleme nach Schweregrad (jeweils mit datei:zeile, was falsch ist, warum es wichtig ist, wie es zu beheben ist, Beweise), Blastradius-Notizen, abgelehnt zu beurteilen (Verhalten, das geprüft und beiseitegelegt wurde, mit Begründung) und ein Urteil: Genehmigen, Genehmigen mit Korrekturen oder Änderungen anfordern. Halte die Spezifikations- und Qualitätsabschnitte getrennt; ordne nicht über sie hinweg neu.
Urteilsregel: Fordere Änderungen nur an, wenn mindestens ein Kritischer oder Wichtiger Befund die oben genannte Beweishürde erfüllt. Eine Änderung, die das Geforderte tut und nur geringfügige oder unbestätigte Bedenken hat, wird genehmigt, wobei diese Bedenken aufgeführt werden. Die Ablehnung einer korrekten Änderung kostet den Autor genauso viel wie die Genehmigung einer kaputten.
Schritt 6: Auf Befunde reagieren (wenn du der Autor bist)
Review-Feedback ist ein Input zum Bewerten, keine Anordnung zum Ausführen.
- Lies alles davon, bevor du reagierst. Wenn ein Punkt unklar ist, frage danach, bevor du irgendetwas implementierst: Punkte hängen oft zusammen.
- Formuliere jeden Punkt als technische Anforderung um und überprüfe ihn am Code. Ist er für diese Codebasis korrekt? Bricht er etwas? Gab es einen Grund für den aktuellen Code? Hat der Prüfer den vollständigen Kontext?
- Widersprich mit Beweisen, wenn es falsch ist: ein Test, eine
datei:zeile, eine Messung. Wenn ein Vorschlag ein ungenutztes „richtiges“ Feature hinzufügt, überprüfe die Nutzung; YAGNI gilt auch für Prüfer. Eskaliere an den Benutzer alles, was mit seinen früheren Entscheidungen kollidiert. - Behebe in der Reihenfolge: Kritisch/Blockierend → einfach → komplex. Jede Korrektur bekommt zuerst einen fehlschlagenden Test, der den Befund reproduziert (über
test), dann die Korrektur, dann eine grüne vollständige Suite. Ein fokussierter Korrektur-Durchlauf, keine Endlosschleife. - Geringfügige, die du nicht behebst, kommen in eine „Aufgeschoben“-Liste in deiner abschließenden Nachricht. Ein Befund, den du nicht zu beheben beschließt, ist eine dokumentierte Entscheidung mit Begründung.
- Kein vorgetäuschtes Einverständnis. Kein „Du hast absolut recht!“, „Super erkannt!“ oder Danke. Sage, was du geändert hast („Gefixt: Leere Zeilen geben jetzt einen CSV-Header aus; Test
exportiert Header für leere Ansicht“) oder warum der Code bleibt. Wenn du widersprochen hast und falsch lagst, sage es in einem Satz und repariere es.
Antworte auf GitHub im Inline-Kommentarthread, nicht als Top-Level-Kommentar.
Vor dem Merge (Definition of Done)
- Jedes Spezifikations-Erfolgskriterium erfüllt und im laufenden System verifiziert
- Neues Verhalten hat Tests, die ohne die Änderung fehlschlagen; vollständige Suite grün, saubere Ausgabe
- Keine kritischen oder wichtigen Befunde offen; Aufschiebungen mit Gründen protokolliert
- Kein toter Code, Debug-Ausgaben oder auskommentierte Blöcke; Änderungen auf die Aufgabe beschränkt
- Lint, Typecheck, Build bestehen
- Migrationen, Konfiguration und Flags berücksichtigt; Rollback-Pfad für riskante Änderungen vorhanden
- Öffentliche Schnittstellen und benutzersichtbares Verhalten dokumentiert; ADR für schwer umkehrbare Entscheidungen
- Commit-Nachrichten und PR-Beschreibung sagen, was geändert wurde und warum, in eigenständigen Begriffen
Häufige Rationalisierungen
| Gedanke | Realität |
|---|---|
| „Tests bestehen, also ist es gut“ | Tests finden kein falsches Design, keine Sicherheitslücken oder eine falsch gelesene Spezifikation. |
| „Ich habe es geschrieben, ich weiß, dass es richtig ist“ | Gleicher Autor, gleiche blinde Flecken. Hol dir frische Augen. |
| „KI-generierter Code ist wahrscheinlich in Ordnung“ | Er ist selbstbewusst und plausibel, wenn er falsch liegt. Er braucht mehr Überprüfung, nicht weniger. |
| „Das Refactoring ist sauberer“ | Wenn der Leser gleich viele Konzepte behalten muss, wurde nur verschoben. |
| „Wir räumen später auf“ | Später kommt selten. Behebe es jetzt oder dokumentiere es explizit. |
| „Die Spezifikation hat diese Eingabe nicht erwähnt“ | Schweigen ist keine Erlaubnis. Bewerte nach dem, was der Benutzer bekommt. |
| „Der Prüfer sagte Gering, also ist es Gering“ | Bewerte neu nach Wirkung neu. |
| „Die Korrektur ist offensichtlich, kein Test nötig“ | Der fehlschlagende Test ist der einzige Beweis, dass der Befund real war und jetzt verschwunden ist. |
| „Der Prüfer hat wahrscheinlich recht“ | Überprüfe zuerst am Code. |
Rote Flaggen
- „LGTM“ ohne Beleg des Lesens
- Befunde ohne
datei:zeileoder behauptet, ohne Aufrufer und Guards zu prüfen - Spezifikations- und Qualitätsbefunde in einer einzigen Rangliste zusammengeführt
- Nits, die über einem Korrektheits-Bug begraben sind
- Ein Prüfer, der die Sitzungshistorie des Autors erhalten hat
- Behebung von Review-Befunden ohne vorherigen fehlschlagenden Test
- Einige Feedback-Punkte umgesetzt, während andere noch ausstehen