Seien wir ehrlich über etwas, das die meisten von uns nicht laut aussprechen: Wir reviewen KI-generierten Code kaum.

Der Diff umfasst 600 Zeilen. Der Agent hat 14 Dateien angefasst. Du öffnest den Pull Request, scrollst durch die Änderungen, kneifst die Augen bei ein paar Funktionen zusammen und mergst. Vielleicht lässt du vorher die Tests laufen. Vielleicht auch nicht. Der Code sieht vernünftig aus. Der Agent hat gesagt, er ist fertig. Ab damit.

Das ist keine Faulheit. Es ist ein strukturelles Problem. Traditionelles Code-Review wurde für eine Welt entworfen, in der ein Mensch den Code geschrieben hat und auf Nachfrage seine Gedanken erklären konnte. In der Diffs 50-200 Zeilen umfassten, weil das die Menge ist, die ein Mensch in einer konzentrierten Session produziert. In der die PR-Beschreibung sagte "Ich habe Ansatz X gewählt wegen Y" und man diesem Kontext vertrauen konnte.

KI-Agenten funktionieren anders. Claude Code kann 500 Zeilen funktionierenden Code in zwei Minuten produzieren. Die PR-Beschreibung lautet oft nur "Feature X implementiert." Der Diff zeigt dir was sich geändert hat, aber nichts über das warum. Keine Aufzeichnung darüber, welche Alternativen der Agent in Betracht gezogen hat. Keine Erklärung, welche Kompromisse er eingegangen ist. Kein Beweis, dass er tatsächlich etwas getestet hat. Du reviewst den Output einer Black Box, und das Review-Tool zeigt dir nur den Output.

Dieser Artikel erklärt, warum Diff-basiertes Review bei Agent-Output versagt, was die tatsächlich fehlende Ebene ist, und ein konkretes Pattern, das KI-generierten Code reviewbar macht, ohne deine Review-Zeit zu verdreifachen.

Die Review-Lücke

Entwickler sind privat ehrlich darüber. In Community-Threads wiederholt sich das Muster: "Ich überfliege Agent-Diffs meistens nur." "Ich prüfe, ob die Tests durchlaufen, und merge." "Wenn es ungefähr richtig aussieht, genehmige ich es."

Das ist rationales Verhalten angesichts der Einschränkungen. Wenn ein menschlicher Kollege einen PR einreicht, hast du Kontext: Du weißt, woran er gearbeitet hat, du hast das Ticket gesehen, vielleicht habt ihr den Ansatz im Standup besprochen. Der Diff ist ergänzend. Das eigentliche Review geschah durch geteilten Kontext.

Bei einem Agenten hast du nichts davon. Der Agent hat eine Aufgabe übernommen, war drei Minuten still und hat einen Diff produziert. Der einzige Kontext ist die einzeilige Beschreibung, die der Agent im PR hinterlassen hat. Diesen Diff von Grund auf zu reviewen, ohne Kontext über Absicht oder Begründung, dauert 5-10x länger als den PR eines Menschen gleicher Größe zu reviewen. Also tun die Leute es nicht. Sie prüfen stichprobenartig ein paar kritische Stellen und genehmigen.

Das Ergebnis ist vorhersehbar. Bugs schlüpfen durch, die mit Kontext aufgefallen wären. Architektonische Drift akkumuliert sich, wenn Agenten kleine Entscheidungen treffen, die sich aufschaukeln. Code-Qualität verschlechtert sich auf subtile Weise: nicht kaputt, aber auch nicht ganz richtig. Inkonsistente Fehlerbehandlung in einer Datei. Eine Datenbankabfrage, die funktioniert, aber schlecht skaliert. Eine neue Utility-Funktion, die eine bestehende dupliziert, weil der Agent nicht wusste, dass sie existiert.

Keiner dieser Fehler ist in einem Diff-Review sichtbar. Sie werden erst sichtbar, wenn du verstehst, was der Agent versucht hat und seine Absicht mit seiner Ausführung vergleichen kannst.

Warum Diffs nicht ausreichen

Ein Diff ist eine Aufzeichnung von Textänderungen. Das ist alles. Für menschliches Code-Review funktionieren Diffs, weil der Reviewer Absichten aus Mustererkennung und geteiltem Kontext ableiten kann. Du siehst, wie ein Kollege einen try/catch-Block hinzufügt, und weißt, dass er den Fehlerfall aus dem Bug-Report der letzten Woche behandelt. Du siehst, wie er eine Funktion umbenennt, und weißt, dass er der Namenskonvention folgt, auf die sich das Team geeinigt hat.

Bei KI-generiertem Code kannst du keine Absicht ableiten, weil du nicht Teil des Denkprozesses warst. Hier ist, was dir ein 500-Zeilen-Agent-Diff tatsächlich sagt:

Welche Dateien geändert wurden
Welche Zeilen hinzugefügt, geändert oder entfernt wurden
Die syntaktische Struktur des neuen Codes

Hier ist, was er dir nicht sagt:

Warum dieser Ansatz gewählt wurde. Der Agent hat möglicherweise drei verschiedene Implementierungen in Betracht gezogen. Er hat eine gewählt. Du weißt nicht warum. Vielleicht ist die gewählte optimal. Vielleicht war es das Erste, was er probiert hat, und es hat ausgereicht. Aus dem Diff kannst du das nicht erkennen.

Welche Alternativen verworfen wurden. Wenn der Agent eine Polling-Strategie statt WebSocket-Subscriptions gewählt hat, war das eine bewusste Architekturentscheidung oder ein Zufall? Ein Diff sagt es nicht.

Ob die Implementierung der Spec entspricht. Du müsstest die Spec in einem Fenster und den Diff in einem anderen öffnen und jedes Akzeptanzkriterium manuell abgleichen. Die meisten Leute tun das nicht.

Was getestet wurde und wie. Der Diff enthält vielleicht neue Test-Dateien. Aber hat der Agent sie ausgeführt? Waren sie erfolgreich? Decken sie die Edge Cases aus der Spec ab? Du müsstest den Branch auschecken und sie selbst laufen lassen, um das zu wissen.

Ob der Agent im Scope geblieben ist. Vielleicht war die Aufgabe "Login-Bug fixen" und der Agent hat zusätzlich die Auth-Middleware refactored, zwei Utility-Funktionen umbenannt und das Config-Schema aktualisiert. Alle diese Änderungen sehen isoliert betrachtet gut aus. Aber sie wurden nicht angefordert, nicht spezifiziert und nicht gegen die ursprünglichen Akzeptanzkriterien getestet.

Das ist kein Problem eines bestimmten Diff-Tools. GitHubs Review-Interface, GitLabs Merge Requests, Gerrit, git diff im Terminal. Sie alle zeigen dir dasselbe: was sich geändert hat. Für Agent-Output ist "was sich geändert hat" die unwichtigste Frage. Die wichtige Frage ist: Macht diese Änderung das, was sie sollte, und nichts anderes?

Die fehlende Ebene: Implementierungserzählung

Was Reviewer tatsächlich brauchen, ist die Argumentationskette des Agenten. Nicht der Diff. Die Geschichte der Implementierung: was der Agent geplant hat, was er tatsächlich getan hat und wie er das Ergebnis verifiziert hat. Nenn es Implementierungserzählung.

Eine gute Implementierungserzählung beantwortet fünf Fragen:

Was war der Plan? Bevor er Code geschrieben hat: Was wollte der Agent tun? Welche Dateien, welcher Ansatz, welche Reihenfolge?
Was passierte während der Implementierung? Hat der Plan den Kontakt mit der Codebase überlebt? Gab es Überraschungen, Richtungsänderungen oder Scope-Änderungen?
Was war das Endergebnis? Nicht der Diff. Eine Zusammenfassung in Klartext, was sich geändert hat und warum.
Wie wurde verifiziert? Konkrete Schritte, die der Agent unternommen hat, um zu bestätigen, dass die Implementierung funktioniert. Nicht "Tests bestanden", sondern "Ich habe Akzeptanzkriterium #3 ausgeführt, indem ich X getan und Y beobachtet habe."
Was sollte der Reviewer prüfen? Die Empfehlung des Agenten selbst, was menschliche Aufmerksamkeit verdient. Vielleicht gibt es eine Design-Entscheidung, die in beide Richtungen gehen könnte, oder einen Performance-Kompromiss, der eine zweite Meinung verdient.

Nichts davon existiert in einem Standard-PR-Workflow. Das PR-Beschreibungsfeld ist Freitext, den niemand erzwingt. Agent-PRs setzen minimale Beschreibungen als Default, weil dem Agenten gesagt wurde, er solle implementieren, nicht seine Gedanken dokumentieren.

Die Lücke ist nicht das Tooling. Es ist der Prozess. Die Review-Infrastruktur existiert. Was fehlt, ist eine strukturierte Aufzeichnung der Agent-Absicht, die der Reviewer gegen den Diff prüfen kann.

Das Plan-Comment-Done-Pattern

Hier ist ein Pattern, das die Lücke schließt, ohne signifikanten Overhead hinzuzufügen. Es hat drei Teile: Der Agent kommentiert einen Plan, bevor er Code schreibt, er implementiert, und er kommentiert einen strukturierten Done-Report, wenn er fertig ist.

Schritt 1: Der Plan-Comment

Bevor der Agent eine Datei öffnet, schreibt er auf, was er vorhat. Nummerierte Schritte, Dateien, die er anfassen wird, und der Ansatz, den er verfolgen wird.

PLAN: Fix WebSocket reconnection dropping messages during
server restart.

1. Add a message buffer to hooks/use-websocket.ts that queues
   outbound messages while the connection is in CONNECTING state
2. On successful reconnection, flush the buffer in order
3. Add a 30-second timeout: if reconnection hasn't succeeded,
   surface an error to the user via the toast system
4. Update the existing reconnection test to verify buffer
   behavior

Files: hooks/use-websocket.ts, components/connection-status.tsx

Test: Unit test for buffer queueing/flushing, manual test by
killing the WS server mid-operation and verifying no messages
are lost on reconnect.

Das kostet den Agenten etwa 30 Sekunden. Der Reviewer liest es in unter 2 Minuten. In diesen 2 Minuten fängst du Probleme ab, die im Diff-Review 20 Minuten kosten würden:

Stimmt der Scope? (Der Plan nennt 2 Dateien. Wenn der Diff 6 Dateien berührt, ist etwas abgedriftet.)
Ist der Ansatz vernünftig? (Ein Message-Buffer mit Flush-on-Reconnect ist sinnvoll. Hätte der Agent vorgeschlagen, den kompletten State vom Server neu zu laden, würdest du das vorher besprechen wollen.)
Fehlen Schritte? (Was ist mit Nachrichten, die während des Timeout-Fensters gesendet wurden? Sollen sie verworfen oder wiederholt werden?)

Der Plan ist ein leichtgewichtiger Checkpoint. Review ihn, genehmige ihn, und der Agent fährt mit geteiltem Verständnis der Absicht fort.

Schritt 2: Implementierung

Der Agent schreibt den Code. Hier ändert sich nichts. Aber weil der Plan existiert, hat der Agent eine Roadmap, der er folgen kann, statt ad-hoc-Entscheidungen unterwegs zu treffen.

Schritt 3: Der Done-Comment

Wenn der Agent fertig ist, postet er einen strukturierten Abschlussbericht. Nicht "fertig." Nicht "Feature implementiert." Ein detaillierter Bericht darüber, was er tatsächlich getan hat.

DONE: WebSocket reconnection now buffers outbound messages
during CONNECTING state and flushes on successful reconnect.

Changes:
- hooks/use-websocket.ts: Added messageBuffer ref, queue
  messages when readyState !== OPEN, flush in FIFO order on
  'open' event. Added 30s reconnection timeout.
- components/connection-status.tsx: Shows "Reconnecting..."
  badge during buffer state, switches to error toast after
  timeout.

QA Verification:
1. Start dev server and WebSocket server
2. Open app, verify connection dot is green
3. Kill WebSocket server process
4. Trigger an action that sends a WS message (e.g., update
   a bead status)
5. Restart WebSocket server within 30 seconds
6. Verify: the buffered message is delivered, bead status
   updates in the UI
7. Repeat step 3, but wait >30 seconds before restart
8. Verify: error toast appears after timeout

Acceptance criteria:
- [x] Messages sent during reconnection are not lost (step 6)
- [x] Timeout surfaces user-visible error (step 8)
- [x] No behavior change when connection is stable (step 2)

Commit: f4e2a1b

Jetzt hat der Reviewer alles, was er braucht. Er liest den Plan (was beabsichtigt war), liest den Done-Comment (was tatsächlich gebaut und wie es verifiziert wurde), und schaut sich dann den Diff mit vollem Kontext an. Das Diff-Review wandelt sich von "was ist das alles?" zu "lass mich bestätigen, dass das zu dem passt, was der Agent gesagt hat."

Review-Checklisten für Agent-Output

Auch mit der Implementierungserzählung brauchst du einen systematischen Ansatz. Hier ist eine Checkliste, die ich beim Reviewen von Claude Code Output verwende. Sie braucht 5-10 Minuten pro Review und fängt die Kategorien von Bugs ab, die Diffs allein übersehen.

Spec-Alignment:

Adressiert die Implementierung jedes Akzeptanzkriterium aus der Spec?
Gibt es Änderungen, die über das hinausgehen, was die Spec verlangt hat?
Bildet der Done-Comment jedes Kriterium auf einen Verifikationsschritt ab?

Scope-Begrenzung:

Hat der Agent nur die im Plan aufgeführten Dateien geändert?
Wenn er zusätzliche Dateien angefasst hat, gibt es einen angegebenen Grund?
Gibt es "Aufräum"-Änderungen (Umbenennungen, Neuformatierungen, Refactorings), die nicht Teil der Aufgabe waren?

Testabdeckung:

Gibt es neue Tests für neues Verhalten?
Testen die Tests tatsächlich das Richtige? (Agenten schreiben manchmal Tests, die trivialerweise bestehen, weil sie den Mock testen, nicht die Implementierung.)
Hat der Agent behauptet, die Tests ausgeführt zu haben? Gibt es Belege?

Architektonische Konsistenz:

Folgen die Änderungen bestehenden Patterns in der Codebase?
Gibt es neue Abstraktionen, die bestehende duplizieren?
Passt die Fehlerbehandlungsstrategie zum Rest des Projekts?

Abhängigkeitsbewusstsein:

Falls der Agent Dependencies hinzugefügt hat, sind sie gerechtfertigt?
Brechen die Änderungen bestehende Funktionalität? (Prüfe Dateien, die die geänderten Module importieren.)
Falls die Aufgabe Abhängigkeiten zu anderen Aufgaben hat, sind diese Abhängigkeiten aufgelöst?

Diese Checkliste funktioniert mit jedem Code-Review-Tool. Drucke sie auf einen Post-it, füge sie in dein PR-Template ein, oder bau sie in deine CLAUDE.md ein, damit der Agent weiß, an welchem Standard er gemessen wird. Es geht nicht um die spezifischen Punkte. Es geht darum, ein strukturiertes Protokoll zu haben statt "sieht gut aus."

Beads als Review-Oberfläche

Das Plan-Comment-Done-Pattern braucht einen Ort zum Leben. Wenn Pläne und Done-Comments über Slack-Nachrichten, PR-Beschreibungen und Terminal-Output verstreut sind, geht die Verbindung zwischen Spec, Plan, Implementierung und Verifikation verloren.

Das ist das Problem, das beads löst. Beads ist ein Open-Source, Git-nativer Issue-Tracker, bei dem jedes "Bead" den gesamten Lebenszyklus einer Aufgabe trägt: die Spec als Beschreibung, Agent-Pläne als Kommentare, Done-Reports als Kommentare und QA-Ergebnisse als Kommentare. Alles an einer Entität, durchsuchbar und dauerhaft.

So sieht der Review-Workflow mit dem bd CLI aus:

Aufgabe mit Spec erstellen:

bd create --title "Fix WebSocket reconnection message loss" \
  --description "## Problem
Messages sent during WebSocket reconnection are silently
dropped...

## Acceptance Criteria
1. Messages queued during CONNECTING state are delivered
   on reconnect
2. 30-second timeout surfaces error to user
3. No behavior change when connection is stable" \
  --type bug --priority p1

Agent übernimmt die Arbeit und postet einen Plan:

bd update bb-f4e2 --claim --actor eng1
bd comments add bb-f4e2 --author eng1 "PLAN: Add message
buffer to WebSocket hook...

1. Queue outbound messages when readyState !== OPEN
2. Flush buffer in FIFO order on 'open' event
3. Add 30s timeout with error toast
4. Update reconnection test

Files: hooks/use-websocket.ts, components/connection-status.tsx"

Du reviewst den Plan in 2 Minuten:

bd show bb-f4e2  # Spec + Plan-Comment lesen

Wenn der Plan richtig aussieht, fährt der Agent fort. Wenn nicht, kommentierst du mit Korrekturen, bevor Code geschrieben wird.

Agent beendet die Arbeit und postet einen Done-Report:

bd comments add bb-f4e2 --author eng1 "DONE: WebSocket
reconnection now buffers outbound messages...

QA Verification:
1. Kill WS server, trigger action, restart within 30s...

Acceptance criteria:
- [x] Buffered messages delivered on reconnect
- [x] Timeout error visible
- [x] No regression on stable connection

Commit: f4e2a1b"

bd update bb-f4e2 --status ready_for_qa

QA verifiziert unabhängig:

bd show bb-f4e2  # Verifikationsschritte aus dem Done-Comment lesen
# Jeden Schritt ausführen
bd comments add bb-f4e2 --author qa1 "QA PASS: All 3 criteria
verified. Buffer flushes correctly, timeout fires at 30s,
stable connections unaffected."

Die gesamte Review-Spur ist an einem Ort. Sechs Monate später, wenn jemand fragt "warum buffert der WebSocket Nachrichten während der Reconnection?", steht die Antwort im Bead: Die Spec erklärt das Problem, der Plan erklärt den Ansatz, der Done-Comment erklärt, was gebaut wurde, und der QA-Comment bestätigt, dass es funktioniert.

Wenn Terminal-Review an seine Grenzen stößt

bd show auf einer einzelnen Aufgabe gibt dir alles. Aber wenn du den Output mehrerer Agenten über verschiedene parallele Workstreams reviewst, skaliert der CLI-Workflow linear: ein bd show pro Aufgabe, ein bd list um zu sehen, was bereit für Review ist, ein bd show pro Plan, den du genehmigen musst.

Hier passt Beadbox hinein. Beadbox ist ein Echtzeit-Dashboard, das dir jede Aufgabe in deinem Workspace mit ihrem aktuellen Status, letzten Kommentar und ihrer Position in der Review-Pipeline zeigt. Du siehst, welche Agenten Pläne gepostet haben, die deine Genehmigung brauchen. Welche Done-Reports gepostet haben, die bereit für dein Review sind. Welche noch in Arbeit sind. Alles aktualisiert sich live, während Agenten Kommentare schreiben und Status über das bd CLI ändern.

Du brauchst Beadbox nicht, um das Plan-Comment-Done-Pattern zu nutzen. Das CLI bewältigt den gesamten Workflow. Aber wenn du fünf Agenten hast, die gleichzeitig reviewbaren Output produzieren, verändert es deine Geschwindigkeit durch die Pipeline, wenn du die Review-Queue auf einen Blick sehen kannst, statt jede Aufgabe einzeln abzufragen.

Beadbox ist während der Beta kostenlos, und das beads CLI, auf dem es läuft, ist Open Source.

Das Review-Problem löst sich nicht von selbst

KI-generierter Code nimmt schneller zu als unsere Fähigkeit, ihn zu reviewen. Die Tools, die wir haben, wurden für einen anderen Maßstab und einen anderen Workflow gebaut. GitHub PRs, IDE Diffs, sogar ausgefeilte statische Analyse: Keines davon adressiert das fundamentale Problem, nämlich dass Code ohne Kenntnis der Absicht des Autors zu reviewen dramatisch schwieriger ist als Code mit dieser Kenntnis.

Die Lösung sind nicht bessere Diff-Tools. Es ist strukturierte Absicht: eine Aufzeichnung dessen, was der Agent geplant hat, was er tatsächlich getan hat und wie er das Ergebnis verifiziert hat. Das Plan-Comment-Done-Pattern gibt dir diese Aufzeichnung ohne signifikanten Overhead. Der Agent verbringt 30 Sekunden mit dem Schreiben eines Plans. Du verbringst 2 Minuten mit dem Review. Der Agent verbringt 60 Sekunden mit dem Schreiben eines Done-Reports. Du reviewst den Diff mit vollem Kontext statt von Grund auf.

Fünf Prinzipien zum Mitnehmen:

Verlange Pläne vor Code. Ein 30-Sekunden-Plan-Comment spart 20-Minuten-Review-Sessions. Wenn der Plan falsch ist, korrigiere ihn, bevor der Code existiert.
Fordere strukturierte Done-Reports. "Fertig" ist kein Done-Report. Verifikationsschritte, Akzeptanzkriterien-Mapping und Commit-Hashes sind ein Done-Report.
Reviewe gegen die Spec, nicht gegen den Diff. Der Diff zeigt, was sich geändert hat. Die Spec sagt, was sich hätte ändern sollen. Gleiche sie ab.
Erzwinge Scope-Grenzen. Wenn der Agent Dateien außerhalb seines Plans angefasst hat, ist das ein Warnsignal. Ungeplante Änderungen sind unreviewte Änderungen.
Behandle Review als Protokoll, nicht als Bauchgefühl. Eine Checkliste fängt mehr Bugs als Intuition. "Sieht gut aus" ist kein Review.

Die Agenten werden weiter schneller. Die Diffs werden weiter größer. Die Frage ist, ob dein Review-Prozess mit ihnen skaliert, oder ob du immer noch 600-Zeilen-Diffs durchschaust und das Beste hoffst.

Wenn du Workflows wie diese baust, gib Beadbox einen Stern auf GitHub.

KI-Code-Review ist kaputt. Das fehlt.