Best Practices: Feature-Spezifikation

Feature-Spezifikationen bilden die Grundlage für AI-Driven Development. Der Beitrag zeigt sinnvolle Inhalte, die Abgrenzung zu Datenmodell und Implementierungsplan sowie die Pflege als Documentation as Code.

---

Einleitung

Selbstverständlich sind Feature-Spezifikationen keine Erfindung des AI-Driven-Developments. Idealerweise verwendet jeder Entwicklungsprozess dokumentierte Anforderungen als Ausgangspunkt der Umsetzung. So selbstverständlich, wie das klingt, ist es aber leider nicht. Auch heute noch haben viele Projekte genau deshalb Probleme, weil die Anforderungen unklar, unvollständig oder schwer zugänglich sind. Oder Projekte verzichten ganz auf separat dokumentierte Anforderungen, oft mit der Begründung, man habe einen agilen Prozess und ein Ticketsystem. Tickets können zwar auch Anforderungen enthalten, aber in der Praxis werden sie oft nicht als solche behandelt und die saubere Dokumentation der Anforderungen bleibt auf der Strecke.

Sobald man sich entscheidet, auf AI-Driven Development zu setzen, funktioniert die Abkürzung des Prozesses über minimal dokumentierte Tickets nicht mehr. Feature-Spezifikationen bilden zusammen mit dem semantischen Datenmodell die Grundlage für die Kommunikation mit den Agenten. Ohne sauber dokumentierte Anforderungen funktioniert auch die Erstellung der Implementierungspläne nicht und am Ende entsteht fehlerhafter oder unvollständiger Code. Man könnte durchaus argumentieren, dass alleine diese Tatsache schon die Einführung eines AI-Driven-Development-Prozesses rechtfertigt.

Was ist eine Feature-Spezifikation?

Eine Feature-Spezifikation ist ein für Menschen und Agenten gleichermaßen leicht zu lesendes Dokument. Ich empfehle, sie als Markdown-Datei in einem Repository abzulegen. In kleineren Projekten liegt sie zusammen mit dem Code, in großen Vorhaben lohnt sich ein separates Spezifikations-Repository. Sie beschreibt das Verhalten für einen zusammenhängenden Teilaspekt des Zielsystems: für wen, was passieren soll, was nicht passieren darf und woran wir erkennen, dass es fertig ist.

Feature-Dateien können mit Hilfe von Agenten erstellt werden, müssen aber ausnahmslos von Menschen als Human-in-the-Loop (HITL) geprüft und freigegeben werden. Agenten können fachlich falsche Anforderungen zumindest Stand Herbst 2026 nicht erkennen und hinterfragen sie daher nicht.

Das heißt übrigens nicht, dass ich für jede kleine Änderung eine Feature-Datei anlege. Für einen Tippfehler, eine Textänderung oder einen kleineren Bugfix reicht tatsächlich ein simples Ticket. Hier ist etwas Augenmaß gefragt. AIDD bedeutet nicht, den nächsten schwergewichtigen Prozess zu etablieren, ganz im Gegenteil. Die immer mächtiger werdenden Agenten ermöglichen schnelle Zyklen, Bugfixes und kontinuierliche Verbesserungen. Eine Feature-Datei schreibe ich, wenn neues beobachtbares Verhalten hinzukommt oder bestehendes Verhalten sich so ändert, dass es Stakeholder erkennen würden.

Unterschiede zu anderen Dokumentarten

Ich unterscheide in einem AIDD-Prozess zwischen vier Arten von Dokumenten:

• Feature-Spezifikation (Was / Warum). Beschreibt das Verhalten des Systems an der UI- oder API-Grenze. Wichtige Inhalte und eine empfehlenswerte Struktur beschreibe ich weiter unten noch ausführlich.
• Semantisches Datenmodell (Was / Glossar). Entitäten, Attribute, Typen, Beziehungen, Enumerationen, DSGVO-Kennzeichnungen, Domänenregeln. Das SDM ist das Glossar, auf das sich die Feature-Spezifikation stützt.
• Architekturdokumentation (Wie / High-Level). Grundlegende Architekturentscheidungen, Schichten, Schnittstellen, Integrationspunkte, nicht-funktionale Anforderungen. Der Agent wird diese Informationen nutzen, um den Implementierungsplan zu erstellen, aber die Architekturdokumentation ist unabhängig von einzelnen Features.
• Implementierungsplan (Wie / Low-Level). Implementierungsschritte, Teststrategie, In-Scope, Out-of-Scope, Entscheidungen, die der Agent nicht allein treffen kann. Eine Spezifikation kann auch zu mehreren Implementierungsplänen führen, je nach Umfang oder Modulgrenzen.

Für das Survey-Management-Beispiel, das ich schon für einige Beiträge im Blog verwendet habe, sieht die Trennung so aus: Die Feature-Spezifikation sagt, dass eine Administratorin eine Umfrage mit Titel und Ersteller anlegen, geordnete Fragen definierter Typen hinzufügen und eine Umfrage inklusive abhängiger Daten löschen kann. Das semantische Datenmodell sagt, was eine Question ist und welche Werte QuestionTypeEnum kennt. Die Architekturdokumentation erläutert den grundlegenden Aufbau des Service inklusive der umzusetzenden Schichten. Der Implementierungsplan sagt, dass wir zuerst Persistenz bauen, dann Repositories, dann die Service-Schicht, dann die REST-API und wie das alles über Tests abgesichert werden soll.

Inhalt und Struktur

Auch für den Inhalt und die Struktur einer Feature-Spezifikation gilt das oben Gesagte: Man muss für einen AIDD-Prozess das Rad nicht neu erfinden. Es gibt unzählige Varianten, Vorlagen und Best Practices zur Erfassung und Dokumentation von Anforderungen. Wichtig ist aus meiner Sicht nur, dass das Ergebnis sowohl für Menschen als auch für Agenten verständlich ist.

Ein aus meiner Sicht eher negatives Beispiel ist die Verwendung von EARS (Easy Approach to Requirements Syntax) für die Dokumentation von Anforderungen, wie das von Amazon Kiro propagiert und umgesetzt wird. Die Idee dahinter ist auf den ersten Blick naheliegend: Man nutzt eine strukturierte Syntax, um Anforderungen präzise, unmissverständlich und testbar zu formulieren. Agenten sollen sich dadurch, so zumindest die Hoffnung, leichter tun, die Anforderungen korrekt zu verstehen. Doch obwohl EARS ursprünglich für Menschen entwickelt wurde, ist die Syntax aus meiner Sicht für menschliche Stakeholder schwer lesbar. Diese Zielgruppe im Projekt ist in vielen Fällen sowieso mit vielen fachlichen Reviews und der Dokumentation von Anforderungen belastet. Eine umständliche Syntax wie EARS macht diese Aufgabe nicht leichter und die Gefahr ist groß, dass Schattendokumente mit denselben Anforderungen im “normalen” Fließtext entstehen.

Was bei mir funktioniert, ist die Dokumentation der Anforderungen in normaler Prosa im Markdown-Format und in der Sprache des Projekts (Deutsch in einem deutschen Team, Englisch in einem internationalen Team). Früher hatte ich den Eindruck, dass sich die Modelle mit Englisch grundsätzlich leichter tun, und habe deshalb diese Sprache bevorzugt. Das ist bei den neuen Frontier-Modellen aus meiner Sicht nicht mehr der Fall. Wichtig ist, dass alle projektrelevanten Fachbegriffe konsistent zum semantischen Datenmodell sind, das ja als Glossar dient. Verwendet man im SDM Englisch für die Entitäten und schreibt die Features auf Deutsch, werden trotzdem die englischen Entitäten, Attribute usw. aus dem SDM verwendet. Beschwerden über das resultierende Denglisch ignoriert man dann weg, Prio hat, dass die Ergebnisse des AIDD-Prozesses am Ende passen.

Für Backend-Features nutze ich für die funktionale Beschreibung klassische Use Cases, manchmal auch Journeys, und Schnittstellenverträge. Eine Journey kann so lauten: Eine Administratorin legt eine Umfrage mit Titel und Ersteller an, fügt drei Fragen hinzu, ruft die vollständige Struktur ab, löscht eine Frage und löscht anschließend die Umfrage. Das reicht für ein Verständnis der gewünschten Funktionalität. Journeys helfen auch dabei, die richtige Granularität eines Features zu finden. Wenn ich keine Journey beschreiben kann, z. B. weil ein Feature mit einem einzigen API-Endpunkt verwechselt wurde, kann das ein Hinweis auf einen zu feinen Schnitt sein. Wenn ich mich schwertue, die Funktionalität in einer zusammenhängenden Journey zu beschreiben, bin ich vermutlich noch zu grobgranular. Schnittstellenverträge sind nur dann Teil der Anforderungen, wenn sie nicht das Ergebnis der Umsetzung sind. Es geht hier also um Schnittstellen, die der neu zu erstellende Backend-Service unverändert verwenden soll. Keine gute Idee ist es meines Erachtens, Anforderungen an neu zu erstellende Schnittstellen beispielsweise als OpenAPI-Contract in die Spezifikation zu packen. Das ist viel zu detailliert und nimmt eine wesentliche Aufgabe der Design- und Umsetzungsphase vorweg.

Auch für UI-lastige Features sind Journeys eine gute Wahl, die die Interaktionen der Benutzer mit der Oberfläche beschreiben. Hier kommen oft sogenannte Personas zum Einsatz, um die unterschiedlichen Nutzerrollen und deren Verhalten zu illustrieren. Hinzu kommen oft Verweise auf Mockups oder Design-Dokumente, um die visuelle Umsetzung zu verdeutlichen. Eine nach Verhaltensbereichen gegliederte UI-Spezifikation zeigt das Beispiel für Foto-Carousels.

Eine sinnvolle Gliederung für eine Feature-Datei könnte wie folgt aussehen:

1. Kurzbeschreibung. Ein knapper Absatz: was das Feature ist, für wen und warum es erstellt wurde.
2. Ziele und Nicht-Ziele. Insbesondere für Agenten wichtig. Dass das Backend-Team nur die API und keine UI baut, ist für menschliche Entwickler oft selbstverständlich, für Agenten jedoch nicht.
3. Funktionale Beschreibung. Siehe oben.
4. Nicht-funktionale Anforderungen. Featurebezogene nicht-funktionale Anforderungen, die über die Vorgaben in der Architekturdokumentation hinausgehen. Beispiele sind Vorgaben zu Berechtigungen oder zur Barrierefreiheit.
5. Geschäfts- oder UI-Regeln. Nur die Regeln, die spezifisch für das Feature sind und nicht schon im semantischen Datenmodell stehen (oder ein Verweis, wenn sie dort stehen).
6. Fehlerfälle. Erwartete Fehlerfälle, die über die UI oder API verifiziert werden können.
7. Akzeptanzkriterien. Done-When für das ganze Feature. Hier gilt dasselbe wie für die Fehlerfälle: Sie müssen sich “von außen” prüfen lassen, also über die UI oder die API.
8. Referenzen. Links auf Schnittstellenverträge, Mockups etc.

Documentation as Code

Documentation as Code ist ein Ansatz, bei dem Anforderungen und andere projektrelevante Dokumente wie Quelltext behandelt werden. Das bedeutet, dass sie versioniert, im Repository gepflegt und im Idealfall automatisiert überprüft werden. Markdown-Dateien für Feature-Spezifikationen sind ein typisches Beispiel für diesen Ansatz. Wie ich oben schon erwähnt habe, empfehle ich kleinen bis mittelgroßen Projekten die Ablage zusammen mit dem Quellcode in einem Repository. In einem solchen Setup kann ich die Agenten über den Bootstrap-Prompt oder die AGENTS.md-Datei anweisen, die Spezifikation konsistent mit dem Code zu halten. In den PRs für Code-Änderungen werden dann auch die Anpassungen an der Spezifikation geprüft und freigegeben.

Erst in großen Projekten mit vielen Beteiligten, mehreren unabhängig voneinander entwickelten Modulen und entsprechend komplexen Abhängigkeiten zwischen diesen Modulen kann es sinnvoll sein, ein separates Spezifikations-Repository anzulegen. Denn pflegt man in diesem Szenario die Anforderungen jeweils in den Modul-Repositories, besteht die Gefahr, dass sich Inkonsistenzen einschleichen und die Gesamtübersicht verloren geht. Nicht nur für Menschen, sondern auch für die Agenten.

Bei der Entscheidung für ein separates Spezifikations-Repository ist es wichtig, dass die eingesetzten AIDD-Tools die Arbeit in mehreren Repositories unterstützen. Dadurch können Agenten Anforderungen im Spec-Repository parallel zum Quelltext im Modul-Repository überarbeiten. Und dann beispielsweise zwei PRs aufmachen (einen für die Specs, einen für den eigentlichen Quelltext). Um die Konsistenz zu gewährleisten, müssen die beiden PRs dann natürlich zusammen geprüft und freigegeben werden.

Spec-Driven Development

Wer sich schon mit dem Thema Anforderungen und AI in der Softwareentwicklung beschäftigt hat, ist eventuell über den Begriff Spec-Driven Development (SDD) gestolpert. SDD ist aus meiner Sicht nicht wirklich eindeutig definiert, lässt sich aber in etwa auf die folgenden Kernaussagen herunterbrechen:

1. Anforderungen werden erfasst und dokumentiert, bevor die Umsetzung beginnt.
2. Anforderungen werden während der Umsetzung laufend aktualisiert.
3. Anforderungen werden gleichwertig zu Quellcode im Projekt behandelt, also bspw. im Versionskontrollsystem gepflegt und versioniert.

Hier schließt sich der Kreis zu diesem Beitrag, siehe oben. Im SDD kommt dann noch der Tool-Aspekt hinzu. Es gibt mittlerweile mehrere Implementierungen und Toolkits, die diesen Ansatz unterstützen. Ein Beispiel hierfür ist das schon weiter oben im Beitrag erwähnte Amazon Kiro.

Auch eine Open-Source-Variante einer SDD-Implementierung ist verfügbar, nämlich das Spec Kit auf GitHub. Version 1.0.0 wurde im August 2026 offiziell veröffentlicht. Speziell zum Thema SDD mit dem Spec Kit wird es noch einen separaten Blog-Beitrag geben.

Fazit

“Kein Code ohne Anforderung” erlebt mit AI-Driven Development ein aus meiner Sicht sehr begrüßenswertes Revival. Feature-Dateien im Markdown-Format können mit allen gängigen Tools problemlos erstellt und gepflegt werden. Die bestehenden Mechanismen zur Verwaltung von Quellcode, wie Versionskontrolle und Code-Reviews, lassen sich somit auch direkt für die Spezifikation anwenden. Zudem unterstützen die Agenten uns dabei, einen ewigen Schmerzpunkt in der Projektarbeit anzugehen: die kontinuierliche Anpassung und Aktualisierung der Anforderungen an die tatsächliche Umsetzung.

Wer sich bisher nicht an AI-Driven Development herangetraut hat, sollte alleine wegen der Aussicht auf eine endlich vollständige und aktuelle Dokumentation der Anforderungen den ersten Schritt in die neue Welt der Softwareentwicklung wagen.