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

Spezifikationen als Deltas, nicht als 40-seitiges PRD.

Inhaltsverzeichnis

OpenSpec ist eine kostenlose, Open-Source-CLI von Fission AI, die sicherstellt, dass Sie und Ihr Coding-Agent sich vor dem Schreiben von Code über eine Änderung in klarem Markdown einigen, ohne die phasenbasierte Formalität schwerer, spezifikationsgetriebener Frameworks.

Die meisten Teams, die Spezifikationsgetriebene Entwicklung (Spec-Driven Development) ausprobieren, scheitern am selben Kompromiss: genug Prozess, um zu verhindern, dass ein Agent rät, aber nicht so viel Gerüst, dass ein Bugfix mit fünfzig Zeilen ein Proposal-Dokument erfordert. OpenSpecs Antwort besteht darin, den Instinkt „Das gesamte System zuerst dokumentieren“ ganz zu überspringen und Spezifikationen nur für das zu schreiben, was eine Änderung tatsächlich betrifft, wobei ADDED, MODIFIED und REMOVED-Deltas anstelle eines vollständigen Neuschreibens verwendet werden.

OpenSpec spec-driven development workflow with an AI coding assistant

Dieses auf Änderungen ausgerichtete 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 möchte, ohne eine 800-Zeilen-Planungsphase einzugehen. Dieser Guide deckt die Installation der CLI ab, den Vier-Befehls-Workflow, den man tatsächlich tagtäglich nutzt, wie eine Änderung auf der Festplatte aussieht und welche Fragen und Beschwerden 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, für Brownfield entwickelt 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 streng in der Reihenfolge „Spezifizieren, dann Planen, dann Implementieren“ vorgezogen zu werden, wie der toolneutrale SDD-Workflow es beschreibt.

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 einen 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 die dauerhafte, aktuelle Beschreibung Ihres Systems wird – dieselbe Idee der „Spezifikation als Single Source of Truth“, die in Was ist Spezifikationsgetriebene Entwicklung? behandelt wird, nur auf eine Änderung zur selben Zeit begrenzt, anstatt alles auf einmal zu schreiben.

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 stellen Sie sicher, dass sie auf Ihrem PATH liegt:

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

Deno, pnpm, yarn, bun und nix werden ebenfalls als Installationspfade unterstützt, falls das besser zu Ihrer Einrichtung 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, einschließlich Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Kiro und OpenCode. Für CI oder skriptgesteuerte Einrichtung können Sie die Auswahl entirely überspringen:

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 Ihren IDE danach neu, damit er die neu geschriebenen Skills und Befehle aufnimmt. Wenn Sie lieber möchten, dass Ihr Assistent die gesamte Installation für Sie erledigt, liefert OpenSpec einen Setup-Prompt, den Sie in Claude Code oder einen anderen Agenten einfügen können, der die Installation ausführt, openspec init ausführt und meldet, was konfiguriert wurde.

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

Dies ist das eine, was fast jeden am ersten Tag stolpern lässt: 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 Sie eintreten müssen – das Tippen des Slash-Befehls im Chat ist die Art, wie Sie beginnen.

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 risikofreier Denkpartner. Er liest den relevanten Teil Ihrer Codebasis, legt Optionen dar und formt einen Plan, bevor etwas auf der Festplatte geschrieben wird – es lohnt sich, dies zur Gewohnheit zu machen, da es verhindert, dass ein eifriger Agent selbstbewusst das Falsche baut.
  • /opsx:propose <name> erstellt openspec/changes/<name>/ und entwirft in einem Schritt den Vorschlag, die Delta-Spezifikationen, das optionale Design und die Aufgabenliste. Hier überprüfen Sie den Plan, bevor die Implementierung beginnt.
  • /opsx:apply arbeitet die Aufgabenliste ab und hakt Punkte ab, während er fortschreitet. Da der Fortschritt in Dateien liegt und nicht nur im Chat-Verlauf, können Sie Ihr Kontextfenster leeren oder eine neue Sitzung starten und genau dort anknüpfen, 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 zur selben Zeit erstellen möchten, anstatt alles auf einmal – wechseln Sie dazu mit openspec config profile gefolgt von openspec update.

Jedes Tool schreibt den selben Befehl anders, je nachdem, wie es benutzerdefinierte 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 gibt die genaue Form für die von Ihnen gewählten Tools aus, daher ist die schnellste Lösung für „Es ist nichts passiert, als ich den Befehl tippte“ normalerweise, diese ausgegebenen Hinweise 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 es OpenSpec ermöglicht, eine gesamte Spezifikationsdatei nicht für eine Einzelfeld-Änderung neu zu schreiben. Es ist auch der Grund, warum OpenSpec ausdrücklich Brownfield-first statt Greenfield-first ist: Sie dokumentieren nie Ihre gesamte Anwendung, bevor Sie Wert erhalten, Sie dokumentieren nur den Ausschnitt, den jede echte Änderung berührt, und openspec/specs/ füllt sich über Monate normaler Arbeit natürlich auf.

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

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

Commit das gesamte openspec/-Verzeichnis in Git. Die aktiven Änderungen und das Archiv sollen zu einem dauerhaften, versionierten Record dessen werden, was Ihr System tut und warum es sich geändert hat – nicht zu einem Notizblock, den Sie nach dem Merging löschen.

OpenSpec auf einer bestehenden Codebasis einführen

Die häufigste Sorge von Teams, die OpenSpec auf einem echten Projekt bewerten, ist eine Variante von „Meine App ist 80.000 Zeilen alt, muss ich alles zuerst spezifizieren?“ Nein. OpenSpecs eigene Anleitung ist hier deutlich: Wählen Sie etwas Kleines und Reales, das Sie ohnehin diese Woche bauen wollten, führen Sie /opsx:explore im Bereich aus, den Sie gleich berühren, damit der Agent zuerst kartografiert, wie die Dinge tatsächlich funktionieren, und schlagen Sie dann mit /opsx:propose eine Änderung vor, die genau auf diesen Ausschnitt beschränkt ist.

Wenn Sie bereits PRDs, SRS-Dokumente oder Design-Dokumente in Notion oder Confluence liegen haben, behandeln Sie sie als Ausgangsmaterial für die Erkundung, anstatt sie in einem Rutsch in Spezifikationen zu konvertieren. 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 einer 40-seitigen PRD führt dazu, dass niemand der Spezifikation sechs Monate später traut. Für Teams, die einen geführten, erklärten ersten Durchlauf möchten, anstatt direkt in eine echte Änderung zu springen, scannt der erweiterte /opsx:onboard-Befehl Ihre Codebasis nach einer kleinen, sicheren Verbesserung und durchläuft den gesamten Loop damit.

Häufige Fragen und Probleme

Dies sind die Probleme, die wiederholt auf OpenSpecs Discord, GitHub Issues und Reddit-Threads in Subreddits wie r/cursor, r/RooCode und r/opencodeCLI auftauchen.

„Ich habe den Slash-Befehl getippt und es ist nichts passiert.“ Fast immer eines davon: Sie haben es im Terminal statt im Chat Ihres Assistenten getippt, Ihr IDE wurde seit dem Ausführen von openspec init nicht neu gestartet, oder die CLI-Version ist so alt, dass openspec update meldet, dass alles aktuell ist, ohne 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 Berichten: Ein Agent kann ein dreißigminütiges Feature in eine 800-Zeilen-Spezifikation verwandeln. OpenSpec begrenzt das context:-Feld, das in jede Anfrage injiziert wird, auf 50 KB, um Disziplin zu erzwingen, aber die Delta-Spezifikationen selbst haben keine harte Grenze, daher ist das Beschneiden generierter Spezifikationen auf das, was tatsächlich tragend ist, eine Gewohnheit, die Sie selbst aufrechterhalten müssen, und keine Sache, die das Tool für Sie durchsetzt.

„Zwei Änderungen berührten dieselbe Anforderung und eine stieß die Szenarien der anderen stillschweigend beiseite.“ Dies ist ein echter, dokumentierter Grenzfall: Beim Archivieren wird ein MODIFIED-Delta als ganzer Block-Ersatz angewendet, der an den Anforderungsnamen hängt, sodass, wenn zwei laufende Änderungen dieselbe Anforderung modifizieren, das Archivieren der zweiten früher die Szenarien der ersten ohne Warnung überschrieb. Aktuelle Versionen fügen eine Drift-Prüfung hinzu, die das Archivieren abbricht und Sie auffordert, die Spezifikation der Änderung zuerst zu aktualisieren – aber es ist trotzdem wert, zu wissen, dass der Fehlermodus existiert, wenn Sie mehrere Änderungen im selben Bereich parallel ausführen.

„Welches KI-Modell sollte ich eigentlich damit verwenden?“ OpenSpecs eigene Dokumente empfehlen Modelle mit hoher Reasoning-Fähigkeit sowohl für die Planung als auch für die Implementierung – Opus-Klasse und Codex-Klasse Modelle werden speziell genannt – und Ihr Kontextfenster vor der Implementierung zu leeren, da ein sauberes 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 Reddit-Frage, und die ehrliche Antwort ist „Prozessgewicht“. OpenSpecs eigenes README rahmt den Vergleich direkt ein: Spec Kit ist gründlich, aber schwerer, mit mehr Markdown und starreren Phasengrenzen; Kiro ist leistungsfähig, aber bindet Sie in AWSs IDE und Claude-Modelle ein; OpenSpec tauscht einen Teil dieser Vorstruktur gegen die Fähigkeit frei zu iterieren und mit dem Assistenten zu arbeiten, den Sie bereits geöffnet haben. Für die vollständige Aufschlüsselung gegenüber Spec Kit, Kiro, Claude Code Skills, BMAD-METHOD und Superpowers, sehen Sie sich den dedizierten SDD-Tool-Vergleich an.

„Hält die KI sich tatsächlich an die Spezifikation, die sie gerade geschrieben hat?“ Nicht immer, und dies ist ein dokumentiertes Problem über SDD-Tools allgemein, nicht einzigartig für OpenSpec – ein großes Kontextfenster bedeutet nicht, dass der Agent gleichmäßig auf jeden Teil davon achtet. Der /opsx:verify-Befehl existiert speziell, um generierten Code zu finden, der seine eigene Spezifikation widerspricht, und es lohnt sich, ihn bei allem Nicht-Trivialen auszuführen, anstatt der Implementierung blind zu vertrauen.

„Brauche ich das für einen Einzeilen-Fix?“ Nein. OpenSpecs eigene FAQ sagt das auch: Verwenden Sie es, wo Einverständnis wichtig ist, was die meisten nicht-trivialen, Multi-Datei-Arbeiten sind, und überspringen Sie es für einen Tippfehler-Fix oder ein Wegwerf-Prototyp, den Sie in einer Woche löschen werden.

„Wie kann ich verhindern, dass ein Agent etwas erneut vorschlägt, das wir bereits abgelehnt haben?“ /opsx:archive hat keinen dedizierten Status für eine abgelehnte Änderung, daher sagt nichts einem zukünftigen Vorschlag, dass eine Idee bereits untersucht und abgelehnt wurde. Sehen Sie sich OpenSpec Abgelehnte Vorschläge: Eine Konvention für Entscheidungs-Memory für das decision.md-Muster und die Konfigurationsregel an, die einen Agenten das Archiv durchsuchen lässt, bevor er erneut vorschlägt.

Wann OpenSpec passt und wann nicht

Gute Passform:

  • Brownfield-Codebasen, bei denen Sie überprüfbare Spezifikationen möchten, ohne das gesamte System vorab zu dokumentieren.
  • Solo-Entwickler und kleine Teams, die eine leichtere Form als Spec Kit wünschen, aber trotzdem einen schriftlichen Plan vor dem Code erhalten möchten.
  • Arbeit, die mehrere Dateien, eine Schema-Änderung oder etwas überspannt, für das ein Junior-Engineer vernünftigerweise ein kurzes Design-Dokument wollen würde.
  • Teams, die bereits verpflichtet sind, Pläne in Pull Requests zu überprüfen – Delta-Spezifikationen diffen sauber, da sie nur beschreiben, was sich geändert hat.

Schlechtere Passform:

  • Einzeilen-Bugfixes und Wegwerf-Prototypen, bei denen der Vorschlag-Review-Schritt 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 das Entscheidungsframework im Tool-Vergleich für dort, wo jedes Tool gewinnt.
  • Cross-Repo-Features heute, außer Sie sind bereit, OpenSpecs Beta-Feature stores auszuprobieren, das die Planung in ein eigenes geteiltes Repository verlagert, damit mehrere Codebasen und Agenten denselben Plan lesen können.
  • Jeder, der noch entscheidet, ob ein gegebenes Feature überhaupt eine Spezifikation verdient – lesen Sie zuerst Spezifikationsgetriebene Entwicklung vs. Vibe Coding, da OpenSpec nur hilft, wenn Sie bereits entschieden haben, dass Struktur den Overhead wert ist.

Fazit

OpenSpecs Wette ist, dass der größte Schmerz der Spezifikationsgetriebenen Entwicklung von der Formalität kommt, nicht von der zugrunde liegenden Idee, sich vor dem Vorhandensein von Code über einen Plan zu einigen. Deltas anstelle von vollständigen Neuschreibungen, keine gesperrten Phasen und ein Brownfield-first-Workflow machen es merklich leichter als Spec Kit oder Kiro, es auf einer Codebasis einzuführen, die man nicht von Grund auf gebaut hat. Die Trade-offs sind aber auch real – Spezifikationsaufblähung ist ein echtes Risiko ohne Disziplin, die Konfliktbehandlung bei gleichzeitigen Änderungen an einer Anforderung reift noch, und das Ökosystem ist jünger als GitHubs eigenes Tooling. Installieren Sie es auf einem echten Projekt, laufen Sie eine kleine Änderung durch den explore-propose-apply-archive-Zyklus von Anfang bis Ende und entscheiden Sie dann, ob die leichtere Form sich gegen Ihre tatsächliche Arbeitslast lohnt.

Abonnieren

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