Beispiele & Rezepte

Echte Änderungen, von Anfang bis Ende. Jedes Rezept zeigt die Befehle, die Sie eingeben würden, und die Rückmeldungen, die Sie erhalten, sodass Sie Ihre Situation einem Muster zuordnen und es kopieren können. Diese Rezepte verwenden die Standard-core-Befehle (propose, explore, apply, update, sync, archive); wo der erweiterte Befehlssatz hilfreich ist, wird dies vermerkt.

Eine Erinnerung vor dem Start: Slash-Befehle wie /opsx:propose gehören in den Chat Ihres KI-Assistenten, und openspec-Befehle gehören in Ihr Terminal. Falls das neu für Sie ist, lesen Sie zuerst How Commands Work. In den Transkripten unten sind You: und AI: der Chat, und Zeilen, die mit $ beginnen, sind das Terminal.

Noch unsicher, was Sie bauen? Die meisten dieser Rezepte werden schärfer, wenn Sie mit /opsx:explore beginnen, um es vorher durchzudenken. Rezept 3 zeigt es in Aktion, und der Explore First-Guide macht den vollständigen Fall.

Rezept 1: Eine kleine Funktion, der schnelle Weg

Wann Sie es verwenden: Sie wissen, was Sie wollen, und es handelt sich um eine abgegrenzte Arbeitsaufgabe. Dies ist das häufigste Rezept.

Die gesamte Abwicklung besteht aus drei Befehlen. Vorschlagen, bauen, archivieren.

You: /opsx:propose add-logout-button

AI:  Created openspec/changes/add-logout-button/
     ✓ proposal.md — why and what
     ✓ specs/      — the new requirement and its scenarios
     ✓ design.md   — technical approach
     ✓ tasks.md    — implementation checklist
     Ready for implementation. Run /opsx:apply.

Lesen Sie nun den Plan. Öffnen Sie den Vorschlag und die Delta-Spec. Genau für diesen Moment wurde OpenSpec entwickelt: eine falsche Annahme zu erkennen, solange sie noch ein Absatz ist, nicht 400 Zeilen Code. Bearbeiten Sie jedes Artefakt direkt, falls etwas nicht stimmt, und fahren Sie dann fort.

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Add logout button to header
     ✓ 1.2 Clear session on click
     ✓ 1.3 Add confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  Archiving add-logout-button...
     ✓ Merged specs into openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
     Done. Ready for the next change.

Das war's. Das Logout-Verhalten ist nun Teil Ihrer Specs, und die Änderung ist mit ihrem vollständigen Kontext abgelegt.

Rezept 2: Ein Bugfix

Wann Sie es verwenden: Etwas ist kaputt, und Sie möchten, dass der Fix als bewusste Verhaltensänderung dokumentiert wird, nicht als mysteriöser Commit.

Bugfixes funktionieren genauso wie Funktionen. Der Unterschied liegt darin, wie Sie den Vorschlag formulieren: Beschreiben Sie das korrekte Verhalten, nicht nur „den Bug beheben".

You: /opsx:propose fix-login-redirect-loop

AI:  Created openspec/changes/fix-login-redirect-loop/
     The proposal captures the current broken behavior and the
     intended behavior. The delta spec MODIFIES the redirect
     requirement so it's now precise and testable.
     Ready for implementation.

Da der Fix als MODIFIED-Anforderung mit einem neuen Szenario eintrifft, sieht die nächste Person (oder die nächste KI-Sitzung) nicht nur, dass Sie es behoben haben, sondern auch, was „korrekt" bedeutet. Dann /opsx:apply und /opsx:archive wie üblich.

Tipp: Für einen Fix ist ein gutes Szenario der Regressionstest in Prosa. „GIVEN ein abgemeldeter Benutzer, WHEN dieser gültige Anmeldedaten einreicht, THEN landet er auf dem Dashboard und wird nicht erneut umgeleitet." Schreiben Sie das, und die Implementierung hat ein klares Ziel.

Rezept 3: Erforschen, bevor Sie sich verpflichten

Wann Sie es verwenden: Sie haben ein Problem, aber noch keinen Plan. Sie sind unsicher, was zu bauen ist, oder welcher Ansatz der richtige ist.

Beginnen Sie mit /opsx:explore. Es ist ein Denkpartner ohne Struktur und ohne erstellte Artefakte. Es liest Ihren Code und hilft Ihnen bei der Entscheidung.

You: /opsx:explore

AI:  What would you like to explore?

You: Page loads feel slow but I don't know where the time goes.

AI:  Let me look... I found three likely culprits:
     1. Large unoptimized images on the product list
     2. Synchronous data fetching that blocks render
     3. Re-renders triggered by context changes
     Which should we tackle first?

You: The data fetching one.

You: /opsx:propose optimize-product-list-fetching

AI:  Created the change, with a proposal informed by what we just
     found. Ready for implementation.

Erkundung klärt Ihr Denken bevor Sie eine Änderung dafür aufwenden. Wenn sich die Erkenntnis kristallisiert, schlagen Sie vor, und die KI trägt den Kontext weiter.

Rezept 4: Zwei Änderungen gleichzeitig jonglieren

Wann Sie es verwenden: Sie arbeiten an einer Funktion und ein dringender Fix springt in die Warteschlange.

Änderungen sind unabhängige Ordner, daher kollidieren parallele Arbeiten nicht. Beginnen Sie mit dem Fix, liefern Sie ihn aus und kehren Sie dann genau dort zur Funktion zurück, wo Sie aufgehört haben.

You: I'm partway through add-dark-mode, but I need to fix a login bug now.

You: /opsx:propose fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/. Ready for implementation.

You: /opsx:apply

AI:  Implemented the fix. All tasks complete.

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect.

You: Back to dark mode.

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode. Picking up at task 2.3: Update Header...

Die Änderung in /opsx:apply add-dark-mode zu benennen ist der Weg, wie Sie die KI auf eine bestimmte Änderung hinweisen, wenn mehr als eine aktiv ist. Da Aufgaben in tasks.md den Abschluss verfolgen, weiß die KI genau, wo Sie aufgehört haben.

Wenn mehrere Änderungen gleichzeitig abgeschlossen sind, legt der erweiterte /opsx:bulk-archive sie zusammen ab und löst Spec-Konflikte, indem er prüft, was tatsächlich implementiert wurde. Siehe Workflows.

Rezept 5: Ein Refactoring ohne Verhaltensänderung

Wann Sie es verwenden: Sie strukturieren Code um, und das extern sichtbare Verhalten sollte identisch bleiben.

Dieser Fall ist interessant, denn ein reines Refactoring hat nichts zu Ihren Specs hinzuzufügen. Der Verhaltensvertrag ändert sich nicht; nur die Implementierung. Die Arbeit liegt also im Design und in den Aufgaben, und die Spec-Delta ist leer oder fehlt.

You: /opsx:propose refactor-payment-module

AI:  Created the change. The proposal states the goal (split the
     payment module, no behavior change) and the design captures
     the new structure. No spec changes, since behavior is identical.
     Ready for implementation.

Erklären Sie die leere Delta explizit, indem Sie skip_specs: true in der .openspec.yaml der Änderung setzen:

schema: spec-driven
skip_specs: true

Ohne den Marker lehnt openspec validate eine Änderung mit null Deltas ab (so wird eine vergessene Specs-Phase immer noch erkannt); mit dem Marker besteht die Validierung und openspec status zeigt die Specs-Stufe als explizit übersprungen an, nicht als ausstehend. Falls sich herausstellt, dass das Refactoring doch das Verhalten ändert, entfernen Sie skip_specs aus .openspec.yaml und schreiben Sie die Delta-Specs — validate behandelt den Marker plus Spec-Dateien als Konflikt, sodass der veraltete Marker nicht stillschweigend verbleiben kann.

Das Archivieren einer markierten Änderung erfordert keine zusätzlichen Flags (es gibt keine Deltas zum Zusammenführen). Unabhängig davon teilt der --skip-specs-Flag dem Terminalbefehl mit, den Spec-Schritt explizit zu überspringen:

$ openspec archive refactor-payment-module --skip-specs

Dasselbe Flag ist auch für Tooling, CI und reine Dokumentationsänderungen nützlich. Das Prinzip: Specs beschreiben Verhalten, also sollte sich die Spec nicht ändern, wenn sich das Verhalten nicht geändert hat. Siehe Concepts.

Rezept 6: Schritt-für-Schritt-Kontrolle (erweiterte Befehle)

Wann Sie es verwenden: Eine komplexe oder riskante Änderung, bei der Sie jedes Artefakt überprüfen möchten, bevor Sie weitermachen.

Der Kernbefehl /opsx:propose entwirft alles auf einmal. Wenn Sie lieber Schritt für Schritt vorgehen möchten, aktivieren Sie die erweiterten Befehle:

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

Nun können Sie schrittweise Gerüst erstellen und bauen:

You: /opsx:new add-2fa

AI:  Created openspec/changes/add-2fa/. Ready to create: proposal.

You: /opsx:continue

AI:  Created proposal.md. Now available: specs, design.

You: /opsx:continue

AI:  Created specs/auth/spec.md. Now available: design.

Überprüfen Sie jedes Artefakt, sobald es eintrifft, bearbeiten Sie frei und fahren Sie fort, wenn Sie zufrieden sind. Wenn Sie den Rest auf einmal entwerfen möchten, fast-forwardt /opsx:ff durch die verbleibenden Planungsartefakte. Vor dem Archivieren prüft /opsx:verify, ob die Implementierung tatsächlich mit den Specs übereinstimmt. Siehe Workflows.

Rezept 7: Den gesamten Ablauf praktisch lernen

Wann Sie es verwenden: Sie haben OpenSpec installiert und möchten den Workflow an Ihrem eigenen Code erleben, nicht an einem Spielzeugbeispiel.

Aktivieren Sie die erweiterten Befehle (siehe Rezept 6), dann:

You: /opsx:onboard

AI:  Welcome to OpenSpec! I'll walk you through a complete change
     using your actual codebase. Let me scan for a small, safe
     improvement we can make together...

/opsx:onboard findet eine echte (kleine) Verbesserung, erstellt eine Änderung dafür, implementiert sie und archiviert sie, wobei jeder Schritt kommentiert wird. Es dauert 15 bis 30 Minuten und hinterlässt eine echte Änderung, die Sie behalten oder verwerfen können. Es ist der sanfteste Weg zu lernen. Siehe Commands.

Ihre Arbeit vom Terminal aus überprüfen

Jederzeit können Sie vom Terminal aus den Status überprüfen:

$ openspec list                      # active changes
$ openspec show add-dark-mode        # one change in detail
$ openspec validate add-dark-mode    # check structure
$ openspec view                      # interactive dashboard

Dies sind Lese- und Inspektionswerkzeuge. Das Vorschlagen und Bauen erfolgt weiterhin über Slash-Befehle im Chat. Vollständige Details in der CLI-Referenz.

Weiterführende Schritte

• Explore First: der empfohlene Einstieg, wenn Sie unsicher sind
• Workflows: die oben genannten Muster mit Entscheidungshilfe, wann Sie welches verwenden
• Commands: jeder Slash-Befehl im Detail
• Getting Started: der kanonische Walkthrough für die erste Änderung
• Concepts: warum die Bausteine so zusammenpassen, wie sie es tun