Spec-driven Development mit KI-Agenten: Das Repository von Spec Kit ignoriert die eigenen Specs

GitHubs Ankündigung von Spec Kit hat das Versprechen von Spec-driven Development in einen Satz gepackt: „We’re moving from ‘code is the source of truth’ to ‘intent is the source of truth.’“ Erst die Spec schreiben, dann den Coding-Agenten daraus planen und bauen lassen, und die Spec als das behalten, woran alle den Code messen. In dieser Erzählung ist die Spec der Teil einer Agenten-Session, der die Session überlebt.

Dann schau dir an, was Spec Kit im eigenen Repository behält. Die .gitignore enthält specs/, also genau das Verzeichnis, in dem jede Feature-Spec, jeder Plan und jede Taskliste landet, und die Projektdokumentation sagt, dass das Absicht ist:

Spec Kit's own repository illustrates this choice: it tracks
`.specify/memory/constitution.md`, while `specs/` is gitignored and
feature artifacts are not tracked.

Die Constitution, also die projektweiten Regeln, bleibt in der Versionskontrolle. Die Feature-Specs bleiben draußen. Dieselbe Seite fügt vorsichtig hinzu, das Ausschließen „does not establish whether they are deleted or archived“, sage also nichts darüber, ob sie gelöscht oder archiviert werden, und ich nehme sie beim Wort: Die Specs können gut in einem Pull Request oder auf irgendeiner Festplatte liegen. Teil des Repositorys, das der nächste Contributor klont, sind sie nicht.

Die Dokumentation nennt diese Wahl „constitution-only“ und bietet sie als eine von vier Möglichkeiten an, mit einer Spec nach der Auslieferung umzugehen. Keine davon ist der Standard. Ich finde, das sagt mehr über Spec-driven Development als die Ankündigung. Eine Spec überlebt die Session, in der sie entstanden ist, durchaus, und genau das ist der billige Teil. Am meisten wert ist eine Spec bei der Auslieferung, als einziges Artefakt, das ein Mensch gelesen und korrigiert hat, bevor es Code gab. Nach dem Merge ist sie ein Dokument, das von allein niemand mehr prüft, und so ein Dokument veraltet wie jedes andere.

Spec-driven Development in Spec Kit, Kiro und Tessl: wie lange eine Spec zählt

Birgitta Böckelers Vergleich von Kiro, Spec Kit und Tessl auf der Website von Martin Fowler ist inzwischen ein Jahr alt und immer noch die klarste Landkarte. Sie ordnet Spec-driven Development danach, wie lange die Spec eine Rolle spielt:

Spec-first: A well thought-out spec is written first, and then used in
the AI-assisted development workflow for the task at hand.
Spec-anchored: The spec is kept even after the task is complete, to
continue using it for evolution and maintenance of the respective feature.
Spec-as-source: The spec is the main source file over time, and only the
spec is edited by the human, the human never touches the code.

Ihr Befund: Die Tools arbeiteten spec-first und hatten jenseits davon wenig zu bieten. Kiro war „mostly spec-first“. Tessl war das einzige Tool, das „explicitly aspires to a spec-anchored approach“. Spec Kit legte pro Spec einen Branch an, wodurch die Spec „for the lifetime of a change request, not the lifetime of a feature“ lebte.

Einiges davon hat sich geändert. Im heutigen Spec Kit sind Spec-Verzeichnis und Git-Branch unabhängig: Specs landen in nummerierten Verzeichnissen unter specs/, und das Anlegen eines Branches ist ein optionaler Hook. Der Persistenz-Guide auf dem Main-Branch zitiert ihren Artikel und antwortet darauf mit vier Modellen. Sie reichen von flow-forward, bei dem jedes Feature-Verzeichnis ein unveränderlicher Datensatz ist und eine Änderung ein neues bekommt, bis zu living spec, bei dem du zuerst spec.md bearbeitest und den Rest neu generierst. Kiros Best-Practices-Seite beschreibt Specs mit Stand 8. November 2026 als „designed for continuous refinement“: Du bearbeitest requirements.md oder design.md, wählst Sync Files auf tasks.md, um Tasks für die Änderung anzulegen, und kannst Kiro fragen, ob die Implementierung die Akzeptanzkriterien eines Tasks erfüllt.

Beide Tools erlauben also inzwischen, eine Spec zu behalten und zu ändern. Was keines von beiden standardmäßig tut: von selbst bemerken, dass eine ältere Spec und der Code auseinandergelaufen sind. Jede Prüfung in beiden Toolkits läuft, wenn jemand sie startet, meistens während das Feature gebaut wird, für das die Spec geschrieben wurde. Ob eine Spec ihre Session überlebt, hängt weiter von den Gewohnheiten des Teams ab, und Tessls Anspruch, spec-anchored zu sein, war zum Zeitpunkt von Böckelers Review eben ein Anspruch.

Spec Kits /speckit-converge prüft den Code bei der Auslieferung gegen die Spec

Eine Prüfung bekommst du von Spec Kit am Ende eines Features. Seit Juni liefert es /speckit-converge mit, und der minimale Ablauf endet damit: implementieren, konvergieren, wiederholen, bis die Konvergenz Converged meldet. Das Befehls-Template sagt klar, was für eine Prüfung das ist. Es liest spec.md, plan.md und tasks.md als „the sole source of intent“, bewertet den aktuellen Code daran und hängt jede Lücke als neuen Task an. Die Spec bearbeitet es nie. Und den eigenen Checkboxen der Taskliste traut es nicht:

Include every existing task in the intent inventory, regardless of
checkbox state or Convergence phase: completion claims are not evidence.

Das ist die Zeile, die ich aus dem ganzen Toolkit mitnehmen würde. Ein als erledigt markierter Task ist eine Behauptung, und der Code ist der Beleg. Es ist derselbe Instinkt wie einen Test scheitern zu sehen, bevor man ihm traut: Ein grüner Status von dem, der die Arbeit gemacht hat, beweist wenig.

Die Zeile zeigt auch auf die Schwachstelle. Bei converge gleicht ein Modell Code mit einem Dokument ab, und die Prüfung ist nur so unabhängig wie das Dokument. /speckit-specify nimmt einen Satz, im Beispiel aus der README „Build a photo organizer with albums grouped by date and a tile preview of each album.“, und schreibt daraus die Spec. Wenn du das Ergebnis nur überfliegst und weitermachst, vergleicht converge später den Code des Agenten mit der Lesart deines Satzes durch denselben Agenten, und wenn diese Lesart falsch ist, stimmen beide trotzdem überein. Was du bekommst, ist eine längere, selbstsicherere Wiederholung dessen, was der Agent ohnehin glaubte, und danach eine Prüfung, die ihr zustimmt.

Zur Referenz wird die Spec erst dadurch, dass ein Mensch sie gelesen und Zeile für Zeile akzeptiert oder korrigiert hat, bevor es den Plan gab. Genau hier greift Böckelers Einwand:

To be honest, I’d rather review code than all these markdown files.

Bei vielen Aufgaben hat sie recht. Meine Lesart: Die Antwort hängt davon ab, was jedes Artefakt zeigen kann. Code zeigt, was das System tut. Er kann nicht zeigen, was das System ablehnen sollte oder welche Randfälle jemand bewusst nicht behandelt hat. Das sind die Teile einer Spec, die die Zeit eines Reviewers wert sind. Ein Review, das nur prüft, ob die Spec „richtig klingt“, ist also dasselbe Überfliegen, nur langsamer. Zwei Tests entscheiden, ob eine Spec überhaupt ein Review verdient: Sie sagt etwas, das der Code nicht sagen kann, und sie ist kürzer als der Code, den sie regelt. Eine Spec, die die Implementierung in Prosa nacherzählt, fällt beim ersten durch. Eine Spec für eine Änderung, die so klein ist, dass der Diff kürzer ist, fällt beim zweiten durch, und in beiden Fällen ist die Zeit besser in das Code-Review investiert. Eine Spec, die beide besteht, ist im ganzen Ablauf die billigste Stelle, um eine falsch verstandene Anforderung zu erwischen, weil auf dem Missverständnis noch nichts gebaut wurde.

Eine Spec aus Spec-driven Development ist nach dem Merge ein Dokument, das niemand mehr prüft

Nach der Auslieferung liest in Spec Kit nichts eine Spec erneut, solange niemand einen Befehl darauf richtet. Converge arbeitet auf einem Feature-Verzeichnis, und sein Template sagt, es sei „not a diff tool“: kein Git, kein Branch-Vergleich, keine Historie. Die Spec von Feature 003 wird geprüft, während Feature 003 gebaut wird. Wenn Feature 007 sechs Wochen später denselben Code ändert, vergleicht niemand diese Änderung mit der Spec von 003, es sei denn, jemand denkt daran.

Eine kleine Version davon habe ich in meinem eigenen Repository, ganz ohne Spec-Tool. Das Designdokument für die Mehrsprachigkeit dieser Website wurde am 2. Mai 2026 committet, mit einer Statuszeile ganz oben:

**Status:** Design validated, not yet implemented

Die Implementierung kam in Commits am selben Tag. Das Dokument hat seitdem keinen Commit mehr bekommen, behauptet also seit sechs Monaten in einem selbstbewussten Header etwas, das schon nach wenigen Stunden nicht mehr stimmte. Es ist ein schlichtes Designdokument, keine Spec, die irgendein Tool prüfen würde, und genau darum geht es: aufbewahrt und lesbar heißt nicht aktuell. Dasselbe Problem hat auch eine Memory-Datei, die niemand prüft.

Ein Agent, dem man sagt, er solle dieses Dokument als aktuellen Plan behandeln, würde von einem Zustand ausgehen, den es nicht mehr gibt. Spec Kit hat eine schärfere Version desselben Risikos. Würde jemand converge auf ein altes Feature-Verzeichnis richten, als wäre es die aktuelle Absicht, könnte spätere Arbeit, die davon abweicht, als contradicts- oder unrequested-Befunde zurückkommen, samt angehängten Tasks, um sie zu beheben. Für unrequested Arbeit sieht das Template einen sanfteren Weg vor, einen Task, sie zu prüfen oder zu begründen, und es löscht selbst nie Code, also wird nichts automatisch zurückgedreht. Der nächste Implement-Durchlauf würde aber mit diesen Tasks arbeiten, solange sie niemand vorher liest. Die Guides von Spec Kit sehen das. Das „main risk“ von flow-back ist „silent divergence“, und der Evolution-Guide bittet dich, keine Änderung im Code stehen zu lassen, die einer Spec widerspricht, die „meant to remain trustworthy“ ist, also vertrauenswürdig bleiben soll. Das Gewicht liegt auf „meant to“. Vertrauenswürdig ist eine Eigenschaft, die du pro Spec pflegen musst, und das Tool überlässt diese Arbeit dir.

Spec-driven Development nach der Auslieferung: Spec markieren, prüfen oder überführen

Nach dem Merge zählt, was aus jeder Spec wird. Ich sehe drei ehrliche Antworten.

Die erste behält die Spec als historisches Dokument und kennzeichnet sie so: was an diesem Datum beabsichtigt war, abgelöst von allem, was danach kam. Das ist Spec Kits Modell flow-forward und die ältere Disziplin der Architecture Decision Records, die datiert sind, einen Status tragen, als abgelöst markiert und nie in die Gegenwart umgeschrieben werden. Sicher wird das durch eine Regel: Kein Agent liest einen solchen Datensatz als aktuelle Absicht.

Die zweite hält die Spec aktuell, mit etwas, das sie bei jeder Änderung prüft, die ihr Feature berührt, nicht nur bei der Änderung, für die sie geschrieben wurde. Böckelers Definition von spec-anchored verlangt nur, dass die Spec behalten und für die Wartung genutzt wird, und ein Team, das Specs von Hand pflegt, erfüllt das. Meine strengere Anforderung ist eine Prüfung, die läuft, ohne dass jemand daran denken muss, sie zu starten, denn eine living spec, die nur durch gute Vorsätze aktuell bleibt, verfällt genauso wie die Statuszeile in meinem Designdokument.

Die dritte zieht die Spec nach der Auslieferung zurück und verlagert das Dauerhafte an eine Stelle, die jedes Mal gelesen wird. Das ist die Wahl, die Spec Kits Doku für das eigene Repository beschreibt: Die Constitution bleibt, die Feature-Specs verlassen die Versionskontrolle, und dauerhaftes Wissen lebt, in den Worten der Doku, „in design documents, documentation, tests, and contributor guidance.“ Eine Warnung zu diesem Ablageort. Eine Constitution ist eine Regeldatei, die ein Agent zu Beginn der Arbeit liest, dieselbe Art Objekt wie eine CLAUDE.md, und eine Regel, die ein Modell nur liest, wird abgewogen, nicht durchgesetzt. Konventionen und Geschmack gehören dorthin. Alles, was garantiert gelten muss, gehört in einen Test.

Gar nichts zu entscheiden ist schlimmer als jede der drei Varianten: Dann bleibt die Spec im Repository, ohne Status, den jemand pflegt, und jede künftige Session liest sie, als wäre sie noch der Plan.

Wenn du also gleich specify init ausführst oder deine erste Spec in Kiro anlegst: Leg das Persistenzmodell vor dem ersten Feature fest und schreib es in die Constitution, wie es Spec Kits eigener Guide vorschlägt. Steck die Review-Zeit in spec.md, bevor der Plan existiert, und zwar in die Ablehnungen und die ausgelassenen Randfälle statt in die Teile, die der Code ohnehin zeigen wird, denn das ist der früheste und billigste Punkt, an dem deine Korrektur den Agenten erreicht. Mein Designdokument hatte seinen Moment am 2. Mai. Alles, was es seitdem sagt, ist eine Statuszeile, die niemand aktualisiert hat.