SpecFlow: Mehrphasen-SDD in Cursor für strukturierte Code-Entwicklung

Die moderne Softwareentwicklung steht vor einem zentralen Dilemma: Wie lässt sich komplexe Funktionalität so spezifizieren und umsetzen, dass alle Beteiligten – Entwickler, Tester und Produktmanager – stets auf derselben Seite stehen?

Ein innovatives Werkzeug namens SpecFlow bietet hierfür eine Lösung: Es integriert Spec-Driven Development (SDD) direkt in den Entwicklungsworkflow von Cursor. Mit vier klar definierten Agenten-Phasen und einem einzigen Schreiber für den Quellcode stellt SpecFlow sicher, dass Spezifikationen vor der Implementierung abschließend geklärt werden. Der Prozess beginnt mit der Verfeinerung der Anforderungen und endet mit einer systematischen Code-Prüfung – alles automatisiert und nachvollziehbar dokumentiert.

Warum traditionelle Ansätze scheitern

In vielen Teams führt die unklare Trennung von Anforderungsdefinition und Implementierung zu wiederkehrenden Problemen:

• Vage Anforderungen führen zu umfangreichen Code-Änderungen, die schwer zu überprüfen sind.
• Mehrere Entwickler arbeiten gleichzeitig am Quellcode, was zu Konflikten und Inkonsistenzen führt.
• Fehlende Nachvollziehbarkeit erschwert die spätere Prüfung, ob alle Akzeptanzkriterien erfüllt wurden.

SpecFlow adressiert diese Herausforderungen durch einen strukturierten, phasenbasierten Ansatz, der sicherstellt, dass Spezifikationen vor der Code-Implementierung vollständig abgestimmt und dokumentiert sind.

Wie SpecFlow funktioniert: Die vier Phasen

SpecFlow organisiert den Entwicklungsprozess in vier aufeinander aufbauende Phasen, die jeweils von einem dedizierten Agenten gesteuert werden. Jede Phase produziert spezifische Ausgabedateien, die den Fortschritt transparent machen.

Phase 1: Verfeinerung der Anforderungen (refining)

Der Refiner-Agent analysiert die ursprüngliche Aufgabenstellung und erstellt eine detaillierte Spezifikation in der Datei task.md. Diese umfasst:

• Das Hauptziel der Aufgabe
• Klare Akzeptanzkriterien (AC1, AC2, …)
• Mögliche Einschränkungen
• Bereiche, die bewusst nicht bearbeitet werden

Ein typisches Beispiel für eine verfeinerte Aufgabe könnte lauten:

# Aufgabe: Rate-Limit für /api/search implementieren

## Ziel
Einschränkung des anonymen Datenverkehrs zu /api/search, ohne bestehende Funktionalität zu beeinträchtigen.

## Akzeptanzkriterien
- **AC1:** Mehr als 100 Anfragen pro Minute von derselben IP-Adresse führen zu einem HTTP-429-Statuscode.
- **AC2:** Die Antwort enthält ein JSON-Objekt mit dem Feld `error` und `retryAfter`.
- **AC3:** Alle bestehenden Tests für die Suchfunktionalität bleiben unverändert.

## Einschränkungen
- Vorhandene Fehlerbehandlungsmuster sollen wiederverwendet werden.
- Neue Umgebungsvariablen bedürfen der Zustimmung des Teams.

## Nicht behandelt
- Quoten pro API-Schlüssel
- Admin-Dashboard für die Verwaltung der Limits

Phase 2: Design und Planung (designing)

Der SDD-Agent erstellt einen detaillierten Implementierungsplan in den Dateien plan.md und tasks.md. Diese enthalten:

• Eine Liste der durchzuführenden Aufgaben (typischerweise nach TDD-Prinzipien geordnet)
• Testfälle, die die Akzeptanzkriterien abdecken
• Eine Beschreibung der geplanten Architektur und Middleware-Integration

Ein Ausschnitt aus tasks.md könnte wie folgt aussehen:

## Aufgaben
- [ ] [Test] Integrationstest hinzufügen: 101 Anfragen innerhalb von 60 Sekunden → HTTP-429 (AC1)
- [ ] [Test] Überprüfen, dass die JSON-Antwort den Vorgaben aus AC2 entspricht
- [ ] [Implementierung] Rate-Limit-Middleware erstellen (In-Memory-Speicher, 100 Anfragen/Minute)
- [ ] [Implementierung] Middleware in die Route /api/search einfügen
- [ ] [Implementierung] Gesamten Such-Test-Suite ausführen (AC3)

Phase 3: Code-Implementierung (implementing)

Erst nach der Freigabe durch /approve darf der Implementer-Agent den Quellcode bearbeiten. Dieser Schritt stellt sicher, dass:

• Nur ein Agent gleichzeitig am Quellcode arbeitet.
• Alle Spezifikationen und Tests vor der Implementierung vollständig geklärt sind.
• Der Code systematisch und nachvollziehbar entsteht.

Während der Implementierung werden die Aufgaben in tasks.md schrittweise abgehakt. Der Entwickler kann bei Unklarheiten jederzeit Rückfragen im Chat stellen.

Phase 4: Code-Review und Archivierung (reviewing)

Der Reviewer-Agent führt automatisierte Prüfungen durch, indem er die in .agents-docs/verification.md definierten Befehle ausführt. Dazu gehören:

• Ausführung der Test-Suite
• Prüfung auf Code-Stilkonformität (z. B. mit ESLint)
• Validierung der Akzeptanzkriterien

Das Ergebnis wird in review.md dokumentiert. Bei Erfolg wird der Fluss beendet und die Dateien in einen history/-Ordner archiviert. Bei Fehlern kehrt die Aufgabe zur Implementierungsphase zurück, begleitet von konkreten Hinweisen zur Behebung.

Praktische Anwendung: Ein Beispiel aus der Praxis

Ein Entwicklerteam möchte ein Rate-Limit für die Route /api/search einführen. Der Prozess sieht wie folgt aus:

1. Fluss aktivieren:

Der Entwickler gibt im Cursor-Chat den Befehl neue Aufgabe oder flow on ein. SpecFlow überprüft die Umgebung und erstellt die notwendigen Dateistrukturen.

1. Anforderungen verfeinern:

Der Refiner-Agent erstellt task.md mit den detaillierten Akzeptanzkriterien, wie im vorherigen Beispiel gezeigt.

1. Design und Planung:

Der SDD-Agent schlägt einen Implementierungsplan vor, der sowohl Tests als auch die Middleware-Entwicklung umfasst.

1. Freigabe erteilen:

Sobald alle Spezifikationen geklärt sind, gibt der Entwickler den Befehl /approve oder aprobado ein. Damit wird die Implementierungsphase freigegeben.

1. Implementierung durchführen:

Der Implementer-Agent schreibt den Code, während der Entwickler die Fortschritte überwacht. Die Aufgaben in tasks.md werden schrittweise abgehakt.

1. Code prüfen:

Der Reviewer-Agent führt die Tests aus und dokumentiert das Ergebnis. Bei Erfolg wird der Fluss beendet und die Dateien archiviert.

Die fünf Grundprinzipien von SpecFlow

SpecFlow basiert auf fünf zentralen Designprinzipien, die den Entwicklungsprozess strukturieren und effizienter gestalten:

• Spezifikation vor Implementierung: Ohne explizite Freigabe durch /approve darf kein Code geschrieben werden.
• Ein einziger Schreiber: Nur der Implementer-Agent darf den Quellcode bearbeiten, was Konflikte verhindert.
• Expliziter Zustand: Jede Phase wird durch spezifische Dateien dokumentiert (phase.md, task.md, plan.md).
• Portable Regeln: Die Agenten-Regeln befinden sich in .agents/ und bleiben auch nach Synchronisation erhalten.
• Kein Overhead: Ohne aktive Aufgabe arbeitet der Entwickler wie gewohnt – der SpecFlow-Fluss ist deaktiviert.

Tipps für den täglichen Einsatz

SpecFlow bietet eine Reihe nützlicher Befehle, die den Entwicklungsalltag erleichtern:

• specflow init: Erstinstallation und Einrichtung des Projekts
• specflow doctor: Überprüft den Zustand der Agenten-Dateien und die aktuelle Phase
• specflow doctor --run: Führt zusätzlich die in verification.md definierten Befehle aus
• specflow status: Zeigt die aktuelle Version und den Sync-Status an
• specflow sync: Aktualisiert die SpecFlow-Komponenten und -Adapter

Für Teams, die mit Linear arbeiten, bietet SpecFlow eine optionale Integration via Cursor MCP. Diese ermöglicht:

• Automatische Synchronisation von Linear-Issues mit dem SpecFlow-Fluss
• Statusaktualisierungen direkt aus dem Cursor-Chat
• Verknüpfung von Aufgaben mit Linear-Tickets

Fazit: Strukturierte Entwicklung mit SpecFlow

SpecFlow revolutioniert die Art und Weise, wie Teams Software entwickeln, indem es Spezifikationen in den Mittelpunkt stellt und einen klaren, phasenbasierten Prozess vorgibt. Durch die Integration in Cursor wird der Entwicklungsworkflow nahtlos in die bestehende Umgebung eingebettet – ohne zusätzliche Tools oder komplexe Einrichtungsprozesse.

Mit SpecFlow entfallen zeitraubende Diskussionen über unklare Anforderungen oder widersprüchliche Implementierungen. Stattdessen entsteht Code, der von Anfang an den Erwartungen entspricht und durch automatisierte Tests und Reviews abgesichert ist. Für Teams, die Wert auf Qualität, Transparenz und Effizienz legen, ist SpecFlow eine überzeugende Lösung.

Die Zukunft der Softwareentwicklung liegt in der Automatisierung von Prozessen, die menschliche Fehler minimieren und die Zusammenarbeit verbessern. SpecFlow ist ein Schritt in diese Richtung – und ein Beweis dafür, dass strukturierte Entwicklung nicht kompliziert sein muss.