OpenSpec-Einstieg: Installation, Workflow und häufige Fehler

Spezifikationen als Deltas, nicht als 40-seitiges PRD.

Inhaltsverzeichnis

OpenSpec ist eine kostenlose, quelloffene CLI von Fission AI, die sicherstellt, dass Sie und Ihr Coding-Agent sich auf eine Änderung in normalem Markdown einigen, bevor Code geschrieben wird – ohne die phasengesteuerte Zeremonie schwererer, speckgetriebener Frameworks.

Die meisten Teams, die speckgetriebene Entwicklung (Spec-Driven Development) ausprobieren, stocken beim selben Kompromiss: genug Prozess, damit ein Agent nicht raten muss, aber nicht so viel Gerüst, dass für einen Bugfix mit fünfzig Zeilen ein Vorschlagsdokument erforderlich ist. OpenSpecs Antwort besteht darin, den Impuls, „das gesamte System zuerst zu dokumentieren“, ganz zu überspringen und Spezifikationen nur für das zu schreiben, was eine Änderung tatsächlich berührt, wobei ADDED, MODIFIED und REMOVED-Deltas anstelle eines vollständigen Neuschreibens jedes Mal verwendet werden.

OpenSpec spec-driven development workflow with an AI coding assistant

Dieses änderungszentrische Design ist auch der Grund, warum OpenSpec immer wieder neben GitHub Spec Kit, Kiro und Superpowers in dem Vergleich der SDD-Tool-Kategorien auftaucht – es ist in der Regel die Wahl, wenn ein Team überprüfbare Spezifikationen ohne eine 800 Zeilen lange Planungsphase möchte. Dieser Leitfaden deckt die Installation der CLI ab, den Vier-Befehls-Workflow, den man täglich tatsächlich nutzt, wie eine Änderung auf der Festplatte aussieht, sowie die Fragen und Kritikpunkte, die am häufigsten auf Reddit und im eigenen Issue-Tracker von OpenSpec auftauchen.

Was ist OpenSpec?

OpenSpec beschreibt seine eigene Philosophie in vier Zeilen: fließend statt starr, iterativ statt Wasserfall, einfach statt komplex, gebaut für Brownfield und nicht nur für Greenfield. In der Praxis bedeutet das, dass es keine gesperrten Phasen gibt – Sie können einen Vorschlag, eine Spezifikation oder eine Aufgabenliste zu jedem Zeitpunkt einer Änderung bearbeiten, anstatt wie in der toolneutralen SDD-Workflow in der strikten Reihenfolge spezifizieren-dann-planen-dann-implementieren festgelegt zu sein.

Eine Änderung in OpenSpec erzeugt bis zu vier Markdown-Artefakte in ihrem eigenen Ordner:

Artefakt Zweck
proposal.md Warum die Änderung existiert und was sie ändert, in einfacher Sprache
specs/ Delta-Anforderungen und Szenarien – die testbare Spezifikation für diese Änderung
design.md Optionaler technischer Ansatz, für Änderungen, die ihn benötigen
tasks.md Die Implementierungs-Checkliste, mit der der Agent arbeitet

Sobald eine Änderung implementiert und archiviert ist, verschmelzen ihre Delta-Spezifikationen in openspec/specs/, was zur dauerhaften, aktuellen Beschreibung Ihres Systems wird – dieselbe Idee von „Spezifikation als Single Source of Truth“, wie sie in Was ist speckgetriebene Entwicklung? beschrieben wird, nur dass sie hier eine Änderung nach dem anderen statt auf einmal geschrieben wird.

OpenSpec installieren

OpenSpec ist eine Node.js-CLI, daher benötigen Sie Node 20.19.0 oder neuer auf Ihrem Rechner.

node --version

Installieren Sie die CLI global mit npm und prüfen Sie anschließend, ob sie sich in Ihrem PATH befindet:

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

Deno, pnpm, yarn, bun und nix sind ebenfalls unterstützte Installationspfade, falls das besser zu Ihrer Umgebung passt als npm. Sobald installiert, initialisieren Sie es innerhalb eines Projekts:

cd your-project
openspec init

openspec init fragt, welche KI-Tools Sie verwenden, und schreibt die passenden Skill- und Befehlsdateien – OpenSpec unterstützt über 30 Assistenten, darunter Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Kiro und OpenCode. Für CI oder skriptbasierte Einrichtung überspringen Sie die Auswahl ganz:

openspec init --tools claude,cursor   # spezifische Tools einrichten
openspec init --tools all             # jedes unterstützte Tool
openspec init --tools none            # nur openspec/ -Struktur, keine Tool-Dateien

Starten Sie Ihr IDE anschließend neu, damit es die neu geschriebenen Skills und Befehle übernimmt. Wenn Sie lieber Ihren Assistenten die gesamte Installation durchführen lassen möchten, liefert OpenSpec einen Setup-Prompt mit, den Sie in Claude Code oder einen anderen Agenten einfügen können, der die Installation ausführt, openspec init ausführt und berichtet, was konfiguriert wurde.

Der Kern-Workflow: Erkunden, Vorschlagen, Anwenden, Archivieren

Dies ist das Einzige, was fast jeden am ersten Tag verwirrt: openspec-Befehle werden in Ihrem Terminal ausgeführt, aber /opsx:-Befehle werden im Chat-Fenster Ihres KI-Assistenten ausgeführt. Es gibt keinen separaten „interaktiven Modus“, in den man wechseln muss – das Eintippen des Slash-Befehls im Chat ist die Art, wie man startet.

flowchart LR A["/opsx:explore (optional)"] --> B["/opsx:propose change-name"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|specs merged| E["openspec/specs/"]
  • /opsx:explore ist ein denkender Partner ohne Risiko. Es liest den relevanten Teil Ihres Codebasises, legt Optionen dar und formt einen Plan, bevor etwas auf die Festplatte geschrieben wird – es lohnt sich, dies zur Gewohnheit zu machen, gerade weil es einen eifrigen Agenten davon abhält, selbstbewusst das Falsche zu bauen.
  • /opsx:propose <name> erstellt openspec/changes/<name>/ und entwirft in einem Schritt den Vorschlag, die Delta-Spezifikationen, das optionale Design und die Aufgabenliste. Sie prüfen den Plan hier, bevor die Implementierung beginnt.
  • /opsx:apply arbeitet sich durch die Aufgabenliste und macht dabei die abgearbeiteten Punkte ab. Da der Fortschritt in Dateien und nicht nur im Chat-Verlauf gespeichert wird, können Sie Ihr Kontext-Fenster leeren oder eine neue Sitzung starten und genau dort ansetzen, wo /opsx:apply aufgehört hat.
  • /opsx:archive archiviert die abgeschlossene Änderung in openspec/changes/archive/YYYY-MM-DD-<name>/ und verschmelzt ihre Delta-Spezifikationen in den kanonischen openspec/specs/-Baum.

Das Standard-core-Profil installiert genau diese vier Befehle plus update und sync. Ein erweitertes Profil fügt new, continue, ff, verify, bulk-archive und onboard für Teams hinzu, die ein Artefakt nach dem anderen anstelle von allen auf einmal erstellen möchten – wechseln Sie damit mit openspec config profile gefolgt von openspec update.

Jedes Tool schreibt denselben Befehl unterschiedlich, je nachdem, wie es individuelle Anweisungen lädt: /opsx:propose in Claude Code, /opsx-propose in Cursor und GitHub Copilot, @opsx-propose in Amazon Q oder $openspec-propose in Codex. openspec init druckt die genaue Form für die gewählten Tools aus, daher ist die schnellste Lösung für „nichts passierte, als ich den Befehl eingetippt habe“ in der Regel, diesen ausgedruckten Hinweis erneut zu lesen, anstatt zu raten.

Wie eine Änderung auf der Festplatte aussieht

Ein Änderungsordner unter openspec/changes/add-dark-mode/ enthält typischerweise einen Vorschlag, eine Delta-Spezifikation und eine Aufgabenliste wie diese:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Dieses ADDED/MODIFIED/REMOVED-Delta-Format ist der Mechanismus, der OpenSpec ermöglicht, eine gesamte Spezifikationsdatei für eine Änderung an einem Feld nicht neu zu schreiben. Es ist auch der Grund, warum OpenSpec explizit Brownfield-first und nicht Greenfield-first ist: Sie dokumentieren nie Ihre gesamte Anwendung, bevor Sie Wert erzielen, Sie dokumentieren nur den Ausschnitt, den jede echte Änderung berührt, und openspec/specs/ füllt sich über Monate normaler Arbeit von selbst auf.

Nützliche CLI-Befehle, um diesen Status zu prüfen, ohne das Terminal zu verlassen:

openspec list                 # aktive Änderungen
openspec show add-dark-mode   # Artefakte einer Änderung anzeigen
openspec validate --all       # Spezifikationsformatierung im gesamten Projekt prüfen
openspec view                 # interaktives Dashboard

Committe den gesamten openspec/-Ordner in Git. Die aktiven Änderungen und das Archiv sollen zu einem dauerhaften, versionierten Rekord dessen werden, was Ihr System tut und warum es sich geändert hat – nicht zu einem Notizbuch, das Sie nach dem Mergen löschen.

OpenSpec auf einer bestehenden Codebasis einführen

Die häufigste Sorge von Teams, die OpenSpec auf einem echten Projekt bewerten, ist in irgendeiner Form: „Meine App ist 80.000 Zeilen alt, muss ich sie zuerst alle spezifizieren?“ Nein. Die eigene Anleitung von OpenSpec ist hier eindeutig: Wählen Sie etwas Kleines und Echten, das Sie diese Woche ohnehin bauen wollten, fahren Sie /opsx:explore im Bereich aus, den Sie gleich berühren werden, damit der Agent zuerst kartografiert, wie die Dinge tatsächlich funktionieren, und schlagen Sie dann mit /opsx:propose eine Änderung vor, die nur auf diesen Ausschnitt begrenzt ist.

Wenn Sie bereits PRDs, SRS-Dokumente oder Design-Dokumente in Notion oder Confluence haben, behandeln Sie sie als Quellenmaterial für die Exploration, statt sie in Bulk in Spezifikationen umzuwandeln. Fügen Sie den relevanten Abschnitt in eine /opsx:explore-Sitzung ein und lassen Sie den Agenten daraus ein fokussiertes Delta formen; eine einmalige mechanische Konvertierung eines 40-seitigen PRDs neigt dazu, eine Spezifikation zu produzieren, der niemand nach sechs Monaten mehr vertraut. Für Teams, die eine geführte, kommentierte erste Fahrt statt des direkten Springens in eine echte Änderung wünschen, scannt der erweiterte /opsx:onboard-Befehl Ihre Codebasis nach einer kleinen, sicheren Verbesserung und führt den vollständigen Kreislauf daran durch.

Häufige Fragen und Probleme

Dies sind die Probleme, die wiederholt über den Discord von OpenSpec, GitHub-Issues und Reddit-Threads in Subreddits wie r/cursor, r/RooCode und r/opencodeCLI auftauchen.

„Ich habe den Slash-Befehl eingegeben und nichts passierte.“ Fast immer eines von Folgendem: Sie haben es im Terminal anstelle des Chats Ihres Assistenten eingegeben, Ihr IDE wurde seit dem Lauf von openspec init nicht neu gestartet, oder die CLI-Version ist alt genug, dass openspec update meldet, dass alles aktuell ist, ohne jemals die neueren Workflow-Dateien zu schreiben. Führen Sie openspec update aus, starten Sie das IDE neu und stellen Sie sicher, dass die Skill-Ordner existieren (.claude/skills/openspec-* für Claude Code oder das Äquivalent Ihres Tools aus der Liste der unterstützten Tools).

„Die KI generiert viel mehr Spezifikation, als ich brauche.“ Dies ist die am häufigsten zitierte Beschwerde in längeren Artikeln: Ein Agent kann eine 30-minütige Funktion in eine 800-Zeilen-Spezifikation verwandeln. OpenSpec begrenzt das context:-Feld, das in jede Anfrage injiziert wird, auf 50 KB, speziell um Disziplin zu erzwingen, aber die Delta-Spezifikationen selbst haben keine harte Grenze, daher ist das Kürzen generierter Spezifikationen auf das, was wirklich tragend ist, eine Gewohnheit, die Sie selbst aufrechterhalten müssen, und keine, die das Tool für Sie durchsetzt.

„Zwei Änderungen haben dasselbe Kriterium berührt und eines hat stillschweigend das Szenario des anderen verworfen.“ Dies ist ein reales, dokumentierter Grenzfall: Beim Archivieren wird ein MODIFIED-Delta als Ganzblock-Ersetzung angewendet, die über den Namen des Kriteriums adressiert wird. Wenn also zwei laufende Änderungen beide dasselbe Kriterium modifizieren, hat das Archivieren der zweiten die Szenarien der ersten ohne Warnung überschrieben. Aktuelle Versionen fügen eine Drift-Prüfung hinzu, die das Archivieren abbricht und Sie anweist, die Spezifikation der Änderung zuerst zu aktualisieren – aber es ist dennoch wert, zu wissen, dass dieser Fehlermodus existiert, wenn Sie mehrere Änderungen parallel in derselben Bereich ausführen.

„Welches KI-Modell sollte ich tatsächlich damit verwenden?“ Die eigenen Docs von OpenSpec empfehlen hochreasonende Modelle für sowohl Planung als auch Implementierung – Opus-Klasse und Codex-Klasse Modelle werden speziell hervorgehoben – sowie das Leeren Ihres Kontext-Fensters vor der Implementierung, da ein sauberer Kontext messbar bessere Ergebnisse liefert als eine lange, angesammelte Sitzung.

„Wie unterscheidet sich das von Spec Kit, Kiro, Superpowers oder BMAD?“ Dies ist die häufigste Frage auf Reddit, und die ehrliche Antwort lautet „Prozessgewicht“. OpenSpecs eigenes README rahmt den Vergleich direkt ein: Spec Kit ist gründlich, aber schwerer, mit mehr Markdown und starren Phasenkontrollen; Kiro ist mächtig, aber sperrt Sie in AWS’ IDE und Claude-Modelle ein; OpenSpec tauscht einen Teil dieser vorab-Struktur gegen die Fähigkeit ein, frei zu iterieren und mit jedem Assistenten zu arbeiten, den Sie bereits geöffnet haben. Für den vollständigen Abgleich mit Spec Kit, Kiro, Claude Code Skills, BMAD-METHOD und Superpowers, siehe den dedizierten SDD-Tool-Vergleich.

„Folgt die KI tatsächlich der Spezifikation, die sie gerade geschrieben hat?“ Nicht immer, und dies ist ein dokumentiertes Problem über SDD-Tools im Allgemeinen, nicht nur OpenSpec – ein großes Kontext-Fenster bedeutet nicht, dass der Agent gleichmäßig auf jeden Teil davon achtet. Der /opsx:verify-Befehl existiert speziell, um generierten Code zu erkennen, der seine eigene Spezifikation widerspricht, und es lohnt sich, ihn auf alles Nicht-Triviale auszuführen, statt die Implementierung blind zu vertrauen.

„Brauche ich das für einen Einzeiler-Fix?“ Nein. OpenSpecs eigenes FAQ sagt es so: Verwenden Sie es, wo Einigung wichtig ist, was die meisten nicht-trivialen, mehrdateiigen Arbeiten sind, und überspringen Sie es für einen Tippfehler-Fix oder eine Wegwerf-Prototyp, den Sie in einer Woche löschen werden.

Wann OpenSpec passt und wann nicht

Gute Passung:

  • Brownfield-Codebasen, bei denen Sie überprüfbare Spezifikationen wollen, ohne das gesamte System vorab zu dokumentieren.
  • Einzelnentwickler und kleine Teams, die leichtere Zeremonien als Spec Kit wünschen, aber immer noch einen schriftlichen Plan vor dem Code erhalten wollen.
  • Arbeit, die mehrere Dateien, eine Schema-Änderung oder alles, wofür ein Junior-Ingenieur verständlicherweise ein kurzes Design-Dokument wollen würde, umfasst.
  • Teams, die bereits verpflichtet sind, Pläne in Pull Requests zu prüfen – Delta-Spezifikationen diffen sauber, da sie nur beschreiben, was sich geändert hat.

Schwächere Passung:

  • Einzeilen-Bugfixes und Wegwerf-Prototypen, wo der Schritt der Vorschlagsprüfung mehr kostet, als er spart.
  • Teams, die die schwerere, präskriptivere Struktur von Spec Kit oder eine AWS-native, IDE-integrierte Erfahrung wie Kiro benötigen – siehe den Entscheidungsrahmen im Tool-Vergleich für die Stellen, an denen jedes Tool gewinnt.
  • Cross-Repo-Funktionen heute, außer Sie sind bereit, OpenSpecs Beta- stores-Feature zu versuchen, das die Planung in ein eigenes gemeinsames Repository verlagert, damit mehrere Codebasen und Agenten denselben Plan lesen können.
  • Jeder, der noch entscheidet, ob eine gegebene Funktion überhaupt eine Spezifikation verdient – lesen Sie zuerst Spezifikationsgetriebene Entwicklung vs Vibe Coding, da OpenSpec nur hilft, wenn Sie bereits entschieden haben, dass Struktur ihren Overhead wert ist.

Fazit

OpenSpecs Wette ist, dass der größte Teil der Schmerzen in der speckgetriebenen Entwicklung aus Zeremonien kommt, nicht aus der zugrunde liegenden Idee, sich vor dem Existieren von Code auf einen Plan zu einigen. Deltas anstelle von vollständigen Neuverschreibungen, keine gesperrten Phasen und ein Brownfield-first-Workflow machen es merklich leichter als Spec Kit oder Kiro, es auf einer Codebasis einzuführen, die Sie nicht von Grund auf gebaut haben. Die Kompromisse sind auch real – Spec-Bloat ist ein echtes Risiko ohne Disziplin, die Konfliktbehandlung um gleichzeitige Änderungen an einem Kriterium reift noch und das Ökosystem ist jünger als GitHub’s eigene Tools. Installieren Sie es auf einem echten Projekt, führen Sie eine kleine Änderung von Erkunden-Vorschlagen-Anwenden-Archivieren end-to-end durch und entscheiden Sie dann, ob die leichtere Zeremonie sich im Verhältnis zu Ihrer tatsächlichen Arbeitslast lohnt.

Abonnieren

Neue Beiträge zu Systemen, Infrastruktur und KI-Engineering.