Workflows

Dieser Leitfaden behandelt gängige Workflow-Muster für OpenSpec und erläutert, wann welches Muster zum Einsatz kommen sollte. Für die grundlegende Einrichtung siehe Erste Schritte. Eine Referenz der Befehle finden Sie unter Befehle.

Philosophie: Aktionen statt Phasen

Traditionelle Workflows zwingen Sie durch festgelegte Phasen: Planung, dann Implementierung, dann Fertig. Die reale Arbeit passt jedoch nicht immer sauber in solche Schubladen.

OPSX geht einen anderen Weg:

Traditionell (phasengebunden):

  PLANUNG ────────► IMPLEMENTIERUNG ────────► FERTIG
      │                    │
      │   "Zurückgehen nicht möglich"  │
      └────────────────────┘

OPSX (flüssige Aktionen):

  proposal ──► specs ──► design ──► tasks ──► implement

Grundprinzipien:

• Aktionen, keine Phasen – Befehle sind Dinge, die Sie tun können, sondern Stadien, in denen Sie feststecken
• Abhängigkeiten als Ermöglicher – Sie zeigen auf, was möglich ist, nicht darauf, was als Nächstes erforderlich ist

Anpassung: OPSX-Workflows werden von Schemas gesteuert, die die Sequenz der Artefakte definieren. Einzelheiten zur Erstellung benutzerdefinierter Schemas finden Sie unter Anpassung.

Workflow auf einen Blick

Der Standard-Workflow bleibt flexibel: Exploration und Verifikation sind optional, und Sie können Planungsdokumente jederzeit aktualisieren, wenn die Implementierung neue Erkenntnisse liefert.

flowchart TD
    Idea["Idee oder Problem"] --> Explore["/opsx:explore<br/>(optional)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planungsdokumente<br/>bereit?"}
    Review -->|"Verfeinern"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implementieren"| Apply["/opsx:apply"]
    Apply -->|"Plan geändert"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(optional, eigene Auswahl)"]
    Apply --> Sync["/opsx:sync<br/>(optional vor Archivierung)"]
    Verify --> Verified{"Bereit zur Archivierung?"}
    Verified -->|"Implementierung beheben"| Apply
    Verified -->|"Plan überarbeiten"| Update
    Verified -->|"Bereit"| Sync
    Verified -->|"Bereit"| Archive
    Sync --> Archive

Der KI-Assistent steuert den Workflow, während die CLI deterministisches Gerüst, Status und Anweisungen für Artefakte bereitstellt:

sequenceDiagram
    actor Human
    participant Assistant as KI-Assistent
    participant CLI as OpenSpec CLI
    participant Files as Planungs- und Implementierungsdateien

    Human->>Assistant: /opsx:propose "change"
    Assistant->>CLI: openspec new change
    CLI->>Files: Gerüst für Änderungs-Metadaten erstellen
    Assistant->>CLI: Status und Artefakt-Anweisungen anfordern
    CLI-->>Assistant: Bau-Reihenfolge, Pfade und Vorlagen
    Assistant->>Files: Schema-definierte Planungsdokumente schreiben
    Assistant-->>Human: Artefakte zur Überprüfung präsentieren

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: Apply-Anweisungen anfordern
    CLI-->>Assistant: Kontextdateien und Aufgabenstatus
    Assistant->>Files: Aufgaben implementieren und Checkboxen aktualisieren
    Assistant-->>Human: Implementierungsstatus melden

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: Archivierungs-Eingaben und Artefaktstatus anfordern
    CLI-->>Assistant: Planungspfade und Artefakt-Abschluss
    Assistant->>Files: Aufgabenstatus lesen und Delta-Specs vergleichen
    opt Delta-Specs vorhanden
        Assistant-->>Human: Synchronisation vor der Archivierung anbieten
        alt Synchronisation akzeptiert
            Human->>Assistant: Synchronisation bestätigen
            Assistant->>Files: Delta-Specs in Haupt-Specs überführen
        else Synchronisation übersprungen
            Human->>Assistant: Ohne Synchronisation archivieren
        end
    end
    Assistant->>Files: Änderung in das Archiv verschieben
    Assistant-->>Human: Archivort und Synchronisationsergebnis melden

    Note over Human,CLI: CLI-Alternative: openspec archive change-name --yes überspringt Bestätigungsdialoge. Es werden weiterhin Validierungen durchgeführt, dann werden ggf. Delta-Specs angewendet und archiviert

Zwei Modi

Standard-Schnellpfad (core-Profil)

Neue Installationen verwenden standardmäßig core, das Folgendes bereitstellt:

• /opsx:explore
• /opsx:propose
• /opsx:apply
• /opsx:update
• /opsx:sync
• /opsx:archive

Typischer Ablauf:

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

Beginnen Sie mit der Exploration (ein gewohnheitswertenswerter Schritt)

/opsx:explore ist Teil des Standardprofils, kein erweitertes Add-on. Es ist der Schritt, den Sie unternehmen sollten, wann immer Sie ein Problem haben, aber noch keinen Plan – was bei einem KI-Assistenten die meiste Zeit der Fall ist.

Sie: /opsx:explore

KI:  Was möchten Sie erkunden?

Sie: Unsere Suchergebnisse wirken veraltet. Ich bin mir nicht sicher,
     ob es am Caching, dem Indexieren oder der Abfrage selbst liegt.

KI:  Ich schaue mir das an... [liest den Suchdienst und die Cache-Schicht]
     Es liegt am Index: Er wird nur nächtlich neu aufgebaut, daher
     erscheinen Änderungen erst am nächsten Tag. Zwei Optionen:
     bei jedem Schreibvorgang neu aufbauen (einfach, mehr Last) oder
     eine Cache-Invalidation mit kurzem TTL (mehr Komponenten,
     weniger Last). Da Ihre Schreiblast gering ist, ist der
     Rebuild-on-Write der sauberere Ansatz. Möchten wir das
     umsetzen?

Sie: Ja.

Sie: /opsx:propose rebuild-search-index-on-write

Explore erstellt keine Artefakte und schreibt keinen Code. Es ist ein freies, risikofreies Gespräch, das eine vage Sorge in eine präzise Änderung verwandelt, sodass der folgende Vorschlag treffsicher ist. Wissen Sie bereits genau, was Sie wollen? Überspringen Sie es und gehen Sie direkt zu /opsx:propose. Vollständiger Leitfaden: Explore First.

Erweiterter/Vollständiger Workflow (eigene Auswahl)

Wenn Sie explizite Gerüst- und Bau-Befehle wünschen (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), aktivieren Sie diese mit:

openspec config profile
openspec update

Workflow-Muster (erweiterter Modus)

Schnelle Funktion

Wenn Sie wissen, was Sie bauen möchten, und nur ausführen müssen:

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Beispiel-Dialog:

Sie: /opsx:new add-logout-button

KI:  Erstellte openspec/changes/add-logout-button/
     Bereit zur Erstellung: proposal

Sie: /opsx:ff

KI:  Erstelle alle Planungsdokumente...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Bereit für die Implementierung!

Sie: /opsx:apply

KI:  Arbeite an den Aufgaben...
     ✓ Abmelde-Button im Header hinzugefügt
     ✓ Sitzungsbereinigung implementiert
     ✓ Bestätigungsdialog hinzugefügt
     Alle Aufgaben abgeschlossen!

Sie: /opsx:archive

KI:  ✓ Specs zusammengeführt
     ✓ Änderung archiviert

Am besten geeignet für: Kleine bis mittlere Funktionen, Fehlerbehebungen, unkomplizierte Änderungen.

Explorativ

Wenn Anforderungen unklar sind oder Sie zunächst untersuchen müssen:

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

Beispiel-Dialog:

Sie: /opsx:explore

KI:  Was möchten Sie erkunden?

Sie: Ich möchte die Seitenladeleistung verbessern, aber ich bin mir
     nicht sicher, wo die Engpässe liegen.

KI:  Ich helfe bei der Untersuchung...
     [Analysiert Bündelgrößen, identifiziert langsame Abfragen,
     prüft Komponenten-Render-Muster]

     Ich habe drei Haupt-Engpässe gefunden:
     1. Große, nicht optimierte Bilder
     2. Synchrones Datenabrufen in ProductList
     3. Re-Rendering durch Kontextänderungen

     Welchen möchten Sie zuerst angehen?

Sie: Lass uns das Datenabruf-Problem angehen.

Sie: /opsx:new optimize-product-list-fetching

KI:  Änderung erstellt. Bereit zur Erstellung: proposal

Sie: /opsx:continue

KI:  Erstelle Vorschlag basierend auf unserer Exploration...
     [Schreibt Vorschlag unter Einbeziehung der Untersuchungsergebnisse]

     Bereit zur Erstellung: specs, design
     Was möchten Sie als Nächstes?

Sie: /opsx:continue

KI:  Erstelle Specs...

Am besten geeignet für: Leistungsoptimierung, Debugging, Architekturentscheidungen, unklare Anforderungen.

Parallele Änderungen

Arbeiten Sie gleichzeitig an mehreren Änderungen:

Änderung A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in Bearbeitung)
                                         │
                                    Kontextwechsel
                                         │
Änderung B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

Beispiel-Dialog:

Sie: Ich arbeite an add-dark-mode, wurde aber zu einer Fehlerbehebung abgezogen

Sie: /opsx:new fix-login-redirect

KI:  Erstellte openspec/changes/fix-login-redirect/

Sie: /opsx:ff

KI:  ✓ Planungsdokumente erstellt

Sie: /opsx:apply

KI:  Arbeite an fix-login-redirect...
     [Implementiert die Korrektur]
     Alle Aufgaben abgeschlossen!

Sie: /opsx:archive

KI:  ✓ fix-login-redirect archiviert

Sie: Lass uns zurück zum Dark Mode kommen

Sie: /opsx:apply add-dark-mode

KI:  Setze add-dark-mode fort...
     Weiter bei Aufgabe 2.3: Header aktualisieren...

Am besten geeignet für: Parallele Arbeitsströme, dringende Unterbrechungen, Team-Kollaboration.

Wenn Sie mehrere abgeschlossene Änderungen haben, verwenden Sie /opsx:bulk-archive:

Sie: /opsx:bulk-archive

KI:  3 abgeschlossene Änderungen gefunden:
     - add-dark-mode (alle Aufgaben erledigt)
     - fix-login-redirect (alle Aufgaben erledigt)
     - update-footer (alle Aufgaben erledigt)

     Prüfe auf Spec-Konflikte...
     ⚠ add-dark-mode und update-footer betreffen beide specs/ui/

     Untersuche Codebasis zur Auflösung...
     Beide Änderungen sind implementiert. Werden in chronologischer Reihenfolge angewendet.

     Alle 3 Änderungen archivieren?

Sie: Ja

KI:  ✓ add-dark-mode archiviert
     ✓ fix-login-redirect archiviert
     ✓ update-footer archiviert
     Specs in Reihenfolge zusammengeführt: add-dark-mode → update-footer

Bulk-Archivierung erkennt, wenn mehrere Änderungen dieselben Specs betreffen, und löst Konflikte auf, indem sie prüft, was tatsächlich implementiert wurde.

Abschluss einer Änderung

Der empfohlene Abschluss-Ablauf:

/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              validiert          fordert zur
              Implementierung    Synchronisation auf
                                 falls nötig

Verify: Prüfen Sie Ihre Arbeit

/opsx:verify validiert die Implementierung anhand Ihrer Artefakte in drei Dimensionen:

Sie: /opsx:verify

KI:  Verifiziere add-auth...

     VOLLSTÄNDIGKEIT
     ✓ Alle 12 Aufgaben in tasks.md sind abgehakt
     ✓ Alle Anforderungen in Specs haben entsprechenden Code
     ⚠ Szenario "Session timeout after inactivity" nicht getestet

     KORREKTHEIT
     ✓ Implementierung entspricht der Spec-Intention
     ✓ Randfälle aus Szenarien werden behandelt
     ✓ Fehlerzustände entsprechen den Spec-Definitionen

     KONSISTENZ
     ✓ Designentscheidungen in der Code-Struktur widergespiegelt
     ✓ Namenskonventionen mit design.md konsistent
     ⚠ Design erwähnt "event-driven", Implementierung verwendet jedoch Polling

     ZUSAMMENFASSUNG
     ─────────────────────────────
     Kritische Probleme: 0
     Warnungen: 2
     Bereit zur Archivierung: Ja (mit Warnungen)

     Empfehlungen:
     1. Test für das Session-Timeout-Szenario hinzufügen
     2. Überlegen, auf event-driven umzustellen wie im Design vorgesehen, oder design.md aktualisieren

Was Verify prüft:

Dimension	Was validiert wird
Vollständigkeit	Alle Aufgaben erledigt, alle Anforderungen implementiert, Szenarien abgedeckt
Korrektheit	Implementierung entspricht der Spec-Intention, Randfälle behandelt
Konsistenz	Designentscheidungen im Code widergespiegelt, Muster konsistent

Verify blockiert die Archivierung nicht, aber es bringt Probleme ans Licht, die Sie möglicherweise zuerst beheben möchten.

Archive: Die Änderung finalisieren

/opsx:archive schließt die Änderung ab und verschiebt sie ins Archiv:

Sie: /opsx:archive

KI:  Archive add-auth...

     Artefaktstatus:
     ✓ proposal.md vorhanden
     ✓ specs/ vorhanden
     ✓ design.md vorhanden
     ✓ tasks.md vorhanden (12/12 Aufgaben abgeschlossen)

     Delta-Specs: Noch nicht mit Haupt-Specs synchronisiert
     → Möchten Sie jetzt synchronisieren?

Sie: Ja

KI:  ✓ Specs nach openspec/specs/auth/spec.md synchronisiert
     ✓ Nach openspec/changes/archive/2025-01-24-add-auth/ verschoben

     Änderung erfolgreich archiviert.

Archive fragt nach, wenn Specs nicht synchronisiert sind. Es blockiert nicht bei unvollständigen Aufgaben, warnt Sie aber.

Wann was verwenden

/opsx:ff vs. /opsx:continue

Situation	Verwendung
Klare Anforderungen, bereit zum Bauen	/opsx:ff
Exploration, möchten jeden Schritt überprüfen	/opsx:continue
Möchten Vorschlag vor Specs iterativ verfeinern	/opsx:continue
Zeitdruck, müssen schnell vorankommen	/opsx:ff
Komplexer Wechsel, möchten Kontrolle behalten	/opsx:continue

Faustregel: Wenn Sie den gesamten Umfang von vornherein beschreiben können, verwenden Sie /opsx:ff. Wenn Sie es im Laufe der Arbeit herausfinden, verwenden Sie /opsx:continue.

Wann aktualisieren vs. neu starten

Eine häufige Frage: Wann ist es in Ordnung, eine bestehende Änderung zu aktualisieren, und wann sollten Sie eine neue starten?

Bestehende Änderung aktualisieren, wenn:

• Gleiche Intention, verfeinerte Ausführung
• Umfang verengt sich (erst MVP, Rest später)
• Lerngetriebene Korrekturen (Codebasis ist nicht wie erwartet)
• Design-Anpassungen basierend auf Implementierungserkenntnissen

Neue Änderung starten, wenn:

• Intention grundlegend geändert wurde
• Umfang explodierte zu völlig anderer Arbeit
• Originale Änderung eigenständig als "erledigt" markiert werden kann
• Patches würden mehr verwirren als aufklären

                     ┌─────────────────────────────────────┐
                     │     Ist es dieselbe Arbeit?          │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Gleiche Intention?  >50 % Überlappung?  Kann Original
          Gleiches Problem?   Gleicher Umfang?    ohne diese Änderungen
                 │                  │          als "erledigt" gelten?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      JA                NEIN JA           NEIN NEIN           JA
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    AKTUALISIEREN    NEU  AKTUALISIEREN  NEU  AKTUALISIEREN   NEU

Beispiel: "Dark Mode hinzufügen"

• "Müssen auch benutzerdefinierte Themes unterstützen" → Neue Änderung (Umfang explodierte)
• "System-Einstellungserkennung ist schwieriger als erwartet" → Aktualisieren (gleiche Intention)
• "Lass uns erst den Umschalter veröffentlichen, Einstellungen später hinzufügen" → Aktualisieren dann archivieren, dann neue Änderung

Bewährte Vorgehensweisen

Änderungen fokussiert halten

Eine logische Arbeitseinheit pro Änderung. Wenn Sie "Feature X hinzufügen und gleichzeitig Y refaktorieren" tun, erwägen Sie zwei separate Änderungen.

Warum das wichtig ist:

• Einfacher zu überprüfen und zu verstehen
• Sauberere Archivhistorie
• Kann unabhängig ausgeliefert werden
• Einfachere Zurücksetzung bei Bedarf

/opsx:explore bei unklaren Anforderungen verwenden

Bevor Sie sich auf eine Änderung festlegen, erkunden Sie den Problemraum:

You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle rate limiting for our API?

AI:  Let me investigate your current setup and options...
     [Researches codebase, considers patterns]

     I see three approaches we could take:
     1. Middleware-based (simple, per-endpoint)
     2. Redis-backed (scalable, shared state)
     3. Token bucket per user (fair, complex)

     Your current stack suggests #1 or #2. What's your scale?

Die Erkundung klärt das Denken, bevor Sie Artefakte erstellen.

Vor dem Archivieren verifizieren

Verwenden Sie /opsx:verify, um zu prüfen, ob die Implementierung mit den Artefakten übereinstimmt:

You: /opsx:verify

AI:  Verifying add-dark-mode...

     ✓ All tasks in tasks.md are checked
     ✓ Requirements in specs have corresponding code
     ✓ Design decisions are reflected in implementation

     Ready to archive!

Fängt Diskrepanzen ab, bevor Sie die Änderung abschließen.

Änderungen klar benennen

Gute Namen machen openspec list nützlich:

Good:                          Avoid:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

Schnellreferenz der Befehle

Vollständige Befehlsdetails und Optionen finden Sie unter Commands.

Befehl	Zweck	Verwendung
/opsx:propose	Änderung + Planungsartefakte erstellen	Schneller Standardpfad (core-Profil)
/opsx:explore	Ideen mit der KI durchdenken	Hier beginnen, wenn unsicher: unklare Anforderungen, Untersuchung, Optionen vergleichen
/opsx:new	Änderungsgerüst starten	Erweiterter Modus, explizite Artefaktkontrolle
/opsx:continue	Nächstes Artefakt erstellen	Erweiterter Modus, schrittweise Artefakterstellung
/opsx:ff	Alle Planungsartefakte erstellen	Erweiterter Modus, klarer Umfang
/opsx:apply	Aufgaben implementieren	Bereit, Code zu schreiben
/opsx:verify	Implementierung validieren	Erweiterter Modus, vor dem Archivieren
/opsx:sync	Delta-Spezifikationen zusammenführen	Erweiterter Modus, optional
/opsx:archive	Änderung abschließen	Alle Arbeiten abgeschlossen
/opsx:bulk-archive	Mehrere Änderungen archivieren	Erweiterter Modus, parallele Arbeit

Nächste Schritte

• Writing Good Specs – Wie eine starke Anforderung und ein Szenario aussehen und wie man eine Änderung richtig dimensioniert
• Reviewing a Change – Die Zwei-Minuten-Prüfung eines entworfenen Plans vor dem Code
• OpenSpec on a Team – Wie Änderungen in Branches und Pull Requests passen
• Commands – Vollständige Befehlsreferenz mit Optionen
• Concepts – Tiefer Einblick in Spezifikationen, Artefakte und Schemata
• Customization – Benutzerdefinierte Workflows erstellen