Voorbeelden & recepten

Echte wijzigingen, van begin tot eind. Elk recept toont de commando's die je typt en wat je terugziet, zodat je jouw situatie kunt matchen met een patroon en het kunt kopiëren. Deze gebruiken de standaard core-commando's (propose, explore, apply, update, sync, archive); waar de uitgebreide set helpt, staat dat vermeld.

Een herinnering voordat je begint: slash-commando's zoals /opsx:propose gaan in de chat van je AI-assistent, en openspec-commando's gaan in je terminal. Als dit nieuw is, lees dan eerst Hoe commando's werken. In de transcripten hieronder zijn You: en AI: de chat, en regels die beginnen met $ zijn de terminal.

Weet je nog niet zeker wat je bouwt? De meeste van deze recepten zijn scherper als je begint met /opsx:explore om het eerst uit te denken. Recept 3 toont dit in actie, en de Eerst verkennen-gids maakt het volledige geval.

Recept 1: Een klein feature, de snelle route

Wanneer te gebruiken: je weet wat je wilt, en het is een beperkt stuk werk. Dit is het meest voorkomende recept.

Het hele ding is drie commando's. Propose, build, archive.

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.

Lees nu het plan. Open de proposal en de delta spec. Dit is het moment waarvoor OpenSpec is ontworpen: een verkeerde aanname vangen terwijl het nog één paragraaf is, niet 400 regels code. Bewerk elk artefact direct als er iets niet klopt, en ga dan verder.

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.

Dat is het. Het logout-gedrag is nu onderdeel van je specs, en de wijziging is weggeplaatst met de volledige context.

Recept 2: Een bugfix

Wanneer te gebruiken: er is iets kapot en je wilt de fix vastleggen als een bewuste wijziging van gedrag, niet als een mysterieuze commit.

Bugfixes werken precies zoals features. Het verschil zit in hoe je de proposal frame: beschrijf het juiste gedrag, niet alleen "fix the bug."

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.

Omdat de fix landt als een MODIFIED-requirement met een nieuw scenario, ziet de volgende persoon (of de volgende AI-sessie) niet alleen dat je het hebt gefixt, maar ook wat "correct" betekent. Dan /opsx:apply en /opsx:archive zoals gebruikelijk.

Tip: voor een fix is een goed scenario de regression test in proza. "GIVEN een uitgelogde gebruiker, WHEN deze geldige inloggegevens invoert, THEN komt deze op het dashboard en wordt niet opnieuw doorgestuurd." Schrijf dat, en de implementatie heeft een duidelijk doel.

Recept 3: Verkennen voordat je commit-je

Wanneer te gebruiken: je hebt een probleem maar nog geen plan. Je bent niet zeker wat je wilt bouwen, of welke aanpak juist is.

Begin met /opsx:explore. Het is een denkpartner zonder structuur en zonder aangemaakte artefacten. Het leest je codebase en helpt je beslissen.

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.

Verkenning verduidelijkt je denken voordat je er een wijziging aan besteedt. Wanneer de inzicht kristalliseert, propose je, en de AI draagt de context door.

Recept 4: Twee wijzigingen tegelijk juggling

Wanneer te gebruiken: je zit midden in een feature en een urgente fix springt de wachtrij over.

Wijzigingen zijn onafhankelijke mappen, dus parallel werk veroorzaakt geen conflicten. Begin de fix, ship hem, en keer dan terug naar de feature waar je gebleven was.

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...

Het noemen van de wijziging in /opsx:apply add-dark-mode is hoe je de AI wijst naar een specifieke wijziging wanneer er meer dan één actief is. Omdat taken voltooiing bijhouden in tasks.md, weet de AI precies waar je gestopt was.

Wanneer meerdere wijzigingen tegelijk klaar zijn, plaatst de uitgebreide /opsx:bulk-archive ze samen weg en lost spec-conflicten op door te controleren wat daadwerkelijk geïmplementeerd is. Zie Workflows.

Recept 5: Een refactor zonder gedragswijziging

Wanneer te gebruiken: je herstructureert code, en extern zichtbaar gedrag moet identiek blijven.

Dit is het interessante geval, omdat een pure refactor niets toe te voegen heeft aan je specs. De gedragscontract verandert niet; alleen de implementatie. Dus het werk zit in de design en tasks, en de spec delta is leeg of afwezig.

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.

Verklaar de lege delta expliciet door skip_specs: true te zetten in de .openspec.yaml van de wijziging:

schema: spec-driven
skip_specs: true

Zonder de marker wijst openspec validate een wijziging met nul deltas af (dus een vergeten specs-fase wordt nog steeds gevangen); met de marker slaagt de validatie en toont openspec status de specs-stap als expliciet overgeslagen in plaats van pending. Als de refactor toch gedrag verandert, verwijder skip_specs uit .openspec.yaml en schrijf de delta specs — validate behandelt de marker plus spec-bestanden als een conflict, dus de verouderde marker kan niet stil blijven hangen.

Het archiveren van een gemarkeerde wijziging vereist geen extra flags (er zijn geen deltas om te mergen). Onafhankelijk daarvan vertelt de --skip-specs-flag het terminalcommando om de spec-stap expliciet over te slaan:

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

Dezelfde flag is handig voor tooling, CI en alleen-docs-wijzigingen. Het principe: specs beschrijven gedrag, dus als gedrag niet veranderde, moet de spec dat ook niet doen. Zie Concepts.

Recept 6: Stap-voor-stap controle (uitgebreide commando's)

Wanneer te gebruiken: een complexe of risicovolle wijziging waarbij je elk artefact wilt reviewen voordat je verder gaat.

De core /opsx:propose schetst alles tegelijk. Wanneer je liever stap voor stap gaat, zet de uitgebreide commando's aan:

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

Nu kun je incrementeel scaffolden en bouwen:

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.

Review elk artefact zodra het landt, bewerk vrij, en ga verder wanneer je tevreden bent. Wanneer je de rest in één keer wilt laten opstellen, /opsx:ff fast-forwardt door de resterende planning-artefacten. Voor het archiveren controleert /opsx:verify dat de implementatie daadwerkelijk overeenkomt met de specs. Zie Workflows.

Recept 7: De hele lus hands-on leren

Wanneer te gebruiken: je hebt OpenSpec geïnstalleerd en wilt de workflow ervaren op je eigen code, niet een speelgoedvoorbeeld.

Zet de uitgebreide commando's aan (zie Recept 6), en dan:

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 vindt een echte (kleine) verbetering, maakt een wijziging voor het, implementeert het en archiveert het, terwijl het elke stap vertelt. Het duurt 15 tot 30 minuten en laat je achter met een echte wijziging die je kunt houden of verwerpen. Het is de zachtste manier om te leren. Zie Commands.

Je werk controleren vanuit de terminal

Op elk moment, vanuit je terminal, kun je de staat van zaken inspecteren:

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

Dit zijn read-and-inspect-tools. Het proponeren en bouwen gebeurt nog steeds via slash-commando's in de chat. Volledige details in de CLI-reference.

Waar je naartoe kunt

• Eerst verkennen: de aanbevolen manier om te beginnen wanneer je onzeker bent
• Workflows: de patronen hierboven, met beslissingsrichtlijnen over wanneer elk te gebruiken
• Commands: elk slash-commando in detail
• Getting Started: de canonieke eerste-wijziging-walkthrough
• Concepts: waarom de onderdelen zo bij elkaar passen