Konzepte
Dieser Leitfaden erläutert die Grundideen hinter OpenSpec und wie sie zusammenwirken. Für die praktische Anwendung siehe Erste Schritte und Workflows.
Philosophie
OpenSpec basiert auf vier Prinzipien:
fluid not rigid — no phase gates, work on what makes sense
iterative not waterfall — learn as you build, refine as you go
easy not complex — lightweight setup, minimal ceremony
brownfield-first — works with existing codebases, not just greenfieldWarum diese Prinzipien wichtig sind
Fluid not rigid. Traditionelle Spezifikationssysteme binden Sie an Phasen: Zuerst planen Sie, dann implementieren Sie, und dann ist es fertig. OpenSpec ist flexibler — Sie können Artefakte in jeder Reihenfolge erstellen, die für Ihre Arbeit sinnvoll ist.
Iterative not waterfall. Anforderungen ändern sich. Das Verständnis vertieft sich. Was am Anfang wie ein guter Ansatz wirkte, hält nach dem Betrachten des Codebasises möglicherweise nicht stand. OpenSpec nimmt diese Realität an.
Easy not complex. Manche Spezifikationsframeworks erfordern umfangreiche Einrichtung, starre Formate oder aufwendige Prozesse. OpenSpec hält sich aus dem Weg. Initialisieren Sie in Sekunden, beginnen Sie sofort mit der Arbeit und passen Sie nur dann an, wenn Sie es benötigen.
Brownfield-first. Die meisten Softwareprojekte bestehen nicht darin, von Grund auf neu zu bauen — sie bestehen darin, bestehende Systeme zu modifizieren. Der delta-basierte Ansatz von OpenSpec macht es einfach, Änderungen an bestehendem Verhalten zu spezifizieren, nicht nur neue Systeme zu beschreiben.
Das große Bild
OpenSpec organisiert Ihre Arbeit in zwei Hauptbereiche:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Source of truth │◄─────│ Proposed modifications │ │
│ │ How your system │ merge│ Each change = one folder │ │
│ │ currently works │ │ Contains artifacts + deltas │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Specs sind die Quelle der Wahrheit – sie beschreiben, wie Ihr System aktuell funktioniert.
Changes sind vorgeschlagene Änderungen – sie leben in separaten Ordnern, bis Sie bereit sind, sie zu übernehmen.
Diese Trennung ist entscheidend. Sie können an mehreren Änderungen parallel arbeiten, ohne Konflikte. Sie können eine Änderung überprüfen, bevor sie die Haupt-Specs beeinflusst. Und wenn Sie eine Änderung archivieren, werden deren Deltas sauber in die Quelle der Wahrheit übernommen.
Specs
Specs beschreiben das Verhalten Ihres Systems mithilfe strukturierter Anforderungen und Szenarien.
Struktur
openspec/specs/
├── auth/
│ └── spec.md # Authentication behavior
├── payments/
│ └── spec.md # Payment processing
├── notifications/
│ └── spec.md # Notification system
└── ui/
└── spec.md # UI behavior and themesOrganisieren Sie Specs nach Domänen – logische Gruppierungen, die für Ihr System sinnvoll sind. Häufige Muster:
- Nach Funktionsbereich:
auth/,payments/,search/ - Nach Komponente:
api/,frontend/,workers/ - Nach begrenztem Kontext:
ordering/,fulfillment/,inventory/
Spec-Format
Ein Spec enthält Anforderungen, und jede Anforderung hat Szenarien:
# Auth Specification
## Purpose
Authentication and session management for the application.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.
#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued
### Requirement: Session Expiration
The system MUST expire sessions after 30 minutes of inactivity.
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticateWichtige Elemente:
| Element | Zweck |
|---|---|
## Purpose | Beschreibung auf hoher Ebene der Domäne dieses Specs |
### Requirement: | Ein spezifisches Verhalten, das das System haben muss |
#### Scenario: | Ein konkretes Beispiel der Anforderung in Aktion |
| SHALL/MUST/SHOULD | RFC-2119-Schlüsselwörter, die die Stärke der Anforderung angeben |
Warum Specs so strukturiert werden
Anforderungen sind das „Was" – sie legen fest, was das System tun soll, ohne die Implementierung zu spezifizieren.
Szenarien sind das „Wann" – sie liefern konkrete Beispiele, die verifiziert werden können. Gute Szenarien:
- Sind testbar (man könnte einen automatisierten Test dafür schreiben)
- Abdecken sowohl den glücklichen Pfad als auch Randfälle
- Verwenden Given/When/Then oder ein ähnliches strukturiertes Format
RFC-2119-Schlüsselwörter (SHALL, MUST, SHOULD, MAY) vermitteln die Absicht:
- MUST/SHALL — absolute Anforderung
- SHOULD — empfohlen, aber Ausnahmen existieren
- MAY — optional
Was ein Spec ist (und was nicht)
Ein Spec ist ein Verhaltensvertrag, kein Implementierungsplan.
Guter Spec-Inhalt:
- Beobachtbares Verhalten, auf das Benutzer oder nachgelagerte Systeme angewiesen sind
- Eingaben, Ausgaben und Fehlerbedingungen
- Externe Einschränkungen (Sicherheit, Datenschutz, Zuverlässigkeit, Kompatibilität)
- Szenarien, die getestet oder explizit validiert werden können
Vermeiden Sie in Specs:
- Interne Klassen-/Funktionsnamen
- Bibliotheks- oder Framework-Wahl
- Schritt-für-Schritt-Implementierungsdetails
- Detaillierte Ausführungspläne (diese gehören in
design.mdodertasks.md)
Schnelltest:
- Wenn sich die Implementierung ändern kann, ohne dass sich das extern sichtbare Verhalten ändert, gehört es wahrscheinlich nicht in das Spec.
Leichtgewicht halten: Progressive Strenge
OpenSpec zielt darauf ab, Bürokratie zu vermeiden. Verwenden Sie die leichteste Ebene, die die Änderung dennoch überprüfbar macht.
Lite-Spec (Standard):
- Kurze verhaltensorientierte Anforderungen
- Klarer Umfang und Nicht-Ziele
- Einige konkrete Abnahmeprüfungen
Voll-Spec (für höheres Risiko):
- Änderungen über Teams oder Repos hinweg
- API-/Vertragsänderungen, Migrationen, Sicherheits-/Datenschutzbedenken
- Änderungen, bei denen Mehrdeutigkeiten wahrscheinlich teure Nacharbeit verursachen
Die meisten Änderungen sollten im Lite-Modus bleiben.
Mensch + Agenten-Zusammenarbeit
In vielen Teams erkunden Menschen und Agenten entwerfen Artefakte. Die beabsichtigte Schleife ist:
- Der Mensch liefert Absicht, Kontext und Einschränkungen.
- Der Agent wandelt dies in verhaltensorientierte Anforderungen und Szenarien um.
- Der Agent hält Implementierungsdetails in
design.mdundtasks.md, nicht inspec.md. - Validierung bestätigt Struktur und Klarheit vor der Implementierung.
Dies hält Specs für Menschen lesbar und für Agenten konsistent.
Änderungen
Eine Änderung ist eine vorgeschlagene Modifikation Ihres Systems, verpackt als Ordner mit allem, was zum Verständnis und zur Implementierung benötigt wird.
Änderungsstruktur
openspec/changes/add-dark-mode/
├── proposal.md # Why and what
├── design.md # How (technical approach)
├── tasks.md # Implementation checklist
├── .openspec.yaml # Change metadata (optional): schema, created, skip_specs, retire_capabilities
└── specs/ # Delta specs
└── ui/
└── spec.md # What's changing in ui/spec.mdJede Änderung ist in sich geschlossen. Sie hat:
- Artefakte – Dokumente, die Absicht, Design und Aufgaben festhalten
- Delta-Specs – Spezifikationen für das, was hinzugefügt, geändert oder entfernt wird
- Metadaten – optionale Konfiguration für diese spezifische Änderung
Warum Änderungen Ordner sind
Das Verpacken einer Änderung als Ordner hat mehrere Vorteile:
- Alles zusammen. Vorschlag, Design, Aufgaben und Specs liegen an einem Ort. Kein Suchen an verschiedenen Orten.
- Paralleles Arbeiten. Mehrere Änderungen können gleichzeitig existieren, ohne sich zu widersprechen. Arbeiten Sie an
add-dark-mode, währendfix-auth-bugebenfalls in Arbeit ist. - Saubere Historie. Beim Archivieren werden Änderungen nach
changes/archive/verschoben, wobei ihr vollständiger Kontext erhalten bleibt. Sie können zurückblicken und verstehen, nicht nur was geändert wurde, sondern auch warum. - Überprüfungsfreundlich. Ein Änderungsordner ist einfach zu überprüfen – öffnen Sie ihn, lesen Sie den Vorschlag, prüfen Sie das Design, sehen Sie die Spec-Deltas.
Artefakte
Artefakte sind die Dokumente innerhalb einer Änderung, die die Arbeit leiten.
Der Artefakt-Fluss
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
why what how steps
+ scope changes approach to takeArtefakte bauen aufeinander auf. Jedes Artefakt liefert Kontext für das nächste.
Artefakt-Typen
Vorschlag (proposal.md)
Der Vorschlag erfasst Absicht, Umfang und Ansatz auf hoher Ebene.
# Proposal: Add Dark Mode
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and match system preferences.
## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage
Out of scope:
- Custom color themes (future work)
- Per-page theme overrides
## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.Wann der Vorschlag aktualisiert werden sollte:
- Umfangsänderungen (verengen oder erweitern)
- Absicht wird klarer (besseres Verständnis des Problems)
- Ansatz ändert sich grundlegend
Specs (Delta-Specs in specs/)
Delta-Specs beschreiben, was sich ändert im Vergleich zu den aktuellen Specs. Siehe Delta-Specs unten.
Design (design.md)
Das Design erfasst technischen Ansatz und Architekturentscheidungen.
# Design: Add Dark Mode
## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.
## Architecture Decisions
### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency
### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution
## Data Flow
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)Wann das Design aktualisiert werden sollte:
- Die Implementierung zeigt, dass der Ansatz nicht funktioniert
- Bessere Lösung gefunden
- Abhängigkeiten oder Einschränkungen ändern sich
Aufgaben (tasks.md)
Aufgaben sind die Implementierungs-Checkliste – konkrete Schritte mit Kontrollkästchen.
# 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
- [ ] 1.4 Add system preference detection
## 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.3 Test contrast ratios for accessibilityBewährte Praktiken für Aufgaben:
- Gruppieren Sie verwandte Aufgaben unter Überschriften
- Verwenden Sie hierarchische Nummerierung (1.1, 1.2, usw.)
- Halten Sie Aufgaben klein genug, um sie in einer Sitzung abzuschließen
- Haken Sie Aufgaben ab, wenn Sie sie erledigen
Delta-Specs
Delta-Specs sind das Schlüsselkonzept, das OpenSpec für die Entwicklung in Braunfeldern (Brownfield) funktionieren lässt. Sie beschreiben, was sich ändert, statt das gesamte Spec zu wiederholen.
Das Format
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.
#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation
#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP
## MODIFIED Requirements
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated
## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)Delta-Abschnitte
| Abschnitt | Bedeutung | Was beim Archivieren passiert |
|---|---|---|
## ADDED Requirements | Neues Verhalten | Wird an das Haupt-Spec angehängt |
## MODIFIED Requirements | Geändertes Verhalten | Ersetzt bestehende Anforderung |
## REMOVED Requirements | Veraltetes Verhalten | Aus dem Haupt-Spec gelöscht; das Entfernen der letzten Anforderung zieht die Fähigkeit zurück und löscht die Spec-Datei, wenn die Änderung retire_capabilities: true deklariert |
## Purpose | Wofür eine neue Fähigkeit da ist | Begründet den Zweck des zu erstellenden Haupt-Specs; wird ignoriert, wenn das Spec bereits existiert |
Warum Deltas statt vollständiger Specs
Klarheit. Ein Delta zeigt genau, was sich ändert. Beim Lesen eines vollständigen Specs müssten Sie es mental gegen die aktuelle Version diffferen.
Konfliktvermeidung. Zwei Änderungen können dieselbe Spec-Datei berühren, ohne zu kollidieren, solange sie unterschiedliche Anforderungen ändern.
Überprüfungseffizienz. Prüfer sehen die Änderung, nicht den unveränderten Kontext. Konzentration auf das, was wichtig ist.
Braunfeld-Tauglichkeit. Die meiste Arbeit ändert bestehendes Verhalten. Deltas machen Modifikationen zur ersten Klasse, nicht zum nachträglichen Gedanken.
Schemas
Schemas definieren die Artefakttypen und deren Abhängigkeiten für einen Workflow.
Funktionsweise von Schemas
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # Keine Abhängigkeiten, kann als Erstes erstellt werden
- id: specs
generates: specs/**/*.md
requires: [proposal] # Erfordert Proposal vor der Erstellung
- id: design
generates: design.md
requires: [proposal] # Kann parallel zu Specs erstellt werden
- id: tasks
generates: tasks.md
requires: [specs, design] # Erfordert sowohl Specs als auch Design zuerstArtefakte bilden einen Abhängigkeitsgraphen:
proposal
(Wurzelknoten)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(erfordert: (erfordert:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(erfordert:
specs, design)Abhängigkeiten sind Ermöglicher, keine Hürden. Sie zeigen, was erstellt werden kann, nicht was man als Nächstes erstellen muss. Man kann das Design überspringen, wenn es nicht benötigt wird. Man kann Specs vor oder nach dem Design erstellen – beide hängen nur vom Proposal ab.
Eingebaute Schemas
spec-driven (Standard)
Der Standard-Workflow für die spezifikationsgetriebene Entwicklung:
proposal → specs → design → tasks → implementGeeignet für: Die meisten Feature-Arbeiten, bei denen man sich vor der Implementierung auf die Specs einigen möchte.
Eigene Schemas
Erstellen Sie eigene Schemas für den Workflow Ihres Teams:
# Von Grund auf neu erstellen
openspec schema init research-first
# Oder ein bestehendes abzweigen
openspec schema fork spec-driven research-firstBeispiel für ein eigenes Schema:
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # Zuerst Forschung betreiben
- id: proposal
generates: proposal.md
requires: [research] # Proposal durch Forschung informiert
- id: tasks
generates: tasks.md
requires: [proposal] # Specs/Design überspringen, direkt zu Tasks gehenWeitere Details zur Erstellung und Verwendung eigener Schemas finden Sie unter Customization.
Archivierung
Die Archivierung schließt eine Änderung ab, indem ihre Delta-Specs in die Haupt-Specs gemergt und die Änderung zur Dokumentation des Verlaufs gespeichert wird.
Was bei der Archivierung passiert
Vor der Archivierung:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ merge
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
Nach der Archivierung:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Enthält nun die 2FA-Anforderungen
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Für die Historie erhalten
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdDer Archivierungsprozess
Deltas mergen. Jeder Abschnitt eines Delta-Specs (ADDED/MODIFIED/REMOVED) wird auf den entsprechenden Haupt-Spec angewendet.
In das Archiv verschieben. Der Änderungsordner wird mit einem Datumspräfix für die chronologische Ordnung nach
changes/archive/verschoben.Kontext bewahren. Alle Artefakte bleiben im Archiv intakt. Sie können jederzeit zurückblicken, um zu verstehen, warum eine Änderung vorgenommen wurde.
Warum Archivierung wichtig ist
Sauberer Zustand. Aktive Änderungen (changes/) zeigen nur laufende Arbeiten an. Abgeschlossene Arbeiten werden beiseite geräumt.
Prüfpfad. Das Archiv bewahrt den vollständigen Kontext jeder Änderung – nicht nur was sich geändert hat, sondern auch das Proposal, das erklärt, warum; das Design, das erklärt, wie; und die Tasks, die die geleistete Arbeit zeigen.
Spezifikationsentwicklung. Specs wachsen organisch, wenn Änderungen archiviert werden. Jeder Merge fügt seine Deltas hinzu und baut über die Zeit hinweg eine umfassende Spezifikation auf.
Wie alles zusammenpasst
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC FLOW │
│ │
│ ┌────────────────┐ │
│ │ 1. START │ /opsx:propose (core) oder /opsx:new (erweitert) │
│ │ CHANGE │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. CREATE │ /opsx:ff oder /opsx:continue (erweiterter Workflow) │
│ │ ARTIFACTS │ Erstellt proposal → specs → design → tasks │
│ │ │ (basierend auf Schema-Abhängigkeiten) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. IMPLEMENT │ /opsx:apply │
│ │ TASKS │ Durcharbeitung der Tasks, Abhaken │
│ │ │◄──── Artefakte aktualisieren, während man lernt │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. VERIFY │ /opsx:verify (optional) │
│ │ WORK │ Prüfen, ob die Implementierung den Specs entspricht │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARCHIVE │────►│ Delta-Specs werden in die Haupt-Specs │ │
│ │ CHANGE │ │ gemergt │ │
│ └────────────────┘ │ Änderungsordner wird ins Archiv verschoben │ │
│ │ Specs sind nun die aktualisierte │ │
│ │ Single Source of Truth │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘Der positive Kreislauf:
- Specs beschreiben das aktuelle Verhalten
- Änderungen schlagen Modifikationen vor (als Deltas)
- Die Implementierung macht die Änderungen real
- Die Archivierung merged Deltas in die Specs
- Specs beschreiben nun das neue Verhalten
- Die nächste Änderung baut auf den aktualisierten Specs auf
Glossar
| Begriff | Definition |
|---|---|
| Artifact | Ein Dokument innerhalb einer Änderung (Proposal, Design, Tasks oder Delta-Specs) |
| Archive | Der Prozess zum Abschließen einer Änderung und Mergen ihrer Deltas in die Haupt-Specs |
| Change | Ein vorgeschlagener Modifikationsvorschlag für das System, verpackt als Ordner mit Artefakten |
| Delta spec | Eine Spec, die Änderungen (ADDED/MODIFIED/REMOVED) im Verhältnis zu den aktuellen Specs beschreibt |
| Domain | Eine logische Gruppierung für Specs (z. B. auth/, payments/) |
| Requirement | Ein spezifisches Verhalten, das das System haben muss |
| Scenario | Ein konkretes Beispiel für eine Anforderung, typischerweise im Given/When/Then-Format |
| Schema | Eine Definition von Artefakttypen und deren Abhängigkeiten |
| Spec | Eine Spezifikation, die das Systemverhalten beschreibt und Anforderungen sowie Szenarien enthält |
| Source of truth | Das Verzeichnis openspec/specs/, das das aktuell vereinbarte Verhalten enthält |
Nächste Schritte
- Getting Started - Praktische erste Schritte
- Workflows - Häufige Muster und wann welche zu verwenden sind
- Commands - Vollständige Referenz der Befehle
- Customization - Eigene Schemas erstellen und Ihr Projekt konfigurieren