OpenSpec

Erste Schritte ​

Dieser Leitfaden erklärt, wie OpenSpec funktioniert, nachdem du es installiert und initialisiert hast. Installationsanweisungen findest du in der README oder im Installationsleitfaden. Neu in der gesamten Dokumentation? Die Dokumentations-Startseite bietet eine Übersicht über alles.

Wo gebe ich diese Befehle ein? Es gibt zwei Orte, und das Verwechseln ist der häufigste anfängliche Stolperstein.

  • openspec ...-Befehle (wie openspec init) werden in deinem Terminal ausgeführt.
  • /opsx:...-Befehle (wie /opsx:propose) werden im Chat deines KI-Assistenten ausgeführt, in demselben Feld, in dem du ihn um Code bitten würdest.

Es gibt keinen separaten „interaktiven Modus“, den du starten musst. Du gibst einfach den Slash-Befehl im Chat ein, und dein Assistent übernimmt von dort. Vollständige Erklärung: So funktionieren Befehle.

Deine ersten fünf Minuten ​

Der gesamte Ablauf, wobei jeder Schritt mit dem Ort markiert ist, an dem er stattfindet:

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (optional: think it through first)
AI CHAT      /opsx:propose add-dark-mode      (AI drafts the plan; you review it)
AI CHAT      /opsx:apply                      (AI builds it)
AI CHAT      /opsx:archive                    (specs updated, change filed away)

Zwei Terminal-Schritte zum Einrichten, danach arbeitest du im Chat. Der Rest dieses Leitfadens erläutert, was jeder Schritt bewirkt und was du sehen wirst.

Möchtest du den Terminal-Teil nicht selbst machen? Füge den Setup-Prompt in deinen Assistenten ein, und er erledigt beide Zeilen und berichtet dann, was er erstellt hat.

Noch nicht sicher, was du bauen sollst? Beginne mit /opsx:explore. Es ist ein risikoloser Denkpartner, der deine Codebasis liest, Optionen abwägt und eine vage Idee zu einem konkreten Plan schärft – alles bevor irgendein Artefakt oder Code existiert. Wenn das Bild klar ist, übergibt es an /opsx:propose. Das ist die beste Gewohnheit für die Arbeit mit einer KI, die ansonsten zuversichtlich das Falsche bauen würde. Siehe den Explore-Leitfaden.

Wie es funktioniert ​

OpenSpec hilft dir und deinem KI-Codierungsassistenten, sich darauf zu einigen, was gebaut werden soll, bevor irgendein Code geschrieben wird.

Standard-Schnellpfad (Kernprofil):

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (optional)

Beginne mit /opsx:explore, wenn du herausfindest, was du tun sollst, oder springe direkt zu /opsx:propose, wenn du es bereits weißt. Explore ist im Standardprofil enthalten, also immer verfügbar, wenn du es brauchst.

Erweiterter Pfad (benutzerdefinierte Workflow-Auswahl):

text
/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Das standardmäßige globale Profil ist core, das propose, explore, apply, update, sync und archive enthält. Du kannst die erweiterten Workflow-Befehle mit openspec config profile und dann openspec update aktivieren.

Was OpenSpec erstellt ​

Nach dem Ausführen von openspec init hat dein Projekt diese Struktur:

openspec/
├── specs/              # Source of truth (your system's behavior)
│   └── <domain>/
│       └── spec.md
├── changes/            # Proposed updates (one folder per change)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta specs (what's changing)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Project configuration (optional)

Zwei wichtige Verzeichnisse:

  • specs/ – Die Quelle der Wahrheit. Diese Spezifikationen beschreiben, wie sich dein System derzeit verhält. Organisiert nach Domänen (z. B. specs/auth/, specs/payments/).

  • changes/ – Vorgeschlagene Änderungen. Jede Änderung erhält einen eigenen Ordner mit allen zugehörigen Artefakten. Wenn eine Änderung abgeschlossen ist, werden ihre Spezifikationen in das Hauptverzeichnis specs/ übernommen.

Artefakte verstehen ​

Jeder Änderungsordner enthält Artefakte, die die Arbeit leiten:

ArtefaktZweck
proposal.mdDas „Warum“ und „Was“ – erfasst Absicht, Umfang und Ansatz
specs/Delta-Spezifikationen, die ADDED/MODIFIED/REMOVED-Anforderungen zeigen
design.mdDas „Wie“ – technischer Ansatz und Architekturentscheidungen
tasks.mdImplementierungs-Checkliste mit Kontrollkästchen

Artefakte bauen aufeinander auf:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            update as you learn

Du kannst jederzeit zu früheren Artefakten zurückkehren und sie verfeinern, wenn du während der Implementierung mehr lernst.

So funktionieren Delta-Spezifikationen ​

Delta-Spezifikationen sind das Schlüsselkonzept in OpenSpec. Sie zeigen, was sich relativ zu deinen aktuellen Spezifikationen ändert.

Das Format ​

Delta-Spezifikationen verwenden Abschnitte, um die Art der Änderung anzugeben:

markdown
# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

Was beim Archivieren passiert ​

Wenn du eine Änderung archivierst:

  1. ADDED-Anforderungen werden an die Haupt-Spezifikation angehängt
  2. MODIFIED-Anforderungen ersetzen die vorhandene Version
  3. REMOVED-Anforderungen werden aus der Haupt-Spezifikation gelöscht

Der Änderungsordner wird für die Audit-Historie nach openspec/changes/archive/ verschoben.

Beispiel: Deine erste Änderung ​

Gehen wir durch, wie man einem Anwendungsbeispiel einen Dunkelmodus hinzufügt.

1. Die Änderung starten (Standard) ​

text
You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

Wenn du das erweiterte Workflow-Profil aktiviert hast, kannst du dies auch in zwei Schritten tun: /opsx:new und dann /opsx:ff (oder /opsx:continue inkrementell).

2. Was erstellt wird ​

proposal.md – erfasst die Absicht:

markdown
# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

specs/ui/spec.md – Delta mit neuen Anforderungen:

markdown
# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

tasks.md – Implementierungs-Checkliste:

markdown
# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

3. Implementieren ​

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

Wenn du während der Implementierung feststellst, dass das Design angepasst werden muss, aktualisiere einfach das Artefakt und fahre fort.

4. Archivieren ​

You: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

Deine Delta-Spezifikationen sind jetzt Teil der Haupt-Spezifikationen und dokumentieren, wie dein System funktioniert.

Überprüfen und Reviewen ​

Verwende die CLI, um deine Änderungen zu überprüfen:

bash
# List active changes
openspec list

# View change details
openspec show add-dark-mode

# Validate spec formatting
openspec validate add-dark-mode

# Interactive dashboard
openspec view

Nächste Schritte ​