OpenSpec (SDD)

OpenSpec: Spezifikationsgetriebene Entwicklung für KI-gestützte Codegenerierung

Die Integration von Künstlicher Intelligenz in den Softwareentwicklungsprozess hat zu neuen methodischen Herausforderungen geführt. Ein rein chatbasierter Ansatz – oft als „Vibe Coding“ bezeichnet – führt bei komplexen Projekten häufig zu unvorhersehbarem Verhalten, Kontrollverlust über die Codebasis und mangelnder Nachvollziehbarkeit.

Das Open-Source-Framework OpenSpec (entwickelt von Fission AI) adressiert diese Probleme durch die Etablierung einer strukturierten Spezifikationsebene. Dieser Artikel beschreibt die methodischen Grundlagen, die Installation, die Aktualisierungsprozesse sowie den operativen Workflow von OpenSpec.

1. Einführung und methodischer Ansatz

OpenSpec basiert auf dem Konzept des Spec-Driven Development (SDD) (spezifikationsgetriebene Entwicklung). Das primäre Ziel besteht darin, vor der eigentlichen Codegenerierung durch eine KI eine formale, vom Entwickler überprüfbare Spezifikation des Soll-Zustands zu definieren.

Kernprinzipien von OpenSpec

Explizite Spezifikationsebene: Anstatt direkt Code zu generieren, erzeugt die KI im ersten Schritt Planungsdokumente (Proposals, Designs und Aufgabenlisten). Der menschliche Entwickler gibt diese Dokumente frei, bevor Quellcode geändert wird.
Dateibasierte Versionierung: Alle Spezifikationen und Änderungsvorschläge werden als Markdown-Dateien im Repository gespeichert. Dadurch sind sie über Git versionierbar und direkt in bestehende CI/CD-Pipelines integrierbar.
Entkopplung von Kontext und Code: Durch die Aufteilung in diskrete Änderungseinheiten (Changes) wird verhindert, dass der Kontext-Window der KI durch irrelevante Projektinformationen überlastet wird.

2. Installation und Initialisierung

Das OpenSpec-CLI (Command Line Interface) wird über die Node.js-Laufzeitumgebung betrieben.

Systemvoraussetzungen

Node.js: Version 20.19.0 oder höher.

Installation der CLI

Die Installation erfolgt global über den Paketmanager npm:

bash npm install -g @fission-ai/openspec@latest

Hinweis: Für temporäre Ausführungen ohne globale Installation kann npx verwendet werden:

bash npx @fission-ai/openspec@latest --help

Initialisierung im Projekt

Um OpenSpec in einem bestehenden Softwareprojekt zu aktivieren, wird das CLI im Stammverzeichnis des Repositories initialisiert:

bash cd /pfad/zum/projekt openspec init

Dieser Befehl erstellt das Verzeichnis openspec/ und generiert die notwendigen Konfigurationsdateien sowie die systemspezifischen Instruktionen für unterstützte KI-Coding-Assistenten.

3. Aktualisierung und Wartung

Die Wartung von OpenSpec umfasst sowohl das CLI-Tool als auch die projektspezifischen Konfigurationen.

CLI-Update

Das globale npm-Paket sollte regelmäßig auf den neuesten Stand gebracht werden, um Kompatibilität mit neuen Versionen von KI-Modellen und IDEs sicherzustellen:

bash npm install -g @fission-ai/openspec@latest

Projektkonfiguration und Instruktionen aktualisieren

Wenn Änderungen an den internen Abläufen oder den Profilen vorgenommen wurden, müssen die Instruktionsdateien innerhalb des Projekts aktualisiert werden. Dies geschieht über folgenden CLI-Befehl:

bash openspec update

Dieser Befehl schreibt die systemspezifischen Prompt- und Konfigurationsvorlagen im Projektordner neu, ohne die bestehenden Spezifikationsdaten zu überschreiben.

4. Der Entwicklungsworkflow

Der Arbeitsablauf mit OpenSpec gliedert sich in eine strukturierte Schleife aus Planung, Review, Implementierung und Integration. Die Steuerung erfolgt primär über Slash-Befehle (/opsx:...) innerhalb der Chat-Schnittstelle des genutzten KI-Tools (z. B. Cursor, Claude Code, Windsurf).

Der Standard-Zyklus

Erstellung des Änderungsvorschlags (/opsx:propose) Der Entwickler startet die Aufgabe über den Befehl:

text /opsx:propose [Feature-Beschreibung oder Ticket-ID]

Die KI generiert daraufhin im Verzeichnis openspec/changes/change-<id>/ folgende Markdown-Dokumente: - proposal.md: Begründung und Zielsetzung der Änderung. - design.md: Technische Architektur und geplante Systemkomponenten. - tasks.md: Eine konkrete Checkliste der notwendigen Implementierungsschritte. - specs/: Die betroffenen Spezifikationsänderungen.

Prüfung (Review) Der Entwickler sichtet die generierten Entwürfe. Anpassungen an der Architektur oder den Anforderungen werden direkt in den Markdown-Dateien vorgenommen.
Ausführung (/opsx:apply) Nach Freigabe der Pläne wird die Implementierung gestartet:

text /opsx:apply

Die KI arbeitet die Checkliste in tasks.md Schritt für Schritt ab. Der Status der Aufgaben wird in der Datei protokolliert (z. B. [x] für erledigte Aufgaben).

Abschluss und Archivierung (/opsx:archive oder /opsx:sync) Nach erfolgreichem Testlauf wird die Änderung finalisiert:

text /opsx:archive

Dieser Befehl integriert die vorgenommenen Spezifikationsänderungen in die globale Dokumentation des Projekts und verschiebt den Änderungsordner in das Archiv. Alternativ führt /opsx:sync die Spezifikationsdeltas zusammen, ohne den Änderungsordner zu archivieren.

5. Erweiterte Features und Werkzeuge

Über den Standard-Workflow hinaus bietet OpenSpec Mechanismen zur Qualitätssicherung und Konfigurationssteuerung.

Spec-Deltas

Ein zentraler Aspekt von OpenSpec ist das Konzept der Spec-Deltas. Anstatt bei jeder Änderung die gesamte Projektspezifikation an das LLM zu übertragen (was zu Kontextrauschen und erhöhtem Token-Verbrauch führt), arbeitet OpenSpec mit Differenzdateien.

Ein Delta spezifiziert präzise:

Welche Anforderungen neu hinzukommen (ADDED).
Welche Anforderungen angepasst werden (MODIFIED).
Welche Anforderungen entfallen (REMOVED).

Zur detaillierten Analyse dieser Differenzen bietet die CLI folgenden Befehl:

bash openspec show <change-id> --json --deltas-only

Validierung (`openspec validate`)

Zur Vermeidung von Inkonsistenzen in der Dokumentationsstruktur verfügt die CLI über ein integriertes Validierungswerkzeug:

bash openspec validate <change-id>

Dieser Befehl überprüft:

Die strukturelle Integrität der Markdown-Dateien gegen das vordefinierte Schema.
Die Konsistenz zwischen den Aufgaben in tasks.md und den in proposal.md definierten Spezifikationsänderungen.
Etwaige Syntaxfehler in den Metadaten.

Profile und Konfiguration

OpenSpec lässt sich über Profile an unterschiedliche Teamgrößen und Sicherheitsanforderungen anpassen. So kann beispielsweise über openspec config profile definiert werden, ob zusätzliche Prüfschritte wie /opsx:verify oder Fast-Forward-Optionen (/opsx:ff) aktiv sein sollen. Nach einer Profiländerung stellt openspec update sicher, dass alle lokalen Konfigurationen synchronisiert werden.