Snelstart

Je eerste wijziging, van idee naar archief, in een nieuw of bestaand project.

Voordat je begint, heb je de CLI op je machine nodig (Installation) en OpenSpec geïnitialiseerd in je project (Set up your project).

Start vanaf een lege project

Je kunt starten zonder een gekozen stack of een complete architectuur. Initialiseer OpenSpec in de map van je project, en vraag je agent om de opties met je te verkennen. In je AI-chat:

Help me verkennen een taak tracker van nul. Ik heb geen stack gekozen. Vergelijk de opties en help me de eerste gedraging te bouwen.

Bepaal wat de eerste wijziging nodig heeft en laat laterkeuzes in de architectuur open. Vraag je agent om die ene wijziging te voorstellen, en volg vervolgens de stappen hieronder. Je kunt de architectuur later herzien naarmate het project groeit.

Het loopoverzicht

Elke wijziging gaat door dezelfde vijf stappen: je denkt de gedachte door met je agent, het maakt een plan, je corrigeert het plan voordat er code bestaat, de agent bouwt ervan, en archivering update je specs met wat is verzonden.

flowchart LR
    explore["1 · Verken<br/>denk er samen door"] --> propose["2 · Voer voorstel<br/>agent maakt het plan"]
    propose --> review["3 · Beoordeel<br/>jij corrigeert het plan"]
    review --> apply["4 · Toepassen<br/>agent bouwt, taak voor taak"]
    apply --> archive["5 · Archieven<br/>specs absorberen de wijziging"]
    archive -. "volgende wijziging" .-> explore

Elke prompt hieronder gaat in je AI-chat, dezelfde plaats waar je code vraagt. De voorbeelden gebruiken simpele taal, zodat ze overal werken. Je kunt ook direct een vaardigheid aanroepen; de syntaxis varieert per tool (supported tools).

Stap 1: Verken

Denk de gedachte door met je agent voordat je een plan vraagt. In je AI-chat:

Help me verkennen hoe rate limiting eruit moet zien in deze app.

Verken is een denkmode. De agent onderzoekt je codebase, stelt de belangrijke vragen, schetst opties en betwist aannames. Hij/het schrijft nooit code. Hij/het schrijft alleen iets anders als je vraagt om te vastleggen wat je besliste, of ja zegt wanneer hij/het een aanbod doet. Het resultaat is een helderder idee.

Blijf hier zo lang als het nodig is. Wanneer de vorm goed voelt, overdraag het:

Voer het voorstel uit dat we net hebben besproken.

Deze regel start de propose voor jou, met alles wat je hebt vastgelegd. Sla de eerste prompt in stap 2 over.

Stap 2: Voer voorstel

Voer voorstel maakt van de gedachte een reviewbaar plan. Komend van verken, loopt het al. Bij een koude start, wanneer de wijziging duidelijk in je hoofd is, vraag direct. In je AI-chat:

Voer een wijziging voor het toevoegen van rate limiting.

De agent vraagt wat hij/ze nodig heeft, en maakt een map voor de wijziging:

openspec/changes/add-rate-limiting/
├── proposal.md    why, and what changes
├── specs/         what "done" means, as testable requirements
├── design.md      technical decisions (only when the change needs one)
└── tasks.md       the implementation checklist

Geen code nog. Propose stopt bij het plan.

Stap 3: Beoordeel en corrigeer het plan

Corrigeer het plan terwijl het nog maar woorden is en er nog niets is gebouwd. Lees in deze volgorde:

• proposal.md: is dit het juiste probleem, met de juiste omvang?
• specs/: de meest waardevolle lees. Zou je deze eisen als done accepteren?
• tasks.md: dekken de taken de eisen en niets meer?

Om iets te corrigeren, kun je op een van de volgende manieren werken:

• Bewerk het bestand zelf. De artefacten zijn gewoon markdown, en de bestanden zijn het plan.
• Zeg tegen je agent wat er mis is ("de spec mist het geval voor niet-geregistreerde gebruikers"). Het herziet de artefacten.

Stap 4: Toepassen

Toepassen maakt van het plan code. Start een frisse chat-sessie, omdat implementatie beter gaat op een schone contextwindow. In je AI-chat:

Toepas de toevoeging van rate limiting.

De agent leest de map voor de wijziging, en gaat door tasks.md, en vinkt elke taak af zodra deze is voltooid.

• Verstoord, of buiten context? Open een nieuwe sessie en vraag het opnieuw toe te passen. Het hervat bij de eerste taak die nog niet is aangevinkt.
• Plan bleek fout? Corrigeer de artefacten (op welke manier ook uit stap 3), en ga verder met toepassen.
• Vooruitgang staat in de tasks.md vakjes. Er is geen verborgen staat.

Stap 5: Archieven

Archivering doet twee dingen: het update je hoofdspecs met de eisen van de wijziging, en verplaatst de map voor de wijziging naar de archiefmap (in /openspec/changes/archive/*).

Wanneer elke vakje in tasks.md is aangevinkt, in je AI-chat:

Archive de add-rate-limiting change.

Stap door wat archivering doet:

## De voltooide wijziging
> Implementatie is afgerond. Het delta spec (wat deze wijziging toevoegt) zit nog steeds in de map voor de wijziging; de specs/ weten nog niet van rate limiting.
  openspec/
  ├── specs/                                   (nog geen spec voor rate-limiting)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         elke vakje aangevinkt
          └── specs/
              └── rate-limiting/
                  └── spec.md                  de delta: TOEGEVOEDE vereisten

## Vereisten landen in specs/
> Elk vereiste in de delta komt in de hoofd spec: toegevoegde ones voegen toe, gewijzigde vervangen hun oude versie. Een nieuwe mogelijkheid krijgt een nieuw spec-bestand.
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          verkrijgt "Vereiste: Rate limiting"
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  de delta, bron van de merge

## De map verplaatst naar archive/
> De hele map voor de wijziging, inclusief de delta, verplaatst zich naar de archive onder een datumprefix. Niets wordt verwijderd.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## Specs beschrijven het systeem zoals het is gebouwd
> changes/ is klaar voor de volgende wijziging. specs/ is de bron van de waarheid voor wat het systeem doet; archive/ is de geschiedenis van hoe het er kwam.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          het spec zoals het is gebouwd
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Git is een aparte kwestie. Commit de map voor de wijziging met de code, en niets anders over jouw workflowwijzigingen.

Behalte of schraap archiefgewijzigde wijzigingen

openspec/changes/archive/ bewaart de proposal, design, tasks, en delta voor elke voltooide wijziging. In de archiefstroom hierboven is de delta al openspec/specs/ bijgewerkt.

• Behalte de hele map voor de wijziging wanneer je een zelfstandig record wilt in de huidige checkout.
• Verwijder de specs/ map van een archiefgewijzigde wijziging wanneer Git jouw specgeschiedenis is. Commit eerst de archive, vervolgens verwijder openspec/changes/archive/<change>/specs/. De proposal, design en tasks blijven in de checkout. openspec validate --archived werkt nog steeds, omdat het de taakvoltooiing controleert, niet de toegepaste deltas.
• Verwijder de hele map voor de wijziging alleen wanneer je de proposal, design of taakgeschiedenis er niet meer in de checkout nodig hebt. De huidige specs wijzigen niet, maar openspec validate --archived en zoekopdrachten in de checkout omvatten die wijziging niet meer.

WARNING

Houd de archive‑commit in je repository‑geschiedenis als je wilt dat Git de verwijderde bestanden behoudt. Het samenvoegen van de archive‑ en opschoon‑commits verwijdert dat tussentijdse momentopname.

OpenSpec schrapt archiefgewijzigde wijzigingen niet automatisch en biedt geen retentie-instelling.

Ga verder

• Delta specs: hoe je gedragsveranderingen in een delta spec schrijft.
• Profiles: optionele workflows buiten de kernset (verifieer voor archivering, incrementale planning).

Geavanceerde gidsen

Niet geschreven nog; gidsen die we willen toevoegen:

• Prototypen eerst: spike de code voordat je een spec hebt, en vul daarna de proposal aan de hand van wat de prototype je leerde.
• Bouwen iteratief: een reeks kleine wijzigingen in plaats van één grote proposal.
• Herzien een uitgevoerde wijziging: het plan moet opnieuw worden gemaakt na toepassen, maar de wijziging is nog niet gefuseerd of gearchiveerd.