Spec-Driven Development mit AI Coding Agent: Leitfaden

Der Gewinner ist Spec-Driven Development mit einem AI Coding Agent, sofern Anforderungen regelmäßig nachgebessert werden müssen, mehrere Dateien oder Personen beteiligt sind und die Abnahme nachvollziehbar bleiben soll. Entscheidend ist nicht eine besonders lange Anweisung, sondern die schrittweise Übersetzung von Absicht in Projektregeln, Specification, technische Planung, unabhängige Aufgaben und überprüfbare Nachweise.

Diese Anleitung richtet sich an:

• Einzelentwickler, die erzeugten Code nicht mehrmals vollständig korrigieren möchten;
• technische Verantwortliche, die AI Coding in einen kontrollierten Teamprozess einführen;
• Entwicklungsteams, die für Änderungen eine nachvollziehbare Verbindung zwischen Anforderung, Implementierung und Abnahme benötigen.

1. Zuerst die unveränderlichen Projektgrenzen festlegen

Ein AI Coding Agent arbeitet nicht nur mit der aktuellen Aufgabe. Er interpretiert zusätzlich Verzeichnisstruktur, vorhandene Abhängigkeiten, Konfigurationsdateien und bereits implementierte Muster. Wenn diese Regeln nur in einzelnen Prompts stehen, müssen sie bei jeder neuen Aufgabe wiederholt werden. Dabei entstehen widersprüchliche Anweisungen: Ein Prompt erlaubt eine Bibliothek, ein späterer verlangt eine möglichst kleine Abhängigkeit; eine Aufgabe fordert eine neue Schnittstelle, während eine ältere Datei nicht verändert werden darf.

Der erste Arbeitsschritt besteht deshalb aus einem dauerhaften Projektkontext. Dieser sollte mindestens folgende Punkte enthalten:

• verwendete Programmiersprachen, Laufzeitumgebungen und Build-Werkzeuge;
• erlaubte und verbotene Verzeichnisse;
• Regeln für Benennung, Modulgrenzen und öffentliche Schnittstellen;
• Sicherheitsgrenzen, etwa Umgang mit Zugangsdaten, personenbezogenen Daten und externen APIs;
• vorhandene Test-, Linting-, Formatierungs- und Paketierungsbefehle;
• Anforderungen an Logging, Fehlerbehandlung und Rückwärtskompatibilität;
• Definition of Done für Code, Tests, Dokumentation und Review.

Bei Spec Kit wird dieser Grundsatz durch eine projektweite „Constitution“ abgebildet. Die offizielle Referenz beschreibt sie als Leitlinie, gegen die spätere Spezifikationen und Pläne bewertet werden. Die Referenz nennt außerdem eine Abfolge aus constitution, specify, clarify, plan, checklist, tasks, analyze, implement und converge. (github.com)

Die Grenze zwischen stabiler Regel und featurebezogener Anforderung muss sauber bleiben. „Alle Eingaben werden validiert“ gehört in die Projektregeln. „Ein Benutzer kann eine Aufgabe archivieren“ gehört in die Specification. Wird beides vermischt, wird die Specification unnötig lang und verliert ihren Zweck als prüfbarer Vertrag.

Ausgangskontrolle vor der ersten Specification

• [ ] Die zulässigen Änderungsbereiche sind schriftlich festgelegt.
• [ ] Sicherheits- und Datenschutzgrenzen sind eindeutig formuliert.
• [ ] Jeder zentrale Test- und Prüf-Befehl ist bekannt.
• [ ] Die Definition of Done beschreibt ein überprüfbares Ergebnis.
• [ ] Der Agent erhält keinen Zugriff auf Geheimnisse, die für die Aufgabe nicht erforderlich sind.
• [ ] Die Projektregeln werden versioniert und nicht nur im Chatverlauf aufbewahrt.

Gerade beim Einsatz in Teams ist dieser Schritt wichtiger als eine bessere Prompt-Formulierung. Ein neuer Chat kann Projektregeln laden; ein verlorener Chatverlauf kann das nicht.

2. Danach das Nutzerziel als Specification formulierbar machen

Eine Specification beschreibt zuerst, was das System leisten soll und warum diese Funktion benötigt wird. Sie sollte nicht bereits jede Klasse, jedes Framework und jede interne Methode vorgeben. Die technische Lösung gehört in den späteren Plan, damit der Agent zwischen Nutzerziel und Implementierungsentscheidung unterscheiden kann.

Eine belastbare Specification enthält für jede wesentliche Funktion mindestens:

1. einen klar abgegrenzten Anwendungsfall;
2. die beteiligte Rolle oder den auslösenden Prozess;
3. gültige Eingaben und erwartete Ausgaben;
4. sichtbare Zustandsänderungen;
5. Fehler- und Grenzfälle;
6. relevante Sicherheits-, Datenschutz- oder Berechtigungsbedingungen;
7. Akzeptanzkriterien, die durch Test, Prüfung oder manuelle Kontrolle bewertbar sind.

Ein schwaches Kriterium lautet: „Die Suche soll schnell und benutzerfreundlich sein.“ Es ist weder eindeutig messbar noch ausreichend, um eine Abnahme zu begründen. Besser ist eine Beschreibung wie: „Bei leerem Suchfeld bleibt der bisherige Datensatz unverändert. Bei einem nicht gefundenen Begriff zeigt die Oberfläche einen klaren Leerzustand. Groß- und Kleinschreibung beeinflusst das Ergebnis nicht, sofern dies für die gewählte Suchlogik gilt.“

Damit wird nicht zwangsläufig eine konkrete Performance-Zahl behauptet. Die Specification definiert stattdessen ein beobachtbares Verhalten. Falls eine zeitliche oder mengenmäßige Grenze fachlich notwendig ist, muss sie aus einer belastbaren Produktanforderung oder einem Testplan stammen, nicht aus einer frei erfundenen Zahl.

Ein brauchbares Format für jede Kernanforderung

Bestandteil	Prüffrage	Typischer Nachweis
Verhalten	Was muss der Benutzer oder ein System beobachten?	Integrationstest oder manuelle Prüfung
Eingabe	Welche gültigen und ungültigen Eingaben gibt es?	Testfälle für Grenzwerte und Fehlermeldungen
Ausgabe	Welche Daten, Statuswerte oder Ereignisse entstehen?	API-Test, Snapshot oder Protokoll
Ausnahme	Was geschieht bei fehlenden Rechten, Konflikten oder Ausfällen?	Negativtest und Fehlerprotokoll
Abnahme	Woran erkennt ein Reviewer die Erfüllung?	Akzeptanzkriterium mit eindeutigem Ergebnis

Die Specification ist also kein Aufsatz über die Produktidee. Sie ist eine Sammlung von Aussagen, die später auf Code und Prüfungen zurückgeführt werden können. Bei unklaren Anforderungen sollte ein Agent zunächst Fragen stellen, statt vorschnell eine Architektur zu erzeugen. Spec Kit führt dafür einen eigenen Klärungsschritt vor der technischen Planung auf. (github.com)

3. Aus der Specification einen begrenzten technischen Plan ableiten

Erst nachdem die fachliche Absicht ausreichend klar ist, folgt die technische Planung. Der AI Coding Agent sollte dabei nicht nur eine Liste von Dateien ausgeben, sondern die Auswirkungen der geplanten Änderung erklären:

• Welche Module, Schnittstellen und Datenmodelle sind betroffen?
• Welche bestehenden Annahmen könnten durch die Änderung brechen?
• Welche Abhängigkeiten müssen vor einer anderen Änderung umgesetzt werden?
• Welche Teile können unabhängig getestet werden?
• Welche Entscheidungen sind reversibel und welche würden eine spätere Migration auslösen?
• Welche Testdaten und lokalen Voraussetzungen werden benötigt?

Ein guter Plan enthält außerdem eine Liste von ausdrücklich nicht betroffenen Bereichen. Diese Negativabgrenzung ist ein wirksamer Schutz gegen unnötige Änderungen. Wenn nur ein neuer API-Endpunkt benötigt wird, sollte der Plan etwa festhalten, dass Authentifizierung, Datenbankmigrationen und die bestehende Benutzeroberfläche unverändert bleiben, sofern kein Akzeptanzkriterium sie berührt.

Die offizielle Spec-Kit-Dokumentation trennt Specification und technische Planung ausdrücklich: In der Specification wird das Ziel beschrieben, während im Plan Technologie- und Architekturentscheidungen festgelegt werden. (github.com)

Der wichtigste Kontrollpunkt liegt zwischen Specification und Plan. Der Agent darf einen plausiblen Plan erstellen, aber die Annahmen darin sind noch keine automatisch genehmigten Anforderungen. Ein Review sollte jede größere Entscheidung auf drei Fragen prüfen:

• Erfüllt sie ein konkretes Akzeptanzkriterium?
• Verändert sie eine bestehende Grenze?
• Erzeugt sie zusätzliche Wartungs- oder Sicherheitskosten?

Wenn eine Entscheidung keine dieser Fragen beantworten kann, gehört sie möglicherweise nicht in den aktuellen Umfang.

4. Die Umsetzung in einzeln prüfbare Aufgaben zerlegen

Die Aufgabenliste ist die operative Schnittstelle zwischen Plan und Code. Sie darf nicht nur aus Überschriften wie „Backend bauen“ oder „Frontend anpassen“ bestehen. Solche Einträge sind zu groß, um Fortschritt oder Fehlerursache sauber zu bestimmen.

Eine ausführbare Aufgabe sollte folgende Informationen enthalten:

• eindeutige Kennung;
• Bezug zu einem Nutzerfall oder Akzeptanzkriterium;
• konkrete Datei, Schnittstelle oder Komponente;
• notwendige Abhängigkeiten;
• erwartetes Ergebnis;
• Prüf-Befehl oder manuelle Abnahme;
• Hinweis, ob eine parallele Bearbeitung sicher ist.

Spec Kit beschreibt für seine tasks.md unter anderem eine Organisation nach Nutzerfällen, eine Abhängigkeitsreihenfolge, parallele Aufgabenmarker und Dateipfade. Die offizielle Vorlage verwendet dafür ein strukturiertes Aufgabenformat mit Kennung, optionalem Parallelmarker und Bezug zur jeweiligen Story. (github.com)

Eine zu große Aufgabe könnte lauten: „Benutzerverwaltung vollständig implementieren.“ Eine besser kontrollierbare Zerlegung wäre:

1. Datenmodell für Benutzerstatus ergänzen;
2. Validierung für Statuswechsel hinzufügen;
3. Dienstmethode für den Statuswechsel implementieren;
4. API-Endpunkt mit Berechtigungsprüfung ergänzen;
5. Fehlerszenarien testen;
6. Oberfläche an den neuen Status anbinden;
7. End-to-End-Abnahme durchführen.

Jede Stufe besitzt einen eigenen Prüfpunkt. Wenn die Berechtigungsprüfung fehlschlägt, muss nicht die gesamte Benutzerverwaltung erneut analysiert werden. Der Rückfall erfolgt auf die betroffene Aufgabe oder auf das zugehörige Akzeptanzkriterium.

Kontrollliste für die Aufgabengenerierung

• [ ] Jede Aufgabe verweist auf mindestens eine konkrete Specification.
• [ ] Keine Aufgabe umfasst gleichzeitig mehrere unabhängige Nutzerfälle.
• [ ] Abhängigkeiten sind vor der Implementierung sichtbar.
• [ ] Dateipfade und Schnittstellen sind konkret genug für ein Review.
• [ ] Jede Aufgabe besitzt ein erwartetes Prüfergebnis.
• [ ] Parallele Aufgaben verändern keine gemeinsame Datei oder widersprüchliche Schnittstelle.
• [ ] Testaufgaben sind nicht erst nach dem gesamten Feature vorgesehen.

5. Den AI Coding Agent pro Durchlauf eng führen

Bei der eigentlichen Implementierung sollte der Agent nicht jedes Mal den gesamten Projektkontext erhalten. Zu viel Kontext erhöht die Wahrscheinlichkeit, dass alte Anforderungen, fremde Module oder nicht mehr gültige Annahmen in die aktuelle Änderung einfließen. Zu wenig Kontext führt dagegen zu lokalen Lösungen, die bestehende Schnittstellen verletzen.

Für jeden Durchlauf genügt ein kontrolliertes Paket aus:

• der aktuellen Aufgabe;
• den unmittelbar zugehörigen Abschnitten der Specification;
• dem relevanten Teil des Plans;
• betroffenen Dateien und Schnittstellen;
• den Projektregeln;
• den auszuführenden Prüf-Befehlen;
• bekannten Nicht-Zielen.

Vor der Änderung sollte der Agent seinen Plan in wenigen Punkten offenlegen: Welche Dateien werden geändert? Welche Annahme ist kritisch? Wie wird die Änderung geprüft? Danach sollte er ausschließlich den vorgesehenen Umfang bearbeiten. Nach der Änderung gehören Diff, Testergebnisse und verbleibende Unsicherheiten zur Übergabe.

Die Implementierung sollte in kleinen Rückkopplungen erfolgen:

1. Aufgabe auswählen und Abhängigkeiten prüfen.
2. Relevante Specification und Projektregeln laden.
3. Änderungsplan vom Agenten anfordern.
4. Plan gegen Nicht-Ziele und Schnittstellen prüfen.
5. Code ändern lassen.
6. Tests, statische Prüfungen und Formatierung ausführen.
7. Diff und Ergebnis gegen das Akzeptanzkriterium bewerten.
8. Aufgabe erst danach als erledigt markieren.

Für größere Features kann der Agent phasenweise arbeiten. Die offizielle Dokumentation beschreibt, dass implement entweder für alle Aufgaben oder begrenzt auf eine Phase ausgeführt werden kann. Ein vollständiger Arbeitszyklus kann zusätzlich eine Konsistenzanalyse und eine abschließende Konvergenzprüfung enthalten. (github.com)

6. Die Abnahme zurück auf die ursprüngliche Specification führen

Ein grüner Test bedeutet nicht automatisch, dass die fachliche Anforderung erfüllt ist. Ein Test kann die falsche Annahme bestätigen, eine Schnittstelle kann technisch funktionieren, aber eine Berechtigung falsch behandeln, und eine Oberfläche kann formal rendern, ohne den vorgesehenen Leerzustand abzubilden.

Die Abnahme sollte deshalb eine Rückverfolgbarkeit herstellen:

Specification	Implementierung	Nachweis	Status
Nutzerfall und Akzeptanzkriterium	betroffene Datei oder Schnittstelle	Test, Log oder manuelle Prüfung	offen / erfüllt
Fehlerfall	Validierung und Fehlerbehandlung	Negativtest	offen / erfüllt
Sicherheitsgrenze	Berechtigungs- oder Datenschutzprüfung	Test und Review	offen / erfüllt
Nicht-Ziel	unveränderte Bereiche	Diff- und Regressionsprüfung	geprüft

Für eine belastbare Abnahme werden mehrere Nachweisarten kombiniert:

• automatisierte Unit- und Integrationstests;
• statische Analyse, Linting und Formatprüfung;
• API-Beispiele mit gültigen und ungültigen Eingaben;
• manuelle Prüfung der Benutzerflüsse;
• Review des Diffs auf unerlaubte Nebenänderungen;
• Prüfung von Logs, Fehlercodes und Datenschutzverhalten.

Wenn ein Kriterium nicht erfüllt ist, sollte nicht sofort ein weiterer freier Prompt folgen. Zuerst ist zu bestimmen, ob die Ursache in der Specification, im Plan, in der Aufgabenzerlegung oder in der Implementierung liegt. Genau diese Unterscheidung verhindert, dass ein grundlegender Fehler durch immer neue lokale Korrekturen verschleiert wird.

7. Änderungen versionieren und den Prozess langfristig stabil halten

Eine Specification ist kein Dokument, das vor dem ersten Commit verschwindet. Sie entwickelt sich gemeinsam mit Code und Tests. Wird nur der Code geändert, bleibt die ursprüngliche Anforderung falsch oder unvollständig. Wird nur die Specification geändert, verliert die Implementierung ihre Nachvollziehbarkeit.

Bei einer Anforderungsänderung sollte die Reihenfolge deshalb lauten:

1. betroffene Specification und Akzeptanzkriterien ändern;
2. Auswirkungen auf Datenmodell, Schnittstellen, Sicherheit und Tests analysieren;
3. technischen Plan aktualisieren;
4. veraltete Aufgaben entfernen oder neu formulieren;
5. neue oder geänderte Tests festlegen;
6. Implementierung auf den geänderten Umfang begrenzen;
7. Abnahme erneut gegen die aktualisierte Specification durchführen.

Für umfangreiche Vorhaben ist eine Zerlegung in unabhängige Features sinnvoll. Spec Kit beschreibt dafür einzelne Feature-Verzeichnisse mit eigener spec.md, plan.md und tasks.md; eine Roadmap verbindet diese Teil-Specifications und hält deren Status nach. (github.com)

Zusätzlich sollte die aktive Feature-Zuordnung kontrolliert werden. Die Quickstart-Dokumentation beschreibt, dass Spec Kit den aktiven Feature-Pfad über .specify/feature.json verfolgt und dass ein einfacher Branch-Wechsel diese Zuordnung nicht automatisch ändern muss. (github.com) Das ist ein praktischer Fehlerpunkt: Wer nur den Git-Branch wechselt, aber den aktiven Feature-Kontext nicht prüft, kann neue Aufgaben im falschen Verzeichnis erzeugen.

Spec-Driven Development im Vergleich zu einer reinen Prompt-Arbeitsweise

Die folgende Gegenüberstellung hilft bei der Entscheidung, welcher Prozess für eine Änderung angemessen ist:

Kriterium	Freier Prompt-Prozess	Spec-Driven Development
Kontext	überwiegend im Chatverlauf	versionierte Regeln und Artefakte
Anforderungsprüfung	oft implizit	Akzeptanzkriterien und Checklisten
Aufgabenumfang	kann mehrere Module vermischen	abhängigkeitsorientierte Einzelschritte
Fehleranalyse	erneute Prompt-Korrekturen	Rückfall auf Specification, Plan oder Aufgabe
Teamübergabe	stark vom Gespräch abhängig	nachvollziehbare Dokumente und Diffs
Geeigneter Einsatz	kleine, isolierte Änderungen	mehrstufige oder risikoreiche Features

Für einen kleinen lokalen Fehler kann ein vollständiger Prozess unverhältnismäßig sein. Sobald jedoch mehrere Schnittstellen, Sicherheitsregeln, Teammitglieder oder wiederholte Agentenläufe beteiligt sind, überwiegt der Nutzen der zusätzlichen Artefakte. Die Methode ersetzt nicht das Review; sie macht sichtbar, was geprüft werden muss.

Entscheidung vor dem nächsten Agentenlauf

• [ ] Ist das Nutzerziel in beobachtbares Verhalten übersetzt?
• [ ] Sind gültige Eingaben, Fehlerfälle und Nicht-Ziele beschrieben?
• [ ] Ist klar, welche Regeln unveränderlich bleiben?
• [ ] Wurde der technische Plan von der fachlichen Specification getrennt?
• [ ] Sind Aufgaben klein genug, um einzeln getestet zu werden?
• [ ] Kann jede Änderung auf ein Akzeptanzkriterium zurückgeführt werden?
• [ ] Sind Testbefehle und manuelle Prüfungen vor dem Coding festgelegt?
• [ ] Werden Specification, Plan, Aufgaben und Tests gemeinsam versioniert?
• [ ] Ist nach einer Änderung eine neue Konsistenzprüfung vorgesehen?
• [ ] Existiert eine sauber zurücksetzbare Entwicklungsumgebung ohne unnötige Produktionsrechte?

Wer diese Liste nicht überwiegend abhaken kann, sollte den Agenten noch nicht implementieren lassen. In vielen Fällen ist eine fehlende Grenze oder ein unklarer Fehlerfall günstiger zu beheben als später ein größerer Codebestand.

Die benötigten Prüfungen hängen außerdem von der Entwicklungsumgebung ab. Wer einen AI Coding Agent in einer isolierten, reproduzierbaren Umgebung ausführt, kann Branches zurücksetzen, Tests wiederholen und Abhängigkeiten kontrollierter verwalten. Für Fragen zu verfügbaren Umgebungen und technischen Voraussetzungen bietet das Zutcloud Hilfezentrum einen passenden nächsten Anlaufpunkt. Die konkrete Auswahl sollte dabei von Zugriffsschutz, Testwerkzeugen, Repository-Anbindung und benötigten Apple- oder macOS-Komponenten abhängen; eine Mietumgebung ist nicht automatisch für dauerhaft hohe Last oder physische Gerätezugriffe geeignet.

Wer bisher auf einem wechselnden lokalen Rechner arbeitet, muss zusätzlich mit inkonsistenten Tool-Versionen, schwer reproduzierbaren Fehlern und manuellen Reset-Schritten rechnen. Eine temporär gemietete Mac-Umgebung von Zutcloud kann für Tests, Agent-Läufe und reproduzierbare Entwicklungsphasen sinnvoller sein, wenn kurzfristig ein klar abgegrenzter Rechner benötigt wird und keine langfristige Hardwarebindung gewünscht ist. Für die passende Einsatzregion und Variante können die Informationen zum Mac mini mieten herangezogen werden; vor dem Start sollten jedoch Repository-Zugriff, Datenschutzanforderungen, Testdauer und Rücksetzbedarf geprüft werden.

Häufige Fragen zu Specification und AI Coding

Wie beginnt ein sinnvoller Spec-Driven-Development-Prozess?

Der Prozess beginnt nicht mit einem möglichst langen Prompt, sondern mit stabilen Projektregeln. Dokumentieren Sie zunächst Technologieentscheidungen, Verzeichnisgrenzen, Sicherheitsvorgaben, Testbefehle und die Definition of Done. Danach wird ein begrenztes Nutzerziel als Specification beschrieben. Erst wenn offene Punkte geklärt und prüfbare Akzeptanzkriterien vorhanden sind, sollte der AI Coding Agent einen technischen Plan erzeugen.

Wie detailliert muss eine Specification für einen AI Coding Agent sein?

Eine Specification muss so konkret sein, dass Verhalten, Eingaben, Ausgaben, Fehlerfälle und relevante Qualitätsanforderungen geprüft werden können. Sie muss jedoch nicht jede Datei oder Klasse vorwegnehmen. Gute Specifications beschreiben das gewünschte Ergebnis und seine Grenzen; Architektur, Technologie und Dateipfade werden anschließend im Plan festgelegt. Unprüfbare Formulierungen sollten ersetzt werden.

Wie zerlegt ein AI Coding Agent eine Specification in Aufgaben?

Zuerst sollte der Agent aus der Specification einen technischen Plan mit Abhängigkeiten und betroffenen Komponenten ableiten. Danach wird jede Nutzerfunktion in kleine, einzeln implementier- und testbare Aufgaben zerlegt. Jede Aufgabe benötigt einen eindeutigen Zweck, betroffene Dateien oder Schnittstellen, eine Abhängigkeit und ein überprüfbares Ergebnis. Große Querschnittsänderungen werden in mehrere Kontrollpunkte aufgeteilt.

Wie verhindert man nach einer Specification-Änderung unkontrollierte Codeänderungen?

Ändern Sie zuerst die Specification und dokumentieren Sie die betroffenen Akzeptanzkriterien, Schnittstellen und Aufgaben. Lassen Sie anschließend die Konsistenz zwischen Specification, Plan und Aufgabenliste prüfen. Erst danach darf der Agent den Code aktualisieren. Nicht mehr gültige Aufgaben werden entfernt oder ersetzt, statt durch zusätzliche Hinweise überdeckt zu werden. Tests und Abnahmekriterien müssen mit der Änderung weiterentwickelt werden.

Weiterlesen

• Parallele AI-Coding-Workflows mit klaren Aufgaben, Tests und kontrollierten Zusammenführungen
• Projektregeln, wiederverwendbare Abläufe und Gedächtnisschichten für Coding Agents