Code ist die beste Spec: Reviews im Spec-driven Development

Wer mit Spec-driven Development (SDD) arbeitet, verbringt viel Zeit mit dem Lesen von Specs und Code. Um den versprochenen Effizienzgewinn zu erreichen, muss man sich entscheiden, wohin die Review-Zeit fließt. Drei Monate lang habe ich mit meinem Team in einem Greenfield-Projekt mit der BMad Method gearbeitet. Meine Antwort ist danach klar: Für die Entwicklung von gut geschnittenen Features reicht ein kurzer Blick auf die Akzeptanzkriterien der Spec. Die gründliche Prüfung gehört in den Code. Nur so lässt sich sicherstellen, dass Features korrekt implementiert, Lösungen nicht overengineered und die Codebasis langfristig wartbar sind.

Zwei Wege, Spec-driven Development zu leben

Drei Monate lang haben wir als erfahrenes Entwicklungsteam in einem Greenfield-Projekt mit einem SDD-Framework gearbeitet, in unserem Fall die BMad Method. Zuerst haben wir Architektur und Code-Konventionen durchdacht und festgehalten. Dann ging es an die Umsetzung der ersten Features. Wie bei BMad vorgesehen, haben wir die Spec-Dateien dabei nicht selbst geschrieben. Wir haben der KI eine grobe Beschreibung des Features gegeben, und ein Agent hat mithilfe der entsprechenden Skills des Frameworks daraus eine vollständige Spec generiert. Dabei haben wir festgestellt, dass die KI in kurzer Zeit eine Vielzahl von Dokumenten erzeugt. Darin bricht sie ein Feature in Stories herunter, beleuchtet die Details jeder Story und skizziert einen Implementierungsplan. Daraus entstand zügig fertiger Code. Um die so gewonnene Geschwindigkeit nicht wieder zu verlieren, muss man akzeptieren, dass man sich nicht alles im Detail anschauen kann. Beim Review gilt es, Prioritäten zu setzen. Grob lassen sich zwei Ansätze unterscheiden.

Spec als Vertrag: Man reviewt die generierte Spec gründlich und schärft sie nach, bis sie das Feature vollständig beschreibt. Die Hoffnung dahinter ist, dass die KI dann so eigenständig umsetzt, dass das Code-Review kaum noch Überraschungen bringt.

Spec als Kompass: Man prüft die generierte Spec nur auf die grobe Richtung, geht schnell in die Umsetzung und verlegt die gründliche Prüfung ins Code-Review. Wenn Anpassungen nötig sind, setzt man sie direkt zusammen mit der KI im Code um.

Was ein Spec-Review leisten soll

Zu Beginn haben wir sämtliche Feature-Specs genau untersucht. Dadurch wollten wir direkt am Anfang der Entwicklung fachliche Korrektheit sicherstellen. In der Spec waren die Details des Features in natürlicher Sprache formuliert, sodass sich gut mit der KI darüber diskutieren ließ. Ein Missverständnis in der Spec zu finden, ist außerdem günstiger, als es später im Code zu entdecken. Denn bis dahin sind noch keine KI-Kosten für die Implementierung angefallen. Beim Review des generierten Codes sind uns trotzdem einige Probleme aufgefallen, die wir im Spec-Review nicht abfangen konnten. Und das, obwohl die Spec bereits relativ genau auf die technische Umsetzung einging.

Wo das Spec-Review an Grenzen stößt

Unsere generierten Specs enthalten gern Sätze, die nach Sorgfalt klingen: "soll konfigurierbar sein", "soll erweiterbar sein". Auch wenn diese Details gar nicht gefordert sind, widerspricht im Spec-Review niemand, weil sie harmlos klingen. Die implementierende KI nimmt sie aber sehr ernst. Dadurch verbeißt sie sich teilweise in diese Nebensächlichkeiten, und es entsteht unnötig komplizierter Code. Über viele Features summiert sich so Code, der reviewt, getestet und gewartet werden muss.

Außerdem zeigt sich in der Spec oft nicht, ob ein Feature technisch überhaupt sinnvoll umsetzbar ist. Teilweise haben wir viel Arbeit in die Entwicklung einer Spec gesteckt und sie sehr genau reviewt. Erst bei der Implementierung fiel dann auf, dass sich das Feature so nur mit unverhältnismäßig hoher Komplexität umsetzen ließ. Wären wir schneller von der Spec-Phase in die Implementierungsphase übergegangen, hätten wir uns diese Arbeit sparen können.

Unser Weg: schlankes Spec-Review, gründliches Code-Review

Auf der grünen Wiese gab es kaum Konventionen, an denen sich die KI orientieren konnte. Als Baseline haben wir deshalb mit dem SDD-Framework Spec-Dateien zu Architektur und Code-Konventionen angelegt. Trotzdem traten bei den ersten Features genau die oben genannten Probleme auf. Wir haben also von Anfang an viel Zeit ins Code-Review gesteckt.

Weil wir zusätzlich die Specs genau reviewt haben, haben wir vieles doppelt angeschaut: einmal in der Spec, einmal im Code. Das gründliche Spec-Review hat uns das Code-Review nicht erspart, es kam einfach obendrauf.

Außerdem war das Review der Specs recht mühsam, da generierte Specs lang, wortreich und an manchen Stellen kryptisch formuliert sind. Bei manchem Nebensatz war uns nicht klar, was die KI damit eigentlich meinte und ob er für die Umsetzung überhaupt eine Rolle spielt. Mit Entwicklungserfahrung lässt sich im Code dagegen relativ einfach ablesen, was letztendlich passiert. Der Code ist am Ende die präziseste Spec: Er beschreibt eindeutig, was das System tatsächlich tut.

Also haben wir das Spec-Review auf die Akzeptanzkriterien reduziert. Sie zeigen, wie die KI das Feature fachlich verstanden hat. Dadurch decken sie das wichtigste Ziel des Spec-Reviews ab. Die eigentliche Prüfung findet im Code statt. Damit sind wir von Spec als Vertrag zu Spec als Kompass gewechselt. So fiel die Doppelarbeit weg, und der Gesamtaufwand pro Feature sank, obwohl wir im Code weiterhin genau hingeschaut haben.

Ein weiterer Vorteil: Das Systemverständnis bleibt erhalten. Durch das konsequente Code-Review haben wir eine hohe Code-Qualität sichergestellt. Außerdem haben wir uns gut in der Codebasis zurechtgefunden, obwohl wir den Großteil davon nicht selbst geschrieben haben. Das war die Grundlage für fundierte Architekturentscheidungen. Parallel dazu haben wir die Architektur- und Konventionsdateien kontinuierlich verbessert. Erkenntnisse aus den Code-Reviews haben wir dort zurückgeschrieben, damit die KI dieselben Fehler nicht wiederholt. Zusammen mit den wachsenden Beispielen im Code wurden die Ergebnisse der KI dadurch mit der Zeit besser.

Risiken eines schlanken Spec-Reviews und wie wir sie begrenzen

Das größte Risiko: Enthält die Spec gröbere Fehler, baut die KI eine Implementierung, die wir anschließend komplett wegwerfen oder stark umbauen müssen. Das kostet Zeit und KI-Budget, bei größeren Features umso mehr. Geholfen hat uns hier unser SDD-Framework. Es stellt vor der Erstellung der Spec viele Rückfragen und sorgt so dafür, dass die KI das Feature gut versteht. Zusätzlich hilft ein Blick auf die Akzeptanzkriterien vor der Implementierung. Es kam natürlich vor, dass nach Abschluss der Implementierungsphase noch Änderungen nötig waren. Dann haben wir mit der KI einige Iterationen durchlaufen, bis das Feature fertig war. Dabei ging es oft um Details, die ein genaueres Spec-Review vielleicht aufgedeckt hätte. Im Code verursachten sie aber wenig Aufwand, da wir selten große Teile umbauen mussten.

Eine weitere Konsequenz: Wenn wir Anpassungen direkt im Code vornehmen, stimmt die Spec anschließend nicht mehr mit der Implementierung überein. Das nehmen wir bewusst in Kauf, denn die Specs sind für uns nur temporäre Arbeitsdokumente für die Implementierung. Nach Abschluss einiger weiterer Features veralten sie ohnehin schnell. Die verlässliche Beschreibung des Systems ist dann der Code selbst.

Fazit: Spec für das Was, Code für das Wie

Nach drei Monaten mit der BMad Method hat sich für unser Team eine klare Arbeitsteilung ergeben. In der Spec prüfen wir die Akzeptanzkriterien, also ob die KI das Feature fachlich richtig verstanden hat. Dazu kommen Architektur- und Konventionsdateien als Baseline, die mit jedem Code-Review schärfer werden. Im Code prüfen wir die Umsetzung: versteckte Komplexität, Scope, Code-Qualität und Korrektheit. SDD ersetzt das Handwerk der Softwareentwicklung nicht, sondern verschiebt den Schwerpunkt. Wir als Entwicklungsteam prüfen und entscheiden, die KI setzt um und korrigiert. Mein Rat deshalb: Nutzt die Spec als Kompass, statt euch auf jedes Detail zu fokussieren. Setzt eure Expertise dort ein, wo der Hebel am größten ist: im generierten Code.