Workflow voor specificatie-gestuurde ontwikkeling: van vereisten tot code

Spec-gedreven ontwikkeling werkt wanneer de specificatie een workflow is, en geen document dat je na de kickoff weglegt. Het doel is niet het produceren van een uitgebreid productvereisten document.

Het doel is om door een reeks van reviewbare artefacten te bewegen die elk de ambiguïteit verminderen voordat iemand – mens of AI-agent – productcode wijzigt.

Als je conceptueel niet weet wat SDD is, begin dan met Wat is Spec-gedreven Ontwikkeling? voor definities, vergelijkingen met TDD en BDD, en het argument om de specificatie als enige waarheid te behandelen. Dit artikel in de App Architecture documentatiecluster is de operationele gids. Het doorloopt de vijf fasen, toont wat elk artefact moet bevatten, legt uit waar AI-agents in passen en geeft herbruikbare sjablonen die je vandaag nog in je repository kunt kopiëren.

SDD is een Workflow, Geen Document

De meest voorkomende faalfactor bij spec-gedreven ontwikkeling is het behandelen van de specificatie als papierwerk. Een team schrijft een lang vereistendocument, slaat het op in een wiki en codeert vervolgens op basis van geheugen en chatthreads. De specificatie bestaat, maar hij stuurt niets aan. Dat is documentatietheater, en het is erger dan geen specificatie omdat het een vals vertrouwen creëert.

Een werkende SDD-workflow produceert een keten van artefacten, elk gereviewd voordat de volgende fase begint. Vereisten verminderen productambiguïteit. Ontwerp vermindert technische ambiguïteit. Taken verminderen uitvoeringsambiguïteit. Implementatie produceert code tegen een bekend doel. Validatie bewijst dat de keten standhield. Wanneer een fase een fout onthult, los je het artefact op en voer je vanaf dat punt opnieuw uit – niet nadat drieduizend regels drift in main zijn geland.

De workflow is tool-neutraal. Je kunt hem uitvoeren met markdownbestanden in Git, met GitHub Spec Kit, met Cursor-plannen, of met een gewone teksteditor en een gedisciplineerde reviewer. Wat telt, is de volgorde en de reviewpoorten, niet het merk van de tools.

Fase 1 – De Vereisten Specificeren

De specificatiefase beantwoordt welke probleem je oplost en hoe ‘klaar’ eruit ziet. Het vermijdt bewust hoe je het bouwt. Op het moment dat je vereistenspecificatie zegt “gebruik Redis-sorteerde sets”, ben je gestopt met specificeren en begonnen met ontwerpen in het verkeerde document. Houd implementatie buiten de vereisten. Zet het in het plan.

Probleemstelling en gebruikers

Begin met één alinea die het probleem in eenvoudige taal stelt. Noem de getroffen gebruikers en de situatie die het probleem pijnlijk maakt. Een goede probleemstelling stelt een reviewer die niet bij de planningsvergadering was in staat te beslissen of een voorgestelde oplossing het pijnpunt daadwerkelijk aanpakt.

Voorbeeld voor een API-rate-limiting-functie:

API-consumenten op het gratis abonnement kunnen onbeperkt requests sturen, wat leidt tot kostenpieken en ’noisy-neighbor’-impact op betalende tenants. Platformoperators hebben een afdwelbaar per-key limiet nodig zonder handmatige tussenkomst.

Doelen, niet-doelen en acceptatiecriteria

Doelen beschrijven de resultaten die je zal opleveren. Niet-doelen beschrijven verleidelijk aanpalend werk dat je expliciet niet zult doen. Samen begrenzen ze de creativiteit van de agent, wat essentieel is wanneer AI-tools anders “helpvol” de scope uitbreiden.

Acceptatiecriteria moeten precies genoeg zijn zodat elk minstens aan één test correspondeert. “Het eindpunt is veilig” is geen acceptatiecriterium. “Ongeauthenticeerde requests ontvangen HTTP 401” wel. Als je geen concreet criterium kunt schrijven, is de vereiste nog te vaag om te implementeren.

Open vragen

Lijst elke beslissing op die nog niet is vastgesteld. Onheldere vragen zijn geen teken van falen. Ze zijn de specificatiefase die haar werk doet. Los ze op voordat je het ontwerpplan schrijft, of je betaalt voor de ambiguïteit in implementatie-herwerk.

Een minimale vereistensjabloon:

## Probleem
[Één alinea: wie heeft pijn, waarom, en wat triggert de pijn.]

## Gebruikers
- [Primair gebruikersrol]
- [Secundair gebruikersrol]

## Doelen
1. [Meetbaar resultaat]
2. [Meetbaar resultaat]

## Niet-doelen
- [Expliciet buiten scope]
- [Expliciet buiten scope]

## Acceptatiecriteria
- [ ] [Verifieerbaar gedrag]
- [ ] [Verifieerbaar gedrag]

## Open vragen
- [ ] [Vraag die plannen blokkeert]

Fase 2 – Het Ontwerp Plannen

De planfase vertaalt intentie naar technische beslissingen. Hier horen Redis-sorteerde sets thuis, samen met modulegrenzen, schemawijzigingen, API-contracten, migratiestappen, beveiligingsbeperkingen en de teststrategie. Het plan is afgeleid van de vereistenspecificatie plus de bestaande beperkingen van je project – stackkeuzes, beslisrecords en conventies opgeslagen in bestanden zoals AGENTS.md of een projectconstitutie.

Architectuur en betrokken modules

Noem de modules, services of packages die zullen veranderen en vat het integratiepatroon samen. Als de functie een servicegrens overschrijdt, documenteer het contract aan beide kanten. Agents hallucineren API’s wanneer contracten impliciet zijn. Ze expliciet maken in het plan voorkomt verzinselde eindpunten en verkeerde responsvormen.

Datamodel, API-contracten en migraties

Documenteer schemawijzigingen, nieuwe tabellen of velden, indexvereisten en backward-compatibility-regels. Voor HTTP API’s, schrijf methode, pad, request-vorm, respons-vorm en foutcodes. Voor events, schrijf topicnamen, payload-schema’s en leveringssemantiek. Inclusief migratiestappen en rollback-opmerkingen wanneer het datamodel verandert.

Beveiliging, observabiliteit en teststrategie

Beveiligingsbeperkingen horen in het plan, niet als afterthoughts in code review. Noem authenticatievereisten, autorisatieregels, inputvalidatiegrenzen en data die niet in logs mag verschijnen. Observabiliteit moet metingen, logs of traces dekken die nodig zijn om te bevestigen dat de functie in productie werkt.

De teststrategie koppelt terug aan acceptatiecriteria. Identificeer welke criteria unit tests nodig hebben, welke integratietests nodig hebben en welke handmatige verificatie nodig hebben. Als je unit testing in Go of unit testing in Python gebruikt, noem de packages en testbestanden die je verwacht toe te voegen. Een plan zonder teststrategie is een plan dat gaten zal hebben die je in productie ontdekt.

Fase 3 – Implementatietaken Opbreken

De taakfase decomponeert het plan in slices klein genoeg om onafhankelijk te implementeren, te reviewen en te valideren. Dit is wat agent-geassisteerde ontwikkeling reviewbaar maakt. In plaats van één enorme diff, krijg je een reeks van gefocuste wijzigingen die elk terugkoppelen aan een benoemde vereiste.

Taakgrootte en afhankelijkheden

Een goede taak raakt een begrensde set bestanden, voltooit in één agentsessie en eindigt met een verificatiestap. Taken moeten afhankelijkheden expliciet verklaren. Migratietaken lopen voordat code het nieuwe schema leest. Wijzigingen in gedeelde bibliotheken lopen voordat consumenten. Wijzigingen in authenticatiemiddleware lopen voordat eindpunten die afhankelijk zijn van het nieuwe gedrag.

Bestanden, validatie en reviewcontrolepunten

Elke taak moet de bestanden opsommen die waarschijnlijk zullen veranderen, de acceptatiecriteria die hij vervult en hoe voltooiing te valideren. Validatie kan een testcommando zijn, een curl-voorbeeld, of een handmatige check beschreven in copy-pasteable stappen. Elke taak eindigt bij een menselijk reviewcontrolepunt. De reviewer bevestigt dat de diff overeenkomt met de taakbeschrijving voordat de volgende taak begint.

Een minimale taakentry:

### Taak 3 -- Rate-limit middleware toevoegen

**Afhankelijk van:** Taak 1 (schema), Taak 2 (repository)
**Bestanden:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Vult in:** AC-2 (429 boven limiet), AC-3 (limietkoppen in respons)
**Valideren:** `go test ./middleware/...` slaagt; curl boven limiet retourneert 429 met Retry-After
**Reviewcontrolepunt:** Bevestig dat middleware loopt na auth, voor handler

Pas op voor gegenereerde taakexplosies. AI-agents kunnen vijftig-taakplannen in seconden produceren. De meeste van die taken zullen redundant zijn of te granular om efficiënt te reviewen. Een nuttige takenlijst voor een middelgrote functie heeft vaak vijf tot vijftien items, niet vijftig.

Fase 4 – Implementeer Één Taak op een Tijd

Implementatie is bewust smal. Kies één taak, geef de agent alleen de context die hij nodig heeft voor die taak, en stop wanneer validatie slaagt. Contextreset tussen taken is een functie, geen bug. Ze voorkomen dat eerdere aannames later werk vervuilen en houden diffs reviewbaar.

Pas beperkingen toe vanuit de specstack

De implementerende agent moet de vereistenspec lezen, het ontwerpplan, de huidige taakbeschrijving en projectniveau-beperkingen. Beperkingen zijn het hoogste-ROI-sectie dat de meeste teams overslaan. Ze vertellen de agent wat hij niet moet doen – refactor niet ongerelateerde modules, verander geen openbare API-signaturen buiten deze functie, introduceer geen nieuwe afhankelijkheden zonder het plan bij te werken.

Werk het plan bij wanneer de realiteit verschilt

Implementatie zal verrassingen blootleggen. Een bibliotheek ondersteunt het aangenomen gedrag niet. Een migratie duurt langer dan verwacht. Een uitzonderingsgeval ontbrak in de acceptatiecriteria. Wanneer dat gebeurt, werk de spec bij voordat je doorgaat. Los de vereisten of het plan op, krijg een snelle review, en hervat implementatie tegen het gecorrigeerde artefact. Code die stil divergeert van de spec is hoe drift permanent wordt.

Fase 5 – Valideer Tegen de Spec

Validatie is waar SDD zijn waarde bewijst. Zonder het is de spec een oefening. Met het is de spec een contract dat je kunt controleren tegen de uitgebrachte code.

Geautomatiseerde controles

Voer de volledige testsuite, lint en typecontroles uit op CI. Koppel deze aan je pipeline met patronen uit de GitHub Actions cheatsheet als je een praktisch startpunt nodig hebt. Geautomatiseerde controles vangen regressies. Ze vangen niet verkeerde functies die correct zijn gebouwd, daarom blijft acceptatiecriteria-review belangrijk.

Acceptatiecriteria en handmatige review

Loop door elk acceptatiecriterium uit de vereistenspec. Markeer elk als vervuld, mislukt of uitgesteld met rechtvaardiging. Handmatige review vangt UX-problemen, beveiligingsgaten en verkeerd gedrag dat tests misten omdat de tests werden geschreven om te matchen met een gebrekkige spec.

Spec-naar-code diff

De laatste validatiestap vergelijkt de implementatie met het ontwerpplan. Matchten de bestanden die veranderden met de bestanden die het plan voorspelde? Matchten architectuurkeuzes in de code met de gedocumenteerde keuzes? Onverwachte bestanden in de diff zijn een signaal – of het plan was onvolledig of de agent dwaalde. Beide verdienen aandacht voor merge.

Waar AI-Agents in de Workflow Passen

AI-agents zijn versnellers in elke fase, geen vervangingen voor review. Het productieve patroon is concept, review, verfijn, en ga door. Vraag een agent om de vereistenspec te concepten vanuit een probleembeschrijving, en bewerk dan de intentie tot doelen, niet-doelen en acceptatiecriteria correct zijn. Vraag een agent om het ontwerpplan te concepten vanuit de goedgekeurde vereisten, en review dan architectuurkeuzes voordat er code bestaat. Vraag een agent om één taakslice op een tijd te implementeren, met jou die elke diff goedkeurt voordat de volgende taak begint.

Agents zijn vooral nuttig bij het produceren van eerste concepten en boilerplate-tests. Mensen zijn vooral nuttig bij het vangen van verkeerde doelen, onveilige architectuur en subtiele scope creep. De workflow faalt wanneer één van beide kanten wordt overgeslagen – wanneer agents implementeren zonder specs, of wanneer mensen specs schrijven zonder ze ooit te valideren tegen code.

Dit workflow-artikel blijft opzettelijk tool-neutraal. Tool-specifieke uitvoeringsgidsen – editor-instelling, slash-commando’s, agent-configuratie – horen onder de AI Developer Tools cluster. De procespijler leeft hier onder documentatiepraktijken omdat de artefacten belangrijker zijn dan de vendor.

Veelvoorkomende Fouten die Spec-Gedreven Ontwikkeling Doden

Enorme specs voordat er enige validatie plaatsvindt. Een dertig pagina’s tellend vereistendocument geschreven voordat een prototype of spike bestaat is waterfall-papierwerk, geen SDD. Schrijf de minimale spec die ambiguïteit verwijdert voor de volgende fase, en valideer aannames vroeg. Niet elke functie heeft de volledige vijf-fasenloop nodig – Spec-Gedreven Ontwikkeling vs Vibe Coding legt uit wanneer lichtere structuur genoeg is.

Vage acceptatiecriteria. Bijvoegwoorden zoals “snel”, “schoon” en “gebruiksvriendelijk” zijn geen acceptatiecriteria. Vervang ze met meetbaar gedrag. Als je het niet kunt testen, kun je het niet betrouwbaar implementeren – zeker niet met een AI-agent.

Ontbrekende niet-doelen. Zonder niet-doelen breiden agents scope standaard uit. Ze voegen cachinglagen toe, refactoren aangrenzende modules en introduceren afhankelijkheden die je niet vroeg hebt. Niet-doelen zijn hoe je van tevoren nee zegt.

Geen testplan in de ontwerpfase. Tests die pas na implementatie worden geschreven bevestigen vaak wat is gebouwd, niet wat was bedoeld. Het plan moet benoemen welke acceptatiecriteria aan welke testtypen koppelen voordat het eerste productbestand verandert.

Review overslaan bij fasengrenzen. De spec gereviewd voordat het plan. Het plan gereviewd voordat taken. Taken gereviewd voordat implementatie. Elke poort is goedkoop. Drift repareren na een grote merge is duur.

Gegenereerde taken laten exploderen. Behandel een vijftig-item AI-gegenereerde takenlijst als een eerste concept, niet als een planning. Merge redundante items, split oversized ones, en verwijder taken die niet koppelen aan een vereiste.

SDD werkt wanneer elke fase ambiguïteit vermindert. Het faalt wanneer het papierwerk creëert.

Herbruikbare Sjablonen

Kopieer deze naar je repository en pas ze aan. Bewaar specs naast de feature branch, review ze in pull requests, en houd ze in versiebeheer zodat agents en mensen dezelfde bron lezen.

Vereistensjabloon

# Functie -- [naam]

## Probleem
## Gebruikers
## Doelen
## Niet-doelen
## Acceptatiecriteria
## Open vragen

Ontwerpsjabloon

# Ontwerp -- [funktienaam]

## Samenvatting
## Betrokken modules
## Datamodelwijzigingen
## API-contracten
## Migraties
## Beveiliging
## Observabiliteit
## Teststrategie
## Risico's en mitigaties

Takenlijst sjabloon

# Taken -- [funktienaam]

## Taak 1 -- [titel]
Afhankelijk van:
Bestanden:
Vult in:
Valideren:
Reviewcontrolepunt:

## Taak 2 -- [titel]
...

Validatielijst

# Validatie -- [funktienaam]

## Geautomatiseerd
- [ ] Alle tests slagen
- [ ] Lint schoon
- [ ] Typecheck schoon

## Acceptatiecriteria
- [ ] AC-1 --
- [ ] AC-2 --

## Spec-naar-code
- [ ] Gewijzigde bestanden matchen plan
- [ ] Geen ongedocumenteerde architectuurwijzigingen
- [ ] Spec bijgewerkt als implementatie verschild

Conclusie

Spec-gedreven ontwikkeling gaat niet over het schrijven van meer documenten. Het gaat over het doorlopen van specificeren, plannen, taken, implementeren en valideren met een reviewpoort bij elke stap. Elke fase moet de volgende actor – mens of agent – achterlaten met minder gokwerk dan de fase ervoor.

Begin klein. Voer de volledige workflow uit op één middelgrote functie. Houd artefacten in markdown in de repository. Werk de spec bij wanneer de realiteit divergeert. Valideer voor merge. Wanneer de keten werkt, krijg je minder drift, kleinere reviewbare diffs, en een duurzame record van intentie die sessie-resets en teamoverdrachten overleeft.

Wanneer de keten papierwerk wordt, verklein de scope – niet de review. Een tweepaginasspec die werd gevalideerd wint van een dertigpagina’s tellende spec die niemand las.

Nuttige Links

• GitHub Spec Kit documentatie – open-source toolkit die een vergelijkbare specify-plan-taken-implementeer lus implementeert
• Martin Fowler over Spec-Gedreven Ontwikkeling tools – analyse van Kiro, Spec Kit, en Tessl