Teil 16. Teamarbeit und Code-Review

Bisher hat das Lehrbuch einen einzelnen Entwickler durch den vollständigen SDD-Zyklus geführt. In einem Team kommt eine zweite Komplexitätsschicht hinzu: Die Spezifikation wird nicht nur zum Hinweis für den Agenten, sondern auch zu einem Vertrag zwischen Menschen. Wenn dieser Vertrag nicht reviewed wird, kann der Agent akkuraten Code basierend auf einer schwachen oder unvollständigen Beschreibung implementieren.

Die wichtigste Regel für SDD im Team:

Im Merge-Request wird nicht nur der Code geprüft.
Es wird die Kombination geprüft: Anforderungen -> Plan -> Validierungsfakten -> Änderungen.

Wie der Arbeitsablauf aussieht

flowchart TD
  A["Feature-Branch"] --> B["Spezifikation<br/>requirements.md<br/>plan.md<br/>validation.md"]
  B --> C["Erstes Review<br/>sind die Grenzen und Fakten verständlich"]
  C --> D{"Kann implementiert werden?"}
  D -- "nein" --> B
  D -- "ja" --> E["Implementierung"]
  E --> F["Prüfung nach validation.md"]
  F --> G["Pull request"]
  G --> H["Code- und Spezifikations-Review"]
  H --> I{"Bereit zum Mergen?"}
  I -- "nein" --> B
  I -- "ja" --> J["Merge und Neuplanung"]

In einem kleinen Team kann das erste Review mündlich durchgeführt werden. In einem großen Team ist es besser, einen kurzen Kommentar im Merge-Request zu hinterlassen: "Grenzen sind verständlich, Validierungsfakten sind ausreichend, Implementierung kann beginnen". Das spart Zeit beim finalen Review.

Was der Autor vor dem Öffnen des Merge-Requests prüft

Vor dem Merge-Request muss der Autor vier Fragen beantworten.

1. Hat das Feature einen eigenen Ordner in specs/?
2. Hat der Agent Dateien außerhalb der Feature-Grenzen geändert?
3. Sind alle obligatorischen Fakten aus validation.md geprüft?
4. Wenn sich Fakten im Laufe der Arbeit geändert haben, ist erkennbar, warum sie sich geändert haben?

Die letzte Frage ist besonders wichtig. Ein schlechtes Zeichen: Der Agent ändert validation.md nach einem Testfehler so, dass die Prüfung einfacher wird. Ein gutes Zeichen: Der Autor schreibt explizit im PR, dass ein Fakt falsch war, erklärt den Grund und fügt einen neuen Fakt hinzu.

Was der Reviewer prüft

Der Reviewer in einem SDD-Projekt betrachtet vier Ebenen.

Anforderungen. Ist verständlich, für wen das Feature gemacht wird, was in die Grenzen fällt, was nicht fällt, welche Entscheidungen bereits getroffen wurden?

Plan. Entsprechen die Aufgabengruppen den Anforderungen? Gibt es einen versteckten großen Refactoring, der nicht mit dem Feature zusammenhängt?

Fakten. Prüfen die Fakten das tatsächliche Verhalten und nicht die Absicht? Gibt es zumindest teilweise maschinell prüfbare Fakten?

Code. Entspricht die Implementierung dem Plan und den Fakten? Gibt es Änderungen, die der Agent "nebenbei" gemacht hat?

Wenn der Reviewer nur den Code betrachtet, degradiert SDD zu einem gewöhnlichen Review mit vielen Markdown-Dateien.

Vorlage für den Merge-Request

Die minimale Vorlage ist im Anhang ausgelagert: appendix-c-checklists.md. Sie kann nach .github/pull_request_template.md kopiert werden.

Der Sinn der Vorlage liegt nicht in der Bürokratie. Sie zwingt den Autor, den Zusammenhang zwischen Spezifikation und Änderungen aufzuzeigen:

• welcher Spezifikationsordner zur Branch gehört;
• welche Validierungsfakten bestanden haben;
• welche Fakten zurückgestellt wurden und warum;
• welche Dateien außerhalb des erwarteten Bereichs geändert wurden;
• was der Reviewer besonders aufmerksam prüfen soll.

Wenn die Vorlage länger wird als der Merge-Request selbst, kürzen Sie sie. Für die meisten Features reichen 6–8 Punkte.

Wann die Spezifikation in derselben Branch korrigiert wird

Die Spezifikation kann in derselben Branch korrigiert werden, wenn die Präzisierung mit dem aktuellen Feature zusammenhängt und die Projektstrategie nicht ändert.

Beispiele für normale Korrekturen:

• den erwarteten HTTP-Status präzisieren;

• einen manuellen Fakt zur Prüfung der Benutzeroberfläche hinzufügen;
• einen falschen Routennamen korrigieren;
• einen Fakt als zurückgestellt mit Begründung markieren;
• eine während der Implementierung getroffene Entscheidung hinzufügen.

Eine schlechte Korrektur: Die Feature-Grenzen so umschreiben, dass sie mit dem bereits zufällig geschriebenen Code übereinstimmen. Das ist keine Präzisierung, sondern eine versteckte Aufgabenänderung.

Wann ein separater Replanning-Branch nötig ist

Ein separater Replanning-Branch ist nötig, wenn die Änderung die Projektverfassung betrifft:

• der Stack ändert sich;
• die Phasenreihenfolge ändert sich;
• eine neue architektonische Grenze entsteht;
• die MVP-Definition ändert sich;
• mehrere zukünftige Features müssen eine neue Regel berücksichtigen;
• QWEN.md oder ein Team-Skill neu geschrieben werden muss.

Dieser Ansatz reduziert Konflikte und macht die Historie verständlich: Der Feature-Branch implementiert ein Feature, der Replanning-Branch ändert den Prozess oder die Roadmap.

Konflikte in roadmap.md

roadmap.md wird oft zum Engpass. Zwei Personen können gleichzeitig verschiedene Phasen beginnen und beide den Status der Roadmap ändern.

Praktische Regel:

Im Feature-Branch kann roadmap.md gelesen und auf eine Phase verwiesen werden.
Statusänderungen in roadmap.md sind besser vor dem Merge oder in einem kurzen Replanning-Branch.

Wenn das Team groß ist, führen Sie eine Roadmap-Besitzer-Regel ein. Das ist kein Prozessmanager, sondern eine Person, die darauf achtet, dass die Phasenstatus nicht von der Realität abweichen.

Wie Qwen Code im Review eingesetzt wird

Qwen Code ist nützlich als zweiter Leser, aber nicht als Ersatz für den Reviewer.

Gute Anfrage:

/clear
Lies @QWEN.md, die Spezifikation dieser Branch und git diff.
Vergleiche die Implementierung mit requirements.md, plan.md und validation.md.
Erstelle eine Liste der Abweichungen.
Ändere keine Dateien.

Schlechte Anfrage:

Prüfe den Merge-Request und korrigiere alles, was du findest.

Im zweiten Fall vermischt der Agent Review, Korrektur und Entscheidungsfindung. In der Teamarbeit ist das gefährlich: Das Review muss zuerst eine klare Liste der Abweichungen erstellen, und erst dann entscheidet der Autor, was korrigiert wird.

Was nicht dem Agenten im Autopilot überlassen werden darf

Überlassen Sie dem Agenten nicht ohne menschliche Entscheidung:

• Erweiterung der Feature-Grenzen;
• Änderung des Technologie-Stacks;
• Löschung von Fakten aus validation.md;
• Änderung der Sicherheitsrichtlinie;
• Aktualisierung der Roadmap mehrerer Phasen;
• Merge eines Merge-Requests;
• Änderung der Git-Historie;
• Löschung von Daten oder Migrationen, die nicht wiederholt werden können.

Der Agent kann Änderungen vorschlagen. Der Mensch trägt die Verantwortung für die Entscheidung.

Praktische Übung

Nehmen Sie ein bereits implementiertes Feature von AgentClinic und betrachten Sie es als gedanklichen Merge-Request.

1. Finden Sie den Spezifikationsordner.
2. Notieren Sie drei Hauptfakten aus validation.md.
3. Vergleichen Sie sie mit den geänderten Dateien.
4. Finden Sie mindestens eine Frage, die ein Reviewer stellen würde.
5. Formulieren Sie eine kurze Merge-Request-Beschreibung nach der Vorlage aus Anhang C.

Wenn die Merge-Request-Beschreibung nicht ohne Vermutungen geschrieben werden kann, ist die Spezifikation nicht ausreichend übertragbar.

Verwandte Teile

• Teil 18 analysiert Sicherheitsrisiken beim Review: was im Diff auf Leaks von Geheimnissen, neue MCP-Server, Hook-Änderungen zu prüfen ist.
• Teil 20 (Antipatterns) listet Situationen auf, die der Reviewer sofort ablehnen muss: Spezifikation ohne Fakten, im Laufe der Arbeit geschwächte Fakten, Implementierung einer zukünftigen Phase.
• Teil 17 beschreibt, welche Hooks helfen, Teile der Review-Prüfungen automatisch durchzuführen.