OpenSpec bringt Ordnung ins Coding mit KI: Statt deinem AI-Agenten einfach einen Prompt hinzuwerfen, legst du zuerst fest, was gebaut werden soll, und lässt erst dann den Code schreiben. In diesem OpenSpec-Tutorial zeigen wir dir in fünf Schritten, wie du mit Spec-driven Development startest, am Beispiel einer kleinen Kanban-App.
OpenSpec ist ein schlankes Open-Source-Framework für Spec-driven Development (SDD). Die Idee: Bevor dein AI-Agent eine Zeile Code schreibt, einigt ihr euch auf eine Spezifikation, also auf das Warum, das Was und das Wie. Alles landet als einfache Markdown-Dateien in deinem Projekt, versioniert und jederzeit nachlesbar.
OpenSpec arbeitet mit den AI-Tools, die du wahrscheinlich schon nutzt: Claude Code, Codex, GitHub Copilot, Cursor, Gemini CLI und rund 50 weitere. Das Tool ist kostenlos (MIT-Lizenz), du brauchst nur Node.js und einen Coding-Agenten deiner Wahl. Wie sich der Ansatz vom freien Prompten unterscheidet, haben wir in unserem Vergleich Vibe-Coding vs. Spec-driven Development ausführlich erklärt.
Der Ablauf in OpenSpec besteht aus drei Befehlen:
/opsx:propose: Du beschreibst, was du bauen willst. Der Agent erstellt Proposal, Spec, Design und Task-Liste.
/opsx:apply: Der Agent setzt die Tasks Schritt für Schritt um.
/opsx:archive: Der fertige Change wird archiviert und in die dauerhaften Specs übernommen.
Je nach Tool sieht die Schreibweise leicht anders aus. In VS Code mit GitHub Copilot heißt der Befehl zum Beispiel /opsx-propose statt /opsx:propose.
Schritt 1: OpenSpec installieren und im Projekt einrichten
Du installierst OpenSpec einmal global auf deinem Rechner und richtest es dann im Projektordner ein. Dabei legst du fest, mit welchen AI-Tools du arbeiten willst.
Node.js prüfen: OpenSpec braucht Node.js ab Version 20.19. Gib im Terminal node -v ein. Ist die Version älter oder fehlt Node.js, lade die aktuelle LTS-Version von nodejs.org.
OpenSpec installieren: Öffne ein Terminal (Mac/Linux) oder die PowerShell (Windows) und gib npm install -g @fission-ai/openspec@latest ein. Auf dem Mac geht alternativ auch brew install openspec.
Projektordner öffnen: Wechsle mit cd dein-projekt in den Ordner deines Projekts. Für den ersten Test reicht ein leerer Ordner, zum Beispiel openspec-test.
OpenSpec initialisieren: Starte openspec init. Es erscheint der Willkommensbildschirm, mit Enter geht es weiter zur Tool-Auswahl.
AI-Tools auswählen: Markiere mit der Leertaste die Tools, die du nutzt, etwa Claude Code, Codex oder GitHub Copilot, und bestätige mit Enter. OpenSpec legt dann die passenden Skills und Slash-Commands in Ordnern wie .claude oder .github an.
Nach openspec init begrüßt dich OpenSpec im Terminal.Bei der Einrichtung wählst du deine AI-Tools aus, OpenSpec unterstützt rund 50 davon.
Schritt 2: Mit /opsx:propose eine Idee beschreiben
Jetzt beschreibst du deinem AI-Agenten in einem Satz, was du bauen willst. OpenSpec macht daraus einen sogenannten Change mit allen Planungsdokumenten, Code wird in diesem Schritt noch nicht geschrieben.
Editor und Chat öffnen: Öffne den Projektordner in deinem Editor, zum Beispiel VS Code, und starte den Chat deines AI-Agenten im Agent-Modus. Mit Claude Code geht das genauso im Terminal.
Propose-Befehl eingeben: Schreibe deinen Wunsch hinter den Befehl, zum Beispiel /opsx:propose create an easy web app for task management, like trello. Englisch funktioniert gut, Deutsch geht aber auch.
Agent arbeiten lassen: Der Agent prüft dein Projekt und legt unter openspec/changes/ einen eigenen Ordner an, in unserem Beispiel task-management-board.
Zusammenfassung lesen: Am Ende meldet der Agent, welche Artefakte er erstellt hat, etwa „4/4 artifacts complete“. Der Hinweis „No application code was changed“ zeigt dir, dass bisher nur geplant wurde.
Ein Satz im Chat reicht: Aus dem Propose-Befehl entsteht ein kompletter Change-Ordner.Der Agent fasst die vier erzeugten Artefakte zusammen und verweist auf den nächsten Schritt.
Schritt 3: OpenSpec-Dateien prüfen und anpassen
Das ist der wichtigste Schritt: Du liest, was der Agent geplant hat, und korrigierst es, bevor Code entsteht. Änderungen kosten hier ein paar Sekunden, später im Code deutlich mehr Zeit.
proposal.md lesen: Hier steht, warum der Change existiert und was er umfasst. Prüfe besonders, was ausdrücklich nicht dazugehört, im Beispiel etwa Login, Multi-User und Cloud-Sync.
spec.md prüfen: Im Unterordner specs/ beschreibt die Spec die Anforderungen als einfache WHEN/THEN-Szenarien, zum Beispiel „WHEN ein User eine Spalte mit Aufgaben löscht, THEN fragt das System vorher nach“. Diese Szenarien sind später dein Prüfmaßstab.
design.md checken: Hier trifft der Agent die technischen Entscheidungen, im Beispiel React, TypeScript und Vite, und begründet sie. Passt dir der Stack nicht, sag es jetzt.
tasks.md durchgehen: Die Task-Liste zerlegt die Umsetzung in kleine, nummerierte Arbeitspakete mit Checkboxen, jeweils inklusive Tests.
Änderungen einfordern: Wenn dir etwas fehlt, schreib es dem Agenten einfach in den Chat, etwa „Füge eine Suchfunktion hinzu“. Er aktualisiert dann die passenden Dateien.
Die proposal.md beschreibt Ziel, Umfang und Auswirkungen des Changes.In der spec.md stehen die Anforderungen als prüfbare WHEN/THEN-Szenarien.Die design.md hält Ziele, Nicht-Ziele und Technik-Entscheidungen fest.Die tasks.md ist die Checkliste, die der Agent im nächsten Schritt abarbeitet.
Schritt 4: Mit /opsx:apply die App bauen lassen
Sobald der Plan steht, startest du die Umsetzung. Der Agent arbeitet die Task-Liste der Reihe nach ab und hakt jeden erledigten Punkt in der tasks.md ab.
Apply-Befehl starten: Gib im Chat /opsx:apply ein. Der Agent liest alle Planungsdateien und beginnt mit dem ersten Task.
Fortschritt verfolgen: In der tasks.md siehst du, wie aus [ ] nach und nach [x] wird. Der Agent legt dabei Code, Tests und Konfiguration an.
Rückfragen beantworten: Bei größeren Changes fragt der Agent zwischendurch, ob er weitermachen soll. Bestätige mit „Continue“ oder gib kurz Feedback.
Änderungen übernehmen: In VS Code bestätigst du die geänderten Dateien mit „Keep“. Mit „Undo“ kannst du einzelne Schritte zurücknehmen.
Während /opsx:apply hakt der Agent die Tasks in der tasks.md nacheinander ab.
Schritt 5: Ergebnis testen und mit /opsx:archive abschließen
Zum Schluss prüfst du die fertige App gegen deine Spec und schließt den Change ab. Damit wird die Spec zur dauerhaften Dokumentation deines Projekts.
Abschlussbericht lesen: Der Agent meldet, wie viele Tasks erledigt sind (im Beispiel 11/11), ob alle Tests laufen und ob die OpenSpec-Validierung erfolgreich war.
App im Browser testen: Öffne die lokale Adresse, die der Agent nennt, etwa http://127.0.0.1:5173/. Klick dich durch die Szenarien aus der spec.md: Aufgaben anlegen, verschieben, Seite neu laden.
Nachbessern lassen: Funktioniert etwas nicht wie beschrieben, sag dem Agenten, welches Szenario fehlschlägt. Die Spec ist dabei eure gemeinsame Referenz.
Change archivieren: Gib /opsx:archive ein. OpenSpec verschiebt den Change nach openspec/changes/archive/ und übernimmt die Anforderungen in die dauerhaften Specs unter openspec/specs/.
Nächsten Change starten: Neue Features baust du wieder mit /opsx:propose, zum Beispiel „add dark mode“. So wächst deine App Schritt für Schritt, und die Specs bleiben aktuell.
Alle 11 Tasks erledigt, 18 Tests grün: Die Kanban-App läuft lokal im Browser.Das Ergebnis: eine schlanke Kanban-App mit drei Spalten, gebaut aus einem Satz und einer geprüften Spec.
OpenSpec: Wichtige Links für den Einstieg
OpenSpec auf GitHub: Quellcode, README und aktuelle Releases des Projekts von Fission AI.
openspec.dev: Die offizielle Website mit Überblick über Konzept und Workflow.
Getting Started: Die offizielle Einstiegsanleitung, die über dieses Tutorial hinausgeht.
Commands-Übersicht: Alle Slash-Commands, inklusive erweiterter Befehle wie /opsx:verify oder /opsx:ff.
Supported Tools: Liste aller unterstützten AI-Tools und wo OpenSpec deren Dateien ablegt.
OpenSpec selbst ist kostenlos und Open Source unter MIT-Lizenz. Kosten entstehen nur für dein AI-Tool, etwa ein Abo für Claude Code, GitHub Copilot oder ChatGPT mit Codex.
Welche AI-Tools funktionieren mit OpenSpec?
OpenSpec unterstützt rund 50 Tools, darunter Claude Code, Codex, GitHub Copilot, Cursor, Gemini CLI, Cline, Amazon Q Developer und Windsurf beziehungsweise Devin Desktop. Bei openspec init kannst du mehrere gleichzeitig auswählen.
Brauche ich Programmierkenntnisse für OpenSpec?
Für den Einstieg reichen Grundkenntnisse im Terminal. Die Specs sind in normalem Englisch oder Deutsch geschrieben. Um das Ergebnis sinnvoll zu prüfen, hilft aber ein grundlegendes Verständnis davon, wie eine Web-App aufgebaut ist.
Was ist der Unterschied zwischen OpenSpec und Vibe-Coding?
Beim Vibe-Coding promptest du direkt drauflos und korrigierst laufend. Bei OpenSpec legst du vorher Ziel, Umfang, Anforderungen und Tasks fest. Der Agent hat dadurch einen klaren Auftrag, und du kannst das Ergebnis gegen die Spec prüfen.
Funktioniert OpenSpec auch mit bestehenden Projekten?
Ja. Du führst openspec init einfach im vorhandenen Projektordner aus. OpenSpec ist auf Brownfield-Projekte ausgelegt: Jeder Change beschreibt nur, was sich ändert, und die Specs wachsen mit jedem archivierten Change.
Fazit: Warum Spec-driven Development besser funktioniert als Vibe-Coding
OpenSpec ist ein einfacher Einstieg ins Spec-driven Development: drei Befehle, vier Markdown-Dateien, und dein AI-Agent arbeitet nach Plan statt nach Bauchgefühl. Im Vergleich zum Vibe-Coding bringt das konkrete Vorteile:
Saubere Anwendungen: Der Agent baut nach einer geprüften Architektur und einer klaren Task-Liste, inklusive Tests. Das Ergebnis ist strukturierter Code statt einer Sammlung von Prompt-Ergebnissen.
Weniger Missverständnisse: Fehler in der Planung fallen auf, bevor Code entsteht. Beim Vibe-Coding merkst du sie oft erst, wenn schon dutzende Dateien betroffen sind.
Klarer Umfang: Durch die festgelegten Non-Goals baut der Agent keine Features, die du nicht bestellt hast.
Prüfbare Ergebnisse: Die WHEN/THEN-Szenarien in der Spec sind deine Checkliste für den Test. Du weißt genau, wann etwas fertig ist.
Dokumentation inklusive: Die archivierten Specs beschreiben, was deine App kann und warum. Das hilft dir, deinem Team und dem nächsten AI-Agenten.
Tool-unabhängig: Die Specs liegen als Markdown in deinem Projekt. Du kannst jederzeit zwischen Claude Code, Codex oder Copilot wechseln.
Fang mit einem kleinen Projekt an, zum Beispiel einer To-do-App wie in unserem Beispiel, und du siehst nach einer halben Stunde, wie viel ruhiger AI-Coding mit einer Spec läuft. Viel Erfolg!
Ralf Schukay ist Co-Gründe von ai-rockstars und spezialisiert auf AI Engineering und Data Analytics. Er arbeitet als Teamlead Analytics & Conversion in der Berliner Digitalagentur MAI Group. Er hat über 20 Jahre Erfahrung im Bereich Web, Analytics und AI.
Wir verwenden Technologien wie Cookies, um Geräteinformationen zu speichern und/oder darauf zuzugreifen. Wir tun dies, um das Surferlebnis zu verbessern und um personalisierte Werbung anzuzeigen. Wenn Sie diesen Technologien zustimmen, können wir Daten wie das Surfverhalten oder eindeutige IDs auf dieser Website verarbeiten. Wenn Sie Ihre Zustimmung nicht erteilen oder zurückziehen, können bestimmte Funktionen beeinträchtigt werden.
Funktional
Immer aktiv
Die technische Speicherung oder der Zugang ist unbedingt erforderlich für den rechtmäßigen Zweck, die Nutzung eines bestimmten Dienstes zu ermöglichen, der vom Teilnehmer oder Nutzer ausdrücklich gewünscht wird, oder für den alleinigen Zweck, die Übertragung einer Nachricht über ein elektronisches Kommunikationsnetz durchzuführen.
Vorlieben
Die technische Speicherung oder der Zugriff ist für den rechtmäßigen Zweck der Speicherung von Präferenzen erforderlich, die nicht vom Abonnenten oder Benutzer angefordert wurden.
Statistiken
Die technische Speicherung oder der Zugriff, der ausschließlich zu statistischen Zwecken erfolgt.Die technische Speicherung oder der Zugriff, der ausschließlich zu anonymen statistischen Zwecken verwendet wird. Ohne eine Vorladung, die freiwillige Zustimmung deines Internetdienstanbieters oder zusätzliche Aufzeichnungen von Dritten können die zu diesem Zweck gespeicherten oder abgerufenen Informationen allein in der Regel nicht dazu verwendet werden, dich zu identifizieren.
Marketing
Die technische Speicherung oder der Zugriff ist erforderlich, um Nutzerprofile zu erstellen, um Werbung zu versenden oder um den Nutzer auf einer Website oder über mehrere Websites hinweg zu ähnlichen Marketingzwecken zu verfolgen.
