OpenSpec-Einstieg: Mit Spezifikationsdokumenten die Grenzen eines KI-Zusammenarbeits-Frameworks sauber halten

Einstieg | ca. 15 Minuten | Du beherrschst die Kernkonzepte von OpenSpec (Delta-Specs, Artifact-Abhängigkeitsgraf), den Initialisierungsprozess, den OPSX-Workflow (propose → apply → archive) sowie die parallele Verwaltung mehrerer Änderungen

---

Projektüberblick

Wir fangen mit einer Sache an, die wir einfach anerkennen müssen: Hast du beim Programmieren mit einem KI-Coding-Assistant schon einmal so etwas erlebt – dass die KI, während ihr euch unterhaltet, plötzlich auch an Stellen etwas ändert, die du eigentlich gar nicht anfassen wolltest; oder dass sie beim Wechsel des Gesprächskontexts komplett vergisst, was vorher besprochen wurde; oder dass Funktionen, die du die KI neu schreiben lässt, am Ende schlicht nicht das sind, was du dir wirklich erhofft hast?

Das liegt nicht daran, dass die KI zu dumm ist – sondern daran, dass die Anforderungen nie wirklich „abgezeichnet“ wurden. Sie existieren nur im Chatverlauf, und dadurch ist der Spielraum der KI zum freien Interpretieren einfach zu groß.

OpenSpec macht das Ganze ganz schlicht: Bevor du überhaupt anfängst, Code zu schreiben, richtet ihr euch erst gemeinsam auf ein Spezifikationsdokument aus – und die KI handelt dann genau nach dieser Spezifikation. OpenSpec wurde von Fission-AI entwickelt, unterstützt 20+ KI-Programmierwerkzeuge (Claude Code, Cursor, Windsurf usw.) und ist im Kern eine leichte Schicht für Spezifikations- und Spezifikationsmanagement für KI-Coding-Assistant.

---

Zielgruppe

• Entwickler, die täglich KI-Programmier-Assistants nutzen
• Ingenieure, die in der Teamarbeit unter uneinheitlichem Verständnis von Anforderungen zwischen Mensch und KI leiden
• Produktmanager, die die Ausgabe der KI besser steuerbar machen möchten

Zentrale Abhängigkeiten und Umgebung

• Node.js 20.19.0+

Vollständiger Projekt-Strukturbaum

openspec/
├── specs/                    # Aktuelle Verhaltensspezifikation des Systems (nach Domänen gegliedert)
│   └── <domain>/spec.md
├── changes/                  # Änderungsanträge (pro Änderung ein Ordner)
│   ├── <change-name>/
│   │   ├── proposal.md       # Motivation + Scope + Ansatz
│   │   ├── specs/           # Delta-Spezifikationen (ADDED/MODIFIED/REMOVED)
│   │   │   └── <domain>/spec.md
│   │   ├── design.md         # Technisches Design
│   │   └── tasks.md          # Umsetzungs-Checkliste
│   └── archive/               # Archivierte Historie
└── config.yaml               # Projektkonfiguration (optional)

---

Schritt für Schritt

Schritt 1: OpenSpec global installieren

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

Nach der Installation kurz verifizieren:

openspec --version
# 1.2.0

Schritt 2: Projekt initialisieren

Wechsle in dein Projektverzeichnis und führe den Initialisierungsbefehl aus:

cd your-project
openspec init

Dieser Befehl macht drei Dinge:

1. Erstellt die openspec/-Verzeichnisstruktur
2. Erzeugt die KI-Fähigkeitsdateien unter .claude/ (damit der KI-Assistant die /opsx:*-Kommandos erkennen kann)
3. Fragt dich, ob du die Projektkonfigurationsdatei config.yaml erstellen möchtest (optional, um Projektkontext einzuspeisen)

Nach der Initialisierung enthält dein Projekt diese Verzeichnisse:

openspec/
├── specs/       # Aktuelle Verhaltensspezifikation des Systems (leerer Ordner, wartet auf Befüllung)
├── changes/     # Änderungsantrags-Verzeichnis (leerer Ordner)
└── config.yaml  # Projektkonfiguration (falls erstellt)

Schritt 3: OPSX-Workflow-Extension aktivieren

Die neu installierte OpenSpec ist standardmäßig im core-Modus – mit nur 4 Befehlen: propose, explore, apply, archive. Wenn du den vollständigen Workflow nutzen möchtest (inkl. new, continue, ff, verify, bulk-archive usw.), dann:

openspec config profile
# expanded oder full auswählen
openspec update

openspec update erzeugt die KI-Fähigkeitsdateien basierend auf deinem ausgewählten Profile neu, damit du in den Gesprächen mit der KI mehr Befehle verwenden kannst.

Schritt 4: Die erste Änderung erstellen – Dark Mode hinzufügen

Jetzt lass die KI dir beim Erstellen einer Änderung helfen. Nehmen wir als Beispiel: „Der App einen Dark Mode hinzufügen“. Sag der KI einfach direkt:

/opsx:propose add-dark-mode

Die KI legt automatisch vier Artifact-Dateien unter openspec/changes/add-dark-mode/ an:

openspec/changes/add-dark-mode/
├── proposal.md     # Wozu ist diese Änderung da? Scope? Ansatz?
├── specs/
│   └── ui/spec.md  # Delta-Spezifikation für die UI-Domäne
├── design.md       # Wie ist der technische Ansatz gedacht?
└── tasks.md        # Was genau soll umgesetzt werden? Schritt für Schritt

proposal.md sieht so aus (wird von der KI automatisch generiert; du und die KI könnt ihr gemeinsam anpassen):

# Proposal: Add Dark Mode

## Intent
Der Nutzer wünscht sich einen Dark Mode, um die Augenermüdung bei der Nutzung in der Nacht zu reduzieren.

## Scope
- Einen Theme-Umschaltknopf in den Einstellungen hinzufügen
- Unterstützung für die Erkennung der Systempräferenz
- Persistierung der Präferenz in localStorage

## Approach
CSS-Variablen für das Theme verwenden und den Status mit React Context verwalten.

specs/ui/spec.md ist die entscheidende Delta-Spezifikation mit folgendem Format:

# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
Das System SHALL es Nutzerinnen und Nutzern ermöglichen, zwischen einem Light- und einem Dark-Theme umzuschalten.

#### Scenario: Manuelles Umschalten
- GIVEN Der Nutzer befindet sich auf einer beliebigen Seite
- WHEN Der Nutzer klickt auf den Theme-Umschaltknopf
- THEN Das Theme wird sofort umgeschaltet, und die Präferenz wird über Sitzungen hinweg persistiert

#### Scenario: Systempräferenz
- GIVEN Der Nutzer hat keine gespeicherte Präferenz
- WHEN Die Anwendung startet
- THEN Es wird das vom System bevorzugte Farbschema verwendet

tasks.md ist die Checkliste zur Umsetzung:

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Erstelle ThemeContext (light/dark-Status)
- [ ] 1.2 Füge Definitionen für CSS-Variablen für Farben hinzu
- [ ] 1.3 Implementiere localStorage-Persistierung

## 2. UI Components
- [ ] 2.1 Erstelle ThemeToggle-Komponente
- [ ] 2.2 Füge in der Einstellungsseite einen Umschalter hinzu
- [ ] 2.3 Füge einen Schnellumschalter in den Header ein

## 3. Styling
- [ ] 3.1 Definiere Farbschema für das Dark Theme
- [ ] 3.2 Lasse bestehende Komponenten CSS-Variablen verwenden

Schritt 5: Implementierungsaufgaben ausführen

Nachdem das Spezifikationsdokument bestätigt ist, führe die Implementierung aus:

/opsx:apply

Die KI prüft die Aufgaben aus tasks.md der Reihe nach; für jede erledigte Aufgabe setzt sie ein Häkchen. Du wirst merken, dass sich das Verhalten der KI verändert – sie spielt nicht mehr frei, sondern schreitet strikt anhand von tasks.md voran. Wenn du während der Umsetzung feststellst, dass das Design nicht passt, kannst du direkt design.md anpassen und dann erneut apply ausführen; die KI macht automatisch weiter.

Schritt 6: Validieren und Änderung archivieren

Verifizieren (optional, aber empfohlen):

/opsx:verify

Die KI prüft deine Umsetzung in drei Dimensionen:

Archivieren:

/opsx:archive

Das Archivieren macht zwei Dinge:

1. Die Delta-Spezifikation wird in die Hauptspezifikation openspec/specs/ui/spec.md zusammengeführt.
2. Der Änderungsordner wird nach openspec/changes/archive/2026-04-11-add-dark-mode/ verschoben.

Nach Abschluss des Archivierungsschritts ist die Spezifikationsdatei des Systems aktualisiert – du hast zusätzlich eine vollständige Historie der Änderungen.

Schritt 7: Parallele Verwaltung mehrerer Änderungen

In der realen Entwicklung wird man zwischendurch oft unterbrochen, um andere Probleme zu lösen. OpenSpec unterstützt parallele Änderungen:

# Angenommen, du arbeitest gerade an add-dark-mode und plötzlich muss ein Bug gefixt werden
/opsx:new fix-login-redirect

# Bug-Fix normal abschließen
/opsx:ff
/opsx:apply
/opsx:archive

# Zurück zur Dark-Mode-Arbeit
/opsx:apply add-dark-mode

Wenn du mehrere Änderungen abgeschlossen hast, archivierst du sie gemeinsam:

/opsx:bulk-archive

OpenSpec erkennt automatisch Spezifikationskonflikte (beide Änderungen ändern specs/ui/) und führt sie in zeitlicher Reihenfolge zusammen.

Schritt 8: Schema anpassen

Der OPSX-Workflow von OpenSpec basiert auf einem Schema; du kannst die Arten von Artifacts und ihre Abhängigkeitsbeziehungen vollständig selbst definieren. Zum Beispiel, wenn du einen Workflow „erst recherchieren, dann vorschlagen“ möchtest:

# Ein neues Schema aus dem Default-Schema ableiten
openspec schema fork spec-driven research-first

Die erzeugte Schema-Struktur:

openspec/schemas/research-first/
├── schema.yaml
└── templates/
    ├── research.md
    ├── proposal.md
    └── tasks.md

Das entsprechende Abhängigkeitsdiagramm wird:

research ──► proposal ──► tasks

In schema.yaml wird definiert:

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []

  - id: proposal
    generates: proposal.md
    requires: [research]

  - id: tasks
    generates: tasks.md
    requires: [proposal]

Schritt 9: CLI häufige Befehle – Kurzüberblick

# Initialisierung
openspec init

# KI-Fähigkeitsdateien aktualisieren (muss bei jedem Upgrade oder nach einem Profile-Wechsel ausgeführt werden)
openspec update

# Aktuelle Konfiguration anzeigen
openspec config show

# Workflow-Profile wechseln
openspec config profile

# Aktive Änderungen anzeigen
openspec list

# Details zu einer Änderung anzeigen
openspec show add-dark-mode

# Format prüfen
openspec validate add-dark-mode

# Interaktives Dashboard
openspec view

# Schema-Verwaltung
openspec schemas              # verfügbare Schemas auflisten
openspec schema which --all   # Schema-Quelle anzeigen
openspec schema validate my-schema  # Schema validieren

---

Häufige Probleme beheben

1. Die KI findet den Befehl /opsx:propose nicht

Das ist das häufigste Problem. Nach dem Ausführen von openspec init muss der KI-Assistant die Skill-Dateien neu laden. Führe aus:

openspec update

Dann starte das Gespräch neu. Wenn die KI es immer noch nicht erkennt, prüfe manuell, ob das Verzeichnis .claude/ existiert.

2. openspec init meldet einen Node.js-Versionsfehler

node --version
# sicherstellen, dass >= 20.19.0

# falls die Version zu niedrig ist, mit nvm aktualisieren
nvm install 20 && nvm use 20

3. Konflikt beim Zusammenführen von Delta-Spezifikationen

Beim Ausführen von /opsx:bulk-archive: Wenn zwei Änderungen dieselbe Spezifikationsdatei ändern, erkennt OpenSpec das und weist dich darauf hin. Standardmäßig wird nach Zeitreihenfolge zusammengeführt; falls du manuell eingreifen musst:

# zuerst eine Änderung separat archivieren
/opsx:archive fix-login-redirect

# dann die andere archivieren
/opsx:archive add-dark-mode

4. Laden eines benutzerdefinierten Schemas fehlgeschlagen

Meist liegt das an einem Syntaxfehler in schema.yaml. Prüfe:

openspec schema validate my-schema

Häufige Fehler: Falsche YAML-Einrückungen; das Feld requires eines Artifacts verweist auf eine nicht existierende ID (zirkuläre Abhängigkeit).

5. Das von der KI generierte Spezifikationsformat erfüllt nicht die Anforderungen

Du kannst in openspec/config.yaml Regeln hinzufügen:

rules:
  specs:
    - Verwende das GIVEN/WHEN/THEN-Format, um jedes Szenario zu beschreiben
    - Jede Requirement muss mindestens ein Scenario enthalten

Diese Regeln werden als Anweisungen in die von der KI generierten Spezifikationen eingespeist.

6. Während /opsx:apply überspringt die KI manche Aufgaben

Sag der KI direkt:

Bitte führe die Aufgaben in der Reihenfolge aus, wie in tasks.md vorgegeben. Aufgabe 1.3 ist noch nicht abgeschlossen – nicht überspringen.

Das fluid-Feature von OpenSpec erlaubt es dir, jederzeit Artifacts zu bearbeiten: Nachdem du tasks.md geändert hast, führe erneut apply aus – die KI setzt dort fort, wo sie zuletzt aufgehört hat.

---

Weiterführende Lektüre / Fortgeschrittene Ausrichtung

Delta-Specs – Format im Detail: Die drei Änderungsarten ADDED/MODIFIED/REMOVED haben jeweils eigene Semantik – ADDED fügt neue Anforderungen hinzu, MODIFIED ersetzt bestehende Anforderungen, REMOVED entfernt veraltete Anforderungen. Wenn du ihre Zusammenführungsregeln beherrschst, ist das der Schlüssel, um OpenSpec richtig zu nutzen.

OPSX vs. Legacy-Workflow – Vergleich: OpenSpec v1.x nutzt den Legacy-Workflow (/openspec:proposal), v1.2+ setzt vor allem auf OPSX. Der zentrale Unterschied: Legacy ist phase-locked (entweder alles oder nichts), OPSX ist fluid (du kannst jederzeit beliebige Artifacts bearbeiten).

Leitfaden für die Integration von 20+ KI-Tools: OpenSpec erzeugt Skill-Dateien über das Verzeichnis .claude/skills/ und ist mit Claude Code, Cursor, Windsurf, Copilot und anderen gängigen Tools kompatibel. Siehe dazu docs/supported-tools.md.

Team-Slack-Integration: Für Enterprise-Teams kann man [email protected] kontaktieren, um Support in einem dedizierten Slack-Kanal zu erhalten – ideal für Spezifikationsmanagement- und Review-Prozesse in Szenarien mit mehreren Beteiligten.

Tiefergehende Projektkonfiguration: Neben context und rules kannst du auch per config.yaml ein Default-Schema setzen und Projekt-Technik-Stack-Infos einspeisen (z. B. Testframework, Code-Style-Konventionen), damit die von der KI generierten Spezifikationen noch näher an deinem echten Projekt sind.