Spec-Driven Development mit Spec Kit – ein Erfahrungsbericht

Disziplinierter Code mit KI, ohne sich im Vibe-Coding zu verlieren

Worum es geht

KI-Coding-Agenten sind schnell – und genau das ist das Problem. Man tippt einen Wunsch, der Agent schreibt drauflos, und nach ein paar Runden hat man einen Berg Code, den niemand mehr durchschaut. „Vibe-Coding" nennt sich das: vorne reinreden, hinten kommt irgendwas raus, und die Architektur entsteht zufällig statt absichtlich. Bei Wegwerf-Prototypen ist das egal. Bei allem, was länger leben soll, ist es ein Drama.

Spec-Driven Development (SDD) ist die Gegenbewegung. Die Idee in einem Satz: Nicht mit Code anfangen, sondern mit einer Spezifikation – und den Code als Ergebnis der Spec behandeln, nicht umgekehrt. Die Spec ist die Wahrheit, der Code zieht nach.

Dieser Artikel ist ein Erfahrungsbericht von der Pieke auf: was SDD ist, wofür es taugt, wie sich das Werkzeug Spec Kit dabei anfühlt, und wo der Mensch trotz aller Automatik die Verantwortung behält.

Was SDD von „Compound Engineering" abgrenzt

Vorab eine faire Einordnung. Ansätze wie „Compound Engineering" haben durchaus ihren Reiz: der Gedanke eines selbstverstärkenden Loops, in dem die KI aus jeder Aufgabe lernt und immer besser wird. Gerade zum Start hat das einen ausgeprägten Coaching-Charakter – eine Brainstorm-Phase, die dich im Dialog Frage für Frage durch Zweck, Nutzer und Rahmenbedingungen führt und das Projekt erst mal auf hoher Ebene beschreibt, etwa rund um den Produktnutzen, bevor überhaupt Code entsteht. Für ganz neue Projekte, in denen man ohnehin experimentiert und die Idee noch formt, kann das ein starker Beschleuniger sein. Mein Eindruck ist nur: Die Ansätze sind komplexer, und die Frameworks dahinter werden noch oft erweitert und verändert. Mir fehlt da die Stabilität, die ich für echte, langfristig produktive Projekte brauche. Genau diese Greifbarkeit und Verlässlichkeit bringt SDD mit.

SDD ist das Gegenteil von vage. Es ist kein Versprechen, sondern ein Ablauf mit festen Phasen und prüfbaren Artefakten. Jede Phase hat ein klares Ziel, einen klaren Output und einen Punkt, an dem du als Mensch draufschaust. Statt eines magischen Loops bekommst du eine Pipeline, die du verstehst und kontrollierst.

Warum SDD gerade für Legacy-Projekte stark ist

Ein Punkt, der oft untergeht: SDD ist nicht nur für die grüne Wiese. Gerade bei Altprojekten spielt es seine Stärke aus.

Ein neun Jahre alter Codebestand mit fehlender Doku, fehlender Testabdeckung und gewachsenen Architekturfehlern ist genau der Fall, an dem sich ein KI-Agent „aufhängt" – zu viel verwobener Kontext auf einmal. SDD zwingt dich, das in kleine, abgeschlossene Iterationen zu schneiden. Und es erlaubt einen umgekehrten Einstieg: Statt zu beschreiben, was du bauen willst, lässt du die Spezifikations-Phase beschreiben, was der Code heute tut – Reverse-Engineering des Ist-Verhaltens als erste Dokumentation. Daraus entsteht überhaupt erst die Grundlage, um sicher zu refactoren.

Die bewährte Reihenfolge bei Legacy: erst verstehen und dokumentieren, dann ein Sicherheitsnetz aus Tests (die das aktuelle Verhalten einfangen – Warzen inklusive), dann in kleinen Schnitten refactoren, und erst danach die großen Dependency- und Plattform-Migrationen. Jede Scheibe eine eigene Iteration.

Spec Kit: Phasen wie Build-Goals

Das Werkzeug, das diesen Ablauf greifbar macht, ist Spec Kit (von GitHub, agent-neutral, läuft mit verschiedenen Agenten). Wer Maven oder Cargo kennt, hat sofort das richtige mentale Bild: So wie mvn über definierte Lifecycle-Phasen läuft (validate, compile, test, package …), läuft Spec Kit über definierte Phasen. Sie heißen nur anders und werden als Slash-Commands aufgerufen.

Der Kern-Ablauf:

Phase Befehl Was passiert Output
Verfassung /speckit.constitution Nicht-verhandelbare Prinzipien, projektweit .specify/memory/constitution.md
Spezifizieren /speckit.specify Beschreibt WAS – User Stories, Akzeptanzkriterien specs/NNN-name/spec.md
Planen /speckit.plan Beschreibt WIE – Architektur, Datenmodell plan.md (+ research, data-model, contracts)
Aufgaben /speckit.tasks Dröselt den Plan in kleine, geordnete Schritte tasks.md
Analysieren /speckit.analyze Read-only Konsistenz-Check über spec/plan/tasks nur Report
Umsetzen /speckit.implement Schreibt den echten Code Code + Dateien

Der entscheidende Punkt, den man verinnerlichen muss: Jede Phase erzeugt ein Artefakt – ein Dokument oder Code. Der Chat-Verlauf ist Wegwerf-Ware. Die .md-Dateien sind die Wahrheit. Das ist der Unterschied zwischen „ich habe mit der KI geredet" und „ich habe eine nachvollziehbare Spezifikation".

Und es gibt eine klare Trennlinie, die man nicht verwischen darf: specify = WAS (ohne Techstack!), plan = WIE (jetzt kommt der Techstack rein). Rutscht beim Spezifizieren schon Technik rein, gehört sie raus – sie kommt erst im Plan.

Die Installation ist eine Sache von Minuten:

# Spec Kit global installieren (NICHT von PyPI – nur aus dem Repo)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Im Projekt-Repo initialisieren
specify init . --integration <dein-agent>

Architektur in der Constitution festschreiben

Die constitution.md ist für mich das stärkste Stück an Spec Kit. Hier beschreibst du die projektweiten, nicht-verhandelbaren Prinzipien – und zwar einmal, gültig für alle künftigen Iterationen. Architektur-Schichtung, erlaubte Abhängigkeitsrichtungen, verbindliche Begriffe (Ubiquitous Language), Qualitäts-Gates.

Genau hier sicherst du deine Architektur ab: Schichtungsregeln und die verbindlichen Begriffe für dein Projekt schreibst du in die Constitution – und jede Phase referenziert sie. Der Agent driftet dann nicht mehr zwischen verschiedenen Begriffen für dasselbe Konzept.

Wichtig dabei: Die constitution.md pflegst du möglichst über den Command, nicht primär von Hand. Du rufst /speckit.constitution mit deinen Prinzipien auf, und der Command schreibt sie nicht nur in die Verfassung, sondern synchronisiert auch die Templates (plan, spec, tasks). So bekommt jeder künftige Plan automatisch einen Prüf-Punkt für deine Regel. Prinzip rein → Templates ziehen nach. Manuell nachschärfen darfst du natürlich trotzdem – Überflüssiges rauslöschen, ergänzen, eine Formulierung glattziehen. Nur die große Struktur und die Template-Synchronisation überlässt du besser dem Command.

Wo welche Regel hingehört

Geltungsbereich Ort
Gilt für alle Specs, dauerhaft (z. B. „Schichtung per ArchUnit", „Build muss grün sein") constitution.md
Gilt nur für diese eine Iteration (z. B. „hier Library X") plan.md der Iteration

Weiche Regel vs. harter Riegel

Eine ehrliche Einschränkung, die man kennen muss: Eine Regel in der Constitution ist erst mal nur eine Absicht. Der Agent soll sie befolgen – aber „soll" ist genau das, was beim Vibe-Coding ausbricht. Ein Markdown-Satz ist eine weiche Grenze.

Wirklich erzwungen wird eine Regel erst, wenn sie mechanisch im Weg steht. Beispiel „Build muss grün sein vor Abschluss":

  1. Deklarieren – per /speckit.constitution als Prinzip festschreiben. Weich.
  2. Zur Pflicht-Task machen – die tasks.md bekommt einen finalen Schritt „Build ausführen, muss grün sein". Härter.
  3. Mechanisch erzwingen – ein pre-commit-Hook (oder besser: die CI-Pipeline), der den Build laufen lässt und den Commit bei Fehler physisch blockiert. Unausbrechbar.

Die Maven-Analogie zu Ende gedacht: So wie ein roter Test kein .jar erzeugt, erzeugt ein roter Build keinen Commit. Da kann kein Agent „ausbrechen", weil das Versionskontrollsystem selbst Nein sagt – egal, was in der Constitution steht.

Die Arbeitsteilung ist also: Die Constitution deklariert, der Build/Hook erzwingt. Erst beide zusammen sind dicht. Wer reine Architektur-Regeln (etwa Schichtgrenzen) wirklich hart machen will, kombiniert das mit Werkzeugen wie ArchUnit und einem Multi-Modul-Schnitt, bei dem die falschen Abhängigkeiten gar nicht erst kompilieren.

Der Mensch prüft jede Phase

Zwischen jeder Phase steht ein Review-Gate. Reviewen tut man beim Vibe-Coding auch. Der Unterschied liegt darin, wogegen geprüft wird: bei SDD gegen ein festgehaltenes Artefakt (Spec, Plan, Tasks), das die Erwartung dokumentiert, statt gegen die eigene Erinnerung an das, was man wollte.

Nach /speckit.specify liest du die Spec und korrigierst sie – der Agent rät teilweise, du weißt es besser. Nach /speckit.plan prüfst du, ob der Techstack und die Architektur stimmen. Die tasks.md reviewst du wie einen Pull Request: löschen, umsortieren, kürzen. Und nach /speckit.implement gehst du den Diff durch, bevor irgendetwas committet wird. Kein Auto-Commit.

Das Schöne: Du kannst nach jeder Phase das erzeugte Artefakt manuell anpassen. Die Spec ist zu geschwätzig? Kürzen. Der Plan hat einen Edge Case vergessen? Ergänzen. Die Tasks sind zu kleinteilig? Zusammenfassen. Spec Kit zwingt dir nichts auf – es liefert einen Vorschlag, du behältst die Kontrolle.

Und wenn dir das Tool generell zu viel Zeremonie erzeugt (etwa ein Datenmodell für reine Doku), wirkst du über zwei Hebel gegen: über die Templates (was generell erzeugt wird) oder über die Constitution (was projektweit gilt).

Den Agenten zur Knappheit erziehen

Ein praktischer Tipp, der die Lesbarkeit aller Artefakte enorm verbessert: In der AGENTS.md (der dauerhaften Kontext-Datei) gibst du dem Agenten explizit vor, sich kurz zu fassen. Weniger Fließtext, mehr Stichpunkte, Listen und Tabellen. Kein „KI-Geschwätz", keine ausschweifenden Einleitungen, keine Wiederholungen.

Das macht einen riesigen Unterschied. Specs und Pläne, die in knappen Stichpunkten formuliert sind, kannst du in Sekunden überfliegen und reviewen. Drei Absätze Prosa für eine Sache, die in einem Satz steht, kosten dich nur Zeit beim Gegenlesen.

Modellwahl je nach Phase

Ein unterschätzter Effizienz- und Kostenhebel: Nicht jede Phase braucht das stärkste Modell.

Das Planen (/speckit.plan) und das Aufstellen der Architektur profitieren von einem starken Modell – hier werden die wichtigen Weichen gestellt, hier zahlt sich Denkleistung aus. Das Umsetzen (/speckit.implement) dagegen ist oft mechanisches Abarbeiten klar formulierter Tasks – da reicht häufig ein günstigeres, schnelleres Modell. Trivialkram wie Commit-Messages oder Boilerplate kann sogar ein lokales Modell erledigen.

Da viele Agenten den Modellwechsel pro Aufruf erlauben, lässt sich das gezielt steuern: teure Denkleistung nur, wo sie gebraucht wird. Das drückt die Token-Kosten spürbar – und die sind bei SDD ohnehin etwas höher (~20–40 %), weil jede Phase die Artefakte neu einliest.

Was tun, wenn es schiefgeht

Realismus: Es läuft nicht immer durch. Der Smoketest schlägt fehl, ein Test fehlt, die Implementierung passt nicht. Die wichtigste Regel dabei:

Du fixt nicht still den Code von Hand. Du gehst zur richtigen Phase zurück, korrigierst dort das Artefakt und lässt von dort neu fließen. Sonst driften Code und Spec auseinander – und genau das wolltest du ja vermeiden.

Die Diagnose-Frage bei jedem Fehlschlag lautet: Auf welcher Ebene sitzt der Fehler?

Ebene Symptom Zurück zu
Umsetzung Plan + Tasks waren richtig, Umsetzung schlampig /speckit.implement mit präzisem Hinweis
Test fehlt Kein Test deckt den Fall ab /speckit.tasks (Test-Task ergänzen)
Plan lückenhaft Plan hat Edge Case übersehen /speckit.plan ergänzen, dann tasks neu
Spec falsch Ergebnis erfüllt die Spec, aber die Spec war falsch /speckit.specify (Bestellfehler)

In ~90 % der Fälle ist es die unterste Ebene – nochmal implementieren mit einem präzisen Hinweis. Den ganzen Weg hoch bis zur Spec geht man selten: nur, wenn man beim Testen merkt, dass man das Falsche bestellt hat. Der eigentliche Skill ist, schnell zu unterscheiden: Umsetzungsfehler oder Bestellfehler?

Zwei Befehle helfen bei der Diagnose: /speckit.analyze zeigt, wo spec, plan und tasks auseinanderlaufen. /speckit.converge vergleicht den tatsächlichen Codestand gegen die Artefakte und hängt Fehlendes als Tasks an – besonders wertvoll bei Legacy und nach manuellen Eingriffen.

Agent, Mensch oder beides – Spec Kit ist egal, wer tippt

Hier kommt der Punkt, der für erfahrene Entwickler entscheidend ist: Spec Kit ist agnostisch dazu, wer den Code schreibt. Es prüft nur das Ergebnis – Tasks erfüllt, Build grün, Tests grün. Ob der Code vom Agenten, von dir oder gemischt kommt, ist ihm gleich.

Das ist befreiend. Wenn du eine Sache in Java besser und sauberer kannst als jedes Modell – Konfigurationsaufbau, Strukturanpassung, das Aufräumen einer aufgeblähten Klasse – dann machst du das selbst. Drei Wege stehen offen:

  • Implement überspringen und die tasks.md selbst abarbeiten. Die Task-Liste ist dann deine Checkliste.
  • Hybrid: Der Agent macht den Rohbau, du räumst im Review auf. Das ist kein Regelbruch – das ist das vorgesehene Review-Gate.
  • Spec Kit gar nicht nutzen für Kleinkram. „Start vibe, finish spec-driven" – für einen Tippfehler braucht niemand eine Spezifikation.

Die einzige Disziplin dabei: Wenn du beim manuellen Aufräumen das Wie strukturell änderst, zieh das Artefakt nach (oder lass /speckit.converge dir zeigen, was nachzuziehen ist). Sonst beschreibt dein Plan beim nächsten Durchlauf einen falschen Stand.

Die Quintessenz: Spec Kit definiert WAS und WARUM und prüft das Ergebnis. Das WIE der Code entsteht, bleibt offen. Und genau beim Wie ist die Erfahrung eines echten Entwicklers der Mehrwert: der Agent für den Rohbau und das Breitbeinige, der Mensch für Qualität, Struktur und die Feinheiten.

Den KI-Output wirklich reviewen – der Hunk-Editor

Das Review-Gate ist nur so gut wie dein Werkzeug, um Änderungen zu prüfen. Den Diff zeilenweise durchzugehen und Block für Block zu entscheiden, was rein darf, ist die eigentliche Kontrolle – nicht das pauschale „sieht gut aus".

Wer in IntelliJ IDEA arbeitet, hat das schon eingebaut: Im Commit-Fenster siehst du jede Änderung als Diff und kannst sie pro Block (Hunk) annehmen oder verwerfen. Genau dort prüfst du, was die KI fabriziert hat, bevor es in den Commit geht.

Für VS Code lohnt sich ein Blick auf Extensions wie Hunkwise oder Diff-Reviewer, die ein vergleichbares Hunk-weises Review-Erlebnis bringen.

Egal welches Werkzeug: Der Mensch hat die Verantwortung. Die KI schlägt vor – du entscheidest, was committet wird.

Fazit

SDD mit Spec Kit ist kein magischer Loop, der alles von allein besser macht. Es ist ein diszipliniertes Gerüst, um mit KI guten Code zu schreiben, ohne im Vibe-Coding zu versinken – und es lässt jederzeit Raum für manuelle Eingriffe.

Die Stärken aus der Praxis:

  • Struktur statt Zufall – feste Phasen mit prüfbaren Artefakten, wie Build-Goals bei Maven oder Cargo.
  • Architektur per Constitution – projektweite Regeln, die jede Phase referenziert; hart gemacht durch Build-Gates statt nur durch Prosa.
  • Mensch im Gate – nach jeder Phase prüfst, kürzt und korrigierst du. Kein Auto-Commit.
  • Flexibel bei der Umsetzung – Agent, Mensch oder beides; starke Modelle fürs Planen, günstige fürs Umsetzen.
  • Gut für Legacy – Ist-Verhalten spezifizieren, in kleinen Iterationen refactoren, Netz aus Tests darunter.

Der wichtigste Satz zum Schluss: Die KI schreibt schnell, aber die Verantwortung bleibt beim Menschen. SDD gibt dir die Struktur, diese Verantwortung auch tatsächlich auszuüben – Phase für Phase, Diff für Diff.

Letzte Aktualisierung: Juli 2026 · Feedback und Korrekturen willkommen!