Was ist OpenSpec? Installation und Workflows

OpenSpec ist ein schlankes Framework für spezifikationsgetriebene Entwicklung (Spec-Driven Development). Es fügt zwischen Ihnen und Ihrem KI-Coding-Assistenten eine Schicht der Vereinbarung ein: Zuerst festhalten, was gebaut werden soll, den Plan prüfen und erst dann Code schreiben, statt Anforderungen nur im Chatverlauf zu belassen. Es steht unter der MIT-Lizenz, unterstützt mehr als 30 KI-Coding-Tools, und auch der eigene Workflow von HagiCode basiert darauf. Diese Seite zeigt den kürzesten Weg zur Installation und zur ersten vollständigen Änderung; die ausführlichen Anleitungen werden auf einer eigenen Website gepflegt.

Kernkonzepte

OpenSpec besteht aus fünf Ideen:

1. Specs sind die Quelle der Wahrheit. Sie beschreiben, wie sich das System jetzt verhält, liegen in openspec/specs/, sind nach Bereichen geordnet und bestehen aus Anforderungen und Szenarien.
2. Eine Änderung (change) ist eine Arbeitseinheit. Um Verhalten hinzuzufügen, zu ändern oder zu entfernen, legen Sie unter openspec/changes/ einen Ordner an, der Vorschlag, Design, Aufgabenliste und Spec-Änderungen dieser Arbeit enthält.
3. Delta-Specs beschreiben nur, was sich ändert. Innerhalb einer Änderung schreiben Sie nicht die ganze Spec neu, sondern ADDED, MODIFIED und REMOVED; deshalb eignet sich OpenSpec gut zum Bearbeiten bestehender Systeme.
4. Artefakte bauen aufeinander auf. proposal (warum) → specs (was) → design (wie) → tasks (Schritte) → Umsetzung. Sie sind Hilfsmittel, keine Hürden, und Sie können jederzeit zu jedem davon zurückkehren.
5. Das Archivieren führt die Änderung in die Wahrheit zurück. Ist die Arbeit erledigt, werden die Delta-Specs in die Haupt-Specs übernommen und der Änderungsordner wird mit Datum nach changes/archive/ verschoben.

Installation

Sie benötigen Node.js 20.19.0 oder höher (für andere HagiCode-Komponenten wird 24 oder höher empfohlen, siehe Node.js installieren).

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

Unter macOS und Linux können Sie auch Homebrew verwenden: brew install openspec. Auch pnpm, yarn (1.x) und bun können es global installieren, OpenSpec läuft aber weiterhin auf Node.js.

Wechseln Sie dann in Ihr Projektverzeichnis und initialisieren Sie es:

cd your-project
openspec init

Die Initialisierung fragt, welche KI-Tools Sie verwenden, und erzeugt dafür Skill- oder Befehlsdateien. Ohne Rückfragen geht es mit openspec init --tools claude,cursor; die Tool-IDs finden Sie unter Unterstützte Tools.

Ihre erste vollständige Änderung

Slash-Befehle geben Sie im Chat Ihres KI-Assistenten ein, nicht im Terminal:

/opsx:explore            # noch unsicher? Die KI liest den Code und wägt Optionen ab
/opsx:propose add-dark-mode   # Änderungsordner anlegen: proposal, specs, design, tasks
/opsx:apply              # die Aufgabenliste umsetzen
/opsx:archive            # archivieren; Delta-Specs fließen in die Haupt-Specs

/opsx:propose legt openspec/changes/add-dark-mode/ mit proposal.md, specs/, design.md und tasks.md an. Specs sind einfaches Markdown ohne besondere Syntax:

## 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

Die KI schreibt sie, und Sie prüfen den Plan, bevor Code entsteht. Das Standardprofil enthält propose, explore, apply, update, sync und archive. Für den erweiterten Ablauf (new, continue, ff, verify, bulk-archive und mehr) wählen Sie ihn mit openspec config profile aus und wenden ihn mit openspec update an.

Befehlsnamen unterscheiden sich je nach Assistent leicht

/opsx:propose ist die kanonische Schreibweise. In Cursor und GitHub Copilot lautet sie /opsx-propose, in Amazon Q @opsx-propose und in Codex $openspec-propose. openspec init gibt die passende Form für die gewählten Tools aus.

Aktualisieren

npm install -g @fission-ai/openspec@latest   # Paket aktualisieren
openspec update                              # KI-Anweisungsdateien in jedem Projekt auffrischen

Wenn Sie mit Homebrew installiert haben, verwenden Sie brew upgrade openspec.

Häufige Probleme

• openspec: command not found: Das globale npm-Verzeichnis liegt nicht im PATH. Führen Sie npm prefix -g aus; unter macOS und Linux nehmen Sie das Unterverzeichnis bin/ dieses Verzeichnisses in den PATH auf, unter Windows das Verzeichnis selbst.
• „Requires Node.js 20.19.0 or higher“: Prüfen Sie die Version mit node --version und aktualisieren Sie Node.js.
• /opsx:propose erscheint nicht im Chat: Stellen Sie sicher, dass Sie den Befehl im Assistenten und nicht im Terminal eingeben, führen Sie openspec update aus, um die Dateien neu zu erzeugen, und starten Sie den Assistenten neu. Tools, die nur Skills unterstützen, etwa Codex, brauchen stattdessen die Schreibweise $openspec-propose.
• Die Initialisierung hat Ihr Tool nicht eingerichtet: Führen Sie openspec init erneut aus oder übergeben Sie --tools.

Vollständige Dokumentation

OpenSpec-Dokumentation auf Deutsch öffnen

• OpenSpec installieren
• Erste Schritte
• Workflows
• Fehlerbehebung

Weiterführende Links

• Wenn Sie zwischen OpenSpec und GitHubs Spec Kit abwägen, lesen Sie Spec Kit vs. OpenSpec.
• Die Praxis von HagiCode auf Basis von OpenSpec: Optimierung der OpenSpec-Leistung in verschiedenen Phasen mit verschiedenen Agenten: HagiCode Praxiszusammenfassung und Was ist MonoSpecs: Warum es eine Weiterentwicklung und Erweiterung von OpenSpec ist.