Spec-Driven-Development-Workflow: Von der Anforderung zum Code

Der Agent erzeugt zwar Code, aber niemand kann später eindeutig erklären, welche Anforderung er erfüllt, welche Ausnahmefälle geprüft wurden oder warum bestimmte Dateien geändert wurden.

Die schnellste belastbare Lösung ist ein zweigleisiger Spec-Driven-Development-Workflow: Die Spezifikationsspur verwaltet Anforderungen, technische Grenzen und Abnahmekriterien; die Codespur setzt daraus kleine, prüfbare Aufgaben um. Beide Spuren werden über Versionsstand, Aufgaben-ID und Testergebnis verbunden, statt den AI Coding Agent einmalig aus einer groben Beschreibung eine komplette Anwendung erzeugen zu lassen.

Diese Arbeitsweise ist für Sie relevant, wenn Sie Spec-Driven Development in ein bestehendes Repository integrieren, mehrere Personen an AI-generiertem Code beteiligen oder einen entfernten Agenten über längere Zeit kontrolliert arbeiten lassen möchten. Wenn Sie nur ein kleines, isoliertes Skript ändern, wäre der vollständige Prozess dagegen wahrscheinlich überdimensioniert.

Warum die Trennung von Specification und Code entscheidend ist

In vielen Teams beginnt die Arbeit mit einem Ticket, einer Chat-Nachricht oder einem kurzen Satz wie „Fügen Sie einen Export hinzu“. Für einen Menschen kann der Kontext teilweise aus Gesprächen ergänzt werden. Ein AI Coding Agent besitzt diesen Kontext jedoch nicht automatisch. Er kennt häufig weder die nicht verhandelbaren Geschäftsregeln noch die Gründe, warum eine scheinbar einfache Änderung bestimmte Schnittstellen nicht berühren darf.

Daraus entstehen mindestens vier konkrete Risiken:

• Unklare Abnahmekriterien: Der Agent kann eine Funktion als fertig betrachten, obwohl nur der Normalfall funktioniert.
• Verdeckte Bereichserweiterung: Aus einem Export wird zusätzlich eine neue Datenstruktur, eine neue Authentifizierung oder eine nicht angeforderte Benutzeroberfläche.
• Nicht nachvollziehbare Architekturentscheidungen: Im Code ist später nicht erkennbar, ob eine Technologieanforderung aus der Specification stammt oder spontan vom Agenten gewählt wurde.
• Schwierige Wiederaufnahme: Nach einer Unterbrechung fehlt ein stabiler Zwischenstand. Der nächste Lauf beginnt erneut mit einer langen Zusammenfassung und kann bereits erledigte Arbeit überschreiben.

Die offizielle Dokumentation von Spec Kit beschreibt deshalb eine Abfolge aus Specification, technischer Planung, Aufgabenzerlegung und Implementierung. Jede Phase erzeugt ein eigenes Artefakt, das als strukturierter Kontext für die nächste Phase dient. Zur offiziellen Übersicht des Spec-Driven-Development-Prozesses

Der entscheidende Punkt ist nicht der Name eines bestimmten Werkzeugs, sondern die Übergabequalität zwischen den Phasen. Eine gute Specification ist kein längeres Ticket. Sie ist eine überprüfbare Vereinbarung darüber, welches Verhalten entsteht, welche Daten betroffen sind, welche Fehlerfälle gelten und was ausdrücklich außerhalb des Umfangs bleibt.

Erste Übergabe: Wie wird aus einer Anforderung eine Specification?

Eine unklare Anforderung sollte erst dann in eine Specification übergehen, wenn ihr Ergebnis anhand beobachtbarer Bedingungen beurteilt werden kann.

Beginnen Sie bei der Anforderungsprüfung nicht mit Dateien, Klassen oder Frameworks. Erheben Sie zunächst fünf Bestandteile:

1. Ziel und Nutzergruppe: Wer benötigt die Änderung und welches Problem soll danach anders gelöst werden?
2. Kernverhalten: Welche Handlung führt zu welchem beobachtbaren Ergebnis?
3. Daten und Zustände: Welche Eingaben, Zustandswechsel und Ausgaben sind relevant?
4. Ausschlüsse: Welche naheliegenden Erweiterungen gehören ausdrücklich nicht zu diesem Vorhaben?
5. Risiken und offene Punkte: Welche Regeln, Berechtigungen, Datenschutzfragen oder Abhängigkeiten müssen vor der Umsetzung geklärt werden?

Ordnen Sie anschließend jede Anforderung einer unveränderlichen ID zu, beispielsweise REQ-014. Die ID sollte in der Specification, im technischen Plan, in den Aufgaben und später in der Review-Beschreibung wieder auftauchen. Dadurch kann ein Reviewer nicht nur den Code lesen, sondern die Kette von der ursprünglichen Entscheidung bis zum Testergebnis verfolgen.

Eine brauchbare Specification enthält typischerweise:

• Nutzer- oder Systemverhalten;
• fachliche Regeln;
• Datenmodell und relevante Felder;
• Schnittstellen und erwartete Antworten;
• Fehler- und Ausnahmefälle;
• Berechtigungsgrenzen;
• messbare Akzeptanzkriterien;
• ausdrücklich nicht enthaltene Funktionen;
• offene Fragen mit verantwortlicher Person.

Wie unterscheiden sich Specification und technisches Design?

Die Specification beschreibt vor allem, was das System leisten muss und woran Sie die Erfüllung erkennen. Das technische Design beschreibt, wie das Repository diese Anforderungen umsetzt: etwa durch bestimmte Komponenten, Datenbankänderungen, Schnittstellen, Abhängigkeiten und Teststrategien.

Diese Trennung verhindert, dass eine technische Vorliebe stillschweigend zu einer Geschäftsanforderung wird. Wenn die Specification verlangt, dass ein Nutzer einen Export mit bestimmten Datensätzen erhält, schreibt sie nicht automatisch vor, welche Bibliothek oder welcher Service dafür eingesetzt werden muss. Die technische Planung darf diese Entscheidung treffen, muss sie aber begründen und gegen die vorhandenen Einschränkungen prüfen.

Bei unklaren Anforderungen sollte Ihr Agent zunächst Fragen stellen oder offene Punkte markieren, statt Annahmen als Tatsachen zu speichern. Die offizielle Referenz beschreibt für diesen Zweck einen eigenen Klärungsschritt vor der technischen Planung. Zur offiziellen Referenz für Specification, Klärung und Planung

Zweite Übergabe: Die Auswirkungen auf das Repository werden vorab sichtbar

Nach der freigegebenen Specification folgt die technische Planung. Sie ist die Brücke zwischen fachlicher Absicht und ausführbaren Aufgaben. Ihr Ziel ist nicht, bereits Code zu schreiben, sondern die Änderungsfläche sichtbar zu machen.

Prüfen Sie mindestens:

• betroffene Module und Einstiegspunkte;
• Datenbanktabellen, Migrationen und Rückwärtskompatibilität;
• öffentliche oder interne Schnittstellen;
• Konfigurationsdateien und Umgebungsvariablen;
• Abhängigkeiten und Lizenzrisiken;
• Authentifizierung, Autorisierung und Protokollierung;
• bestehende Tests, Testdaten und CI/CD-Prüfungen;
• Rollback- und Wiederherstellungsweg.

Ein technischer Plan sollte außerdem angeben, welche Entscheidungen noch menschliche Freigabe benötigen. Eine Änderung an einem internen Hilfsmodul kann der Agent oft selbstständig vorbereiten. Eine Änderung an einem Datenmodell, einem Berechtigungskonzept oder einem produktiven Migrationspfad sollte dagegen vor der Aufgabenzerlegung geprüft werden.

Die Übergabe ist freigegeben, wenn jede relevante technische Entscheidung mindestens einer Anforderung zugeordnet werden kann und keine kritische offene Frage unmarkiert bleibt. Wird dieser Zustand nicht erreicht, sollte der Agent nicht mit der Implementierung fortfahren. Kehren Sie stattdessen zur Specification oder zur Planung zurück.

Entscheidungshilfe für die Prozesswahl

Verwenden Sie die folgende Bedingungsliste, bevor Sie den vollständigen Ablauf starten:

• Wenn die Änderung mehrere Module, Datenflüsse oder Teams betrifft, wählen Sie den vollständigen zweigleisigen Workflow mit Specification, Plan, Aufgaben, Analyse und Review.
• Wenn die Änderung eine Datenmigration, Berechtigungslogik oder öffentliche Schnittstelle verändert, wählen Sie zusätzlich eine manuelle Freigabe nach der technischen Planung.
• Wenn der Agent länger als eine kurze lokale Sitzung arbeiten soll, wählen Sie kleine Aufgaben mit gespeicherten Checkpoints und reproduzierbaren Prüfkommandos.
• Wenn die Änderung nur eine klar begrenzte lokale Korrektur ohne neue Zustände betrifft, wählen Sie einen verkürzten Ablauf, dokumentieren Sie aber weiterhin Ziel, Test und Ausschluss.
• Wenn die Specification noch widersprüchliche Anforderungen enthält, wechseln Sie zurück zur Klärung, statt die Widersprüche in Aufgaben zu verteilen.
• Wenn das Repository keine sichere Umgebung für Agent-Ausführung besitzt, verschieben Sie die Automatisierung, bis Isolation, Zugriffsrechte und Protokollierung geklärt sind.

Dritte Übergabe: Wie groß sollten Agent-Aufgaben sein?

Ein AI Coding Agent sollte nicht „das Feature“ als eine einzige Aufgabe erhalten, sondern eine Reihe von Änderungen mit eindeutigem Umfang und eigener Prüfung.

Jede Aufgabe sollte mindestens folgende Felder enthalten:

Die optimale Größe hängt vom Repository und vom Risiko ab. Als Faustregel sollte eine Aufgabe so klein sein, dass ein Reviewer ihren Zweck aus dem Diff erkennen kann, aber nicht so klein, dass jede triviale Zeile eine eigene Übergabe benötigt. Eine Aufgabe für ein Datenmodell, eine Aufgabe für den zugehörigen Service und eine weitere Aufgabe für den Endpunkt kann sinnvoller sein als ein unteilbares Paket mit mehreren Schichten.

Die offizielle Spec-Kit-Dokumentation beschreibt Aufgaben mit Dateipfaden, Abhängigkeiten, parallelen Markierungen und Checkpoints. Zur offiziellen Beschreibung der Task-Erzeugung

Für lange Läufe ist ein Checkpoint besonders wichtig. Nach jeder fachlich geschlossenen Einheit sollte der Agent den aktuellen Stand, die ausgeführten Prüfungen und offene Punkte festhalten. Fällt die Sitzung aus oder verliert der Agent den Kontext, setzen Sie nicht am gesamten Vorhaben neu an, sondern am letzten verifizierten Zustand.

Ein guter Aufgabenabschluss sieht beispielsweise so aus:

• REQ-014 umgesetzt;
• Dateien und Diff kurz zusammengefasst;
• Testkommando ausgeführt;
• Ergebnis und relevante Warnungen dokumentiert;
• keine Änderungen außerhalb des definierten Bereichs;
• nächster Schritt eindeutig benannt.

Vierte Übergabe: Spec-Driven Development wird in Git verankert

Die Spezifikationsartefakte sollten nicht in einem separaten Notizsystem verschwinden, das vom Repository abgekoppelt ist. Sie müssen versioniert, reviewbar und gemeinsam mit der Änderung auffindbar sein.

Eine mögliche Struktur ist:

.specify/
  memory/
  templates/
specs/
  REQ-014-export/
    spec.md
    plan.md
    tasks.md
    analysis.md

Die konkrete Verzeichnisstruktur und die verfügbaren Befehle können sich je nach Version und Integration ändern. Prüfen Sie deshalb vor der Einführung immer die aktuelle Dokumentation und die Ausgabe der installierten CLI, anstatt eine ältere Anleitung unverändert zu übernehmen.

Für den Git-Prozess hat sich folgende Zuordnung bewährt:

1. Die Specification erhält eine eigene Änderung oder wird zusammen mit dem ersten Arbeitsstand versioniert.
2. Der technische Plan bleibt mit derselben Anforderungs-ID verbunden.
3. Jede Implementierungsaufgabe erzeugt einen nachvollziehbaren Commit oder Teil-Diff.
4. Der Pull Request verweist auf Specification, Plan, Aufgaben und Testergebnisse.
5. Nach Änderungen an der Anforderung werden Specification und Aufgaben zuerst aktualisiert.
6. Der Code wird erst danach erneut angepasst.

Welche Git-Übergabe ist für Teams am stabilsten?

Für kleine Änderungen kann ein gemeinsamer Feature-Branch mit einem Pull Request ausreichen. Bei größeren Vorhaben sind gestapelte, voneinander abhängige Pull Requests oft übersichtlicher: zuerst Datenmodell oder Fundament, danach Service, anschließend Oberfläche oder Integration. Die Review bleibt dadurch auf einen begrenzten Änderungsumfang konzentriert. Zur offiziellen Dokumentation über Pull Requests und gestapelte Änderungen

Vermeiden Sie, die komplette Specification erst im Nachhinein in den Pull Request zu kopieren. Dann kann niemand mehr zuverlässig unterscheiden, ob die Dokumentation die ursprüngliche Entscheidung oder nur den bereits geschriebenen Code beschreibt.

Fünfte Übergabe: Was muss der Code-Review zusätzlich prüfen?

Eine normale Codeprüfung bewertet Lesbarkeit, Tests, Sicherheit, Performance und Wartbarkeit. Im Spec-Driven-Development-Workflow kommt eine zweite Prüfdimension hinzu: die Übereinstimmung mit der Specification.

Der Reviewer sollte deshalb zwei Fragen getrennt beantworten:

Ist die Implementierung technisch akzeptabel?

Prüfen Sie unter anderem Fehlerbehandlung, Berechtigungen, Seiteneffekte, Abhängigkeiten, Testabdeckung und mögliche Rückwärtskompatibilität. Besonders kritisch sind Änderungen, die zwar den Hauptfall erfüllen, aber bei ungültigen Eingaben, fehlenden Datensätzen oder konkurrierenden Zuständen unklare Ergebnisse liefern.

Erfüllt die Implementierung tatsächlich die Specification?

Prüfen Sie jede betroffene Anforderungs-ID. Suchen Sie nach fehlenden Ausnahmewegen, stillschweigend veränderten Datenregeln und zusätzlichen Funktionen, die im Plan nicht freigegeben wurden. Ein sauberer Diff kann trotzdem fachlich falsch sein, wenn die falsche Interpretation der Anforderung konsequent umgesetzt wurde.

Der Agent sollte dem Review mindestens vier Informationen liefern:

• eine verständliche Diff-Zusammenfassung;
• Zuordnung der Änderungen zu Specification- und Aufgaben-IDs;
• ausgeführte Test-, Build- und Prüfkommandos;
• offene Punkte, bekannte Einschränkungen und bewusst nicht gelöste Probleme.

Die Review-Funktionen eines Pull Requests unterstützen Kommentare, konkrete Änderungsvorschläge, Freigaben und Rückweisungen. Diese Mechanismen sind jedoch nur dann wertvoll, wenn der Agent die fachliche Referenz mitliefert. Zur offiziellen Anleitung für Pull-Request-Reviews

Ein häufiger Fehler ist, nur den grünen Teststatus zu betrachten. Tests können erfolgreich sein, obwohl eine Ausnahmebedingung nie geprüft wird oder ein nicht angeforderter Bereich verändert wurde. Deshalb braucht die Review eine kleine Abdeckungsmatrix:

Sechste Übergabe: Die Specification bleibt nach dem Merge aktuell

Spec-Driven Development endet nicht mit dem erfolgreichen Merge. Sobald ein Fehler, eine neue Einschränkung oder ein geändertes Nutzerverhalten bekannt wird, muss zunächst entschieden werden, ob die Specification falsch, unvollständig oder inzwischen veraltet ist.

Die Reihenfolge sollte lauten:

1. Fehler oder neue Anforderung dokumentieren.
2. Betroffene Specification und Akzeptanzkriterien aktualisieren.
3. Auswirkungen auf Plan, Datenmodell und Tests prüfen.
4. Neue Aufgaben mit eigener ID erzeugen.
5. Agent nur auf den freigegebenen Änderungsumfang ansetzen.
6. Review erneut gegen Specification und Code durchführen.

Dadurch vermeiden Sie einen Zustand, in dem der Code zwar angepasst wurde, aber die zentrale Beschreibung weiterhin eine veraltete Regel enthält. Gerade bei Teams mit wechselnden Zuständigkeiten ist diese Rückschreibung wichtig, weil der nächste AI Coding Agent sonst auf widersprüchliche Informationen stößt.

Für eine zusätzliche Konsistenzprüfung kann ein Analyse-Schritt zwischen Aufgabenzerlegung und Implementierung eingesetzt werden. Die offizielle Referenz beschreibt dabei Prüfungen auf fehlende Zuordnungen, widersprüchliche Entscheidungen und Lücken zwischen spec.md, plan.md und tasks.md. Zur offiziellen Referenz für die Artefaktanalyse

Typische Schwachstellen bei der Einführung

Die Methode scheitert in der Praxis selten daran, dass ein Team keine Markdown-Dateien erzeugen kann. Häufiger liegen die Probleme in der Prozessdisziplin:

• Die Specification wird zu technisch: Dann ist nicht mehr erkennbar, welches Nutzerverhalten eigentlich geschützt werden soll.
• Der Plan wird nicht freigegeben: Kritische Architekturentscheidungen gelangen direkt in die Aufgabenzerlegung.
• Die Aufgaben sind zu groß: Der Agent verändert zu viele Dateien, und der Reviewer kann den Zusammenhang nicht mehr zuverlässig prüfen.
• Testergebnisse bleiben allgemein: „Tests erfolgreich“ reicht nicht, wenn das konkrete Kommando und der Umfang fehlen.
• Offene Punkte werden versteckt: Ungeklärte Berechtigungs- oder Datenschutzfragen werden als Annahmen umgesetzt.
• Die Dokumentation driftet vom Code weg: Nachträgliche Änderungen werden nur im Code vorgenommen.
• Der Remote-Arbeitsplatz ist nicht vorbereitet: Fehlende Isolation, unvollständige Logs oder unklare Zugriffsrechte machen die eigentliche Prozesskontrolle unmöglich.

Wenn Sie einen entfernten Agenten einsetzen, sollten Sie mindestens Repository-Isolation, Zugriff auf geheime Variablen, Log-Aufbewahrung, Wiederherstellung nach Sitzungsabbruch und sichere Reviewer-Zugänge prüfen. Für sensible Projekte sind zusätzlich DSGVO-Anforderungen, Datenminimierung und die Trennung von Test- und Produktionszugängen zu dokumentieren.

Wann lohnt sich eine entfernte Mac-Umgebung für diesen Workflow?

Der zweigleisige Prozess erzeugt mehr Zwischenartefakte als ein einzelner Prompt: Specification, Plan, Aufgaben, Diff, Testprotokoll und Review-Kommentare müssen verfügbar bleiben. Eine lokale Umgebung ist dafür oft ausreichend, wenn Ihr Team dauerhaft auf denselben Rechnern arbeitet und die Agent-Ausführung kurz sowie manuell überwacht bleibt.

Eine gemietete Mac-Umgebung kann sinnvoller sein, wenn Sie einen AI Coding Agent über längere Zeit laufen lassen, reproduzierbare Arbeitsplätze für mehrere Entwickler benötigen oder getrennte Test- und Review-Sitzungen aufbauen möchten. Entscheidend sind dabei nicht nur Rechenleistung und Betriebssystem, sondern Repository-Isolation, Protokollierung, Snapshot-Wiederherstellung und ein sicherer Zugang für Reviewer.

Wenn Sie diese Punkte vorab prüfen möchten, finden Sie im kvmboot Hilfe-Center den geeigneten Einstieg für Fragen zur Umgebung und zum Zugriff. Für einen konkreten zeitlich begrenzten Testlauf können Sie außerdem die verfügbaren Mac-Umgebungen für US East mit Ihren Anforderungen an Agent-Ausführung, Git-Zugriff und Review vergleichen.

Für eine langfristige, täglich stark ausgelastete Entwicklung ist der Kauf eigener Hardware häufig planbarer. Für einen zeitlich begrenzten Proof of Concept, eine Migration des Agent-Workflows oder die parallele Prüfung mehrerer Repository-Stände ist eine gemietete Umgebung dagegen oft die flexiblere Option. Entscheidend ist, dass die Umgebung die Übergaben zwischen Specification, Codeänderung und Review nicht unterbricht.

Der belastbare Spec-Driven-Development-Workflow besteht daher nicht aus einem einzelnen Agent-Befehl. Er ist ein kontrollierter Übergabeprozess: Anforderungen werden prüfbar, technische Auswirkungen werden vorab sichtbar, Aufgaben bleiben klein, Codeänderungen werden mit Tests verknüpft und jede spätere Änderung wird zuerst in die Specification zurückgeführt. Wenn Ihre aktuelle Umgebung dabei an fehlender Isolation, unvollständigen Logs, nicht reproduzierbaren Zuständen oder unsicherem Reviewer-Zugriff scheitert, sollten Sie genau diese Betriebsgrenzen vor der nächsten Agent-Aufgabe beheben.