Wat is specificatie-gedreven ontwikkeling? De specificatie als bron van waarheid

De specificatie als bron van waarheid, niet als bijlage.

Inhoud

Spec-gedreven ontwikkeling is één van die ideeën waarnaar software-ingenieurs eerder hebben gegrepen en vervolgens hebben opzijgezet toen de inspanning niet meer opwog.

Wat in 2025 veranderd is, is dat AI-coderingsagenten arriveerden en het ontbreken van expliciete intentie duur maakten. Prompts zijn vluchtig. Agentsessies worden gereset. Code verandert, maar de redenering achter deze verdwijnt. De specificatie (spec) is het artefact dat dit voorkomt.

Wat is Spec-gedreven Ontwikkeling – de spec als bron van waarheid voor AI-codering

De Spec Wordt de Bron van Waarheid

Gedurende het grootste deel van de geschiedenis van softwareontwikkeling was de spec ofwel een tijdelijk planmingsartefact of een achteraf toegevoegd detail. Eisen woonden in tickets, ontwerpbepalingen in chatthreads en de code was de grondwaarheid. Documentatie beschreef wat er achteraf bestond.

Spec-gedreven ontwikkeling draait die relatie om. De specificatie wordt het primaire artefact. Code is wat gegenereerd of geverifieerd wordt tegen de spec, niet andersom.

Dit is geen nieuw idee. Formele methoden, design-by-contract en BDD bevatten allemaal varianten ervan. Wat nieuw is, is de praktische motivatie: AI-coderingsagenten hebben expliciete, duurzame context nodig om correcte en consistente output te produceren. Prompts zijn te vluchtig. De spec is het enige artefact dat intentie kan dragen over agentsessies heen, over teamleden heen en door de tijd heen.

Wat Spec-gedreven Ontwikkeling Echt Betekent

Spec-gedreven ontwikkeling, meestal afgekort tot SDD, is een workflow waarbij een geverifieerde specificatie de implementatie begeleidt of genereert. De specificatie wordt geschreven en beoordeeld voordat de agent code schrijft. Het vangt op:

  • Wat er gebouwd moet worden – gebruikersprobleem, doelen en niet-doelen
  • Hoe correct gedrag eruit ziet – acceptatiecriteria, uitzonderingsgevallen, fouttoestanden
  • Hoe het gebouwd moet worden – architectuurkeuzes, datamodel, API-overeenkomsten, beveiligingsbeperkingen
  • Hoe het geverifieerd kan worden – teststrategie, validatieregels, traceerbaarheid terug naar de eisen

De spec is geen eenmalig document. Het wordt bijgewerkt wanneer de realiteit afwijkt van het ontwerp. Wanneer de agent tijdens de implementatie iets ontdekt dat de spec verkeerd had, wordt de spec gecorrigeerd voordat wordt doorgegaan. De spec blijft eerlijk omdat het als code wordt behandeld.

Recent academisch werk formaliseert deze framing: onderzoekers beschrijven SDD als het behandelen van specificaties als de bron van waarheid en code als gegenereerd of geverifieerd tegen deze. De praktische interpretatie is dat de spec het beoordeelde, duurzame register van intentie is dat elke mens of AI-tool kan lezen en vertrouwen.

Drie termen vangen verschillende punten op het spectrum van spec-gebruik:

Spec-first betekent het schrijven van de volledige specificatie voordat enige implementatie begint. Dit is de strengste interpretatie en de één die het dichtst bij waterfall ligt als het niet zorgvuldig wordt gedaan.

Spec-geankerd betekent het synchroniseren van een specificatie met de implementatie gedurende de hele levenscyclus van de feature. De spec wordt bijgewerkt naarmate beslissingen veranderen. Dit is de meest praktische versie voor de meeste teams.

Spec-as-source betekent het genereren of valideren van implementatie vanuit de spec, ofwel door AI-agenten of door tooling die code controleert tegen spec-beperkingen. Dit is de richting waar tools zoals GitHub Spec Kit en Kiro naartoe bewegen.

Waarom SDD Nu Belangrijk Is

Het eerlijke antwoord is dat SDD niet overtuigend is voor een solo-developer die een script voor één dag bouwt. De overhead is het niet waard.

SDD wordt waardevol wanneer drie voorwaarden aanwezig zijn: de feature is groot genoeg om meerdere sessies te beslaan, de agent moet beslissingen nemen die de architectuur beïnvloeden, en het werk zal worden beoordeeld of voortgezet door iemand anders.

Alle drie de voorwaarden komen steeds vaker voor bij AI-geassisteerde ontwikkeling.

LLMs hebben context nodig, niet alleen prompts. Een model dat een vaag prompt ontvangt, neemt vage beslissingen. Een model dat een beoordeelde specificatie met expliciete beperkingen, niet-doelen en acceptatiecriteria ontvangt, neemt betere beslissingen en is gemakkelijker te corrigeren wanneer het afwijkt. Dit hangt samen met hoe retrieval en representatie werken: een agent een geverifieerde spec geven is een vorm van gestructureerde retrieval van projectintentie.

Codegeneratie is goedkoop; beslissen wat er gebouwd moet worden is nog steeds moeilijk. De bottleneck bij AI-geassisteerde ontwikkeling is niet langer typen – het is weten wat er gebouwd moet worden en hoe de agent te beperken. SDD verschuift de inspanning naar waar het toe doet: het duidelijk specificeren van intentie voordat de generatie begint.

Prompts zijn vluchtig. De agent onthoudt niet wat je hem in de vorige sessie hebt verteld. Een geverifieerde specificatie die in de repository is opgeslagen, wel. Elke nieuwe sessie kan dezelfde spec lezen en implementeren tegen dezelfde intentie zonder de context van voor af opnieuw te moeten vaststellen.

Vibe coding werkt totdat het niet meer doet. Voor prototypes en wegwerpwerk is ad-hoc prompten sneller en gepast. Zodra een feature beveiligingsbeperkingen, architectuurkeuzes over meerdere bestanden of een overdracht binnen het team vereist, wordt het ontbreken van een spec de belangrijkste bron van afwijking en defecten. Zie de vergelijking in SDD vs Vibe Coding voor wanneer elke aanpak van toepassing is.

Kernartefacten

Een praktische SDD-workflow produceert vier hoofdartefacten. Elk vermindert een specifieke vorm van ambiguïteit voordat deze de agent bereikt.

Eisenspecificatie. Het probleemstatement, de betrokken gebruikers, de doelen, de expliciete niet-doelen en de acceptatiecriteria. Niet-doelen zijn net zo belangrijk als doelen – ze vertellen de agent wat er niet gebouwd moet worden en voorkomen scope creep. Acceptatiecriteria zijn precies genoeg dat elk ervan in kaart gebracht kan worden naar ten minste één test.

Ontwerpspecificatie. De architectuurkeuzes relevant voor deze feature: betrokken modules, datamodelwijzigingen, API-overeenkomsten, migraties, beveiligingsbeperkingen, observabiliteitsvereisten en bekende faalmodes. Dit is geen volledig systeemontwerppapier – het is het subset van architectuurkeuzes dat nodig is om deze feature correct te implementeren.

Taakplan. Een reeks kleine implementatietaken, elk met expliciete afhankelijkheden, verwachte bestandswijzigingen en validatiecriteria. Taken zijn klein genoeg om te implementeren in een enkele agentsessie en te verifiëren met een focussed diff. Elke taak heeft een menselijke review-checkpoint.

Traceerbaarheidsregister. Een mapping van acceptatiecriteria naar tests, van ontwerpbepalingen naar betrokken bestanden, en van taken naar commits. Dit is wat SDD scheidt van documentatie die veroudert: traceerbaarheid maakt het mogelijk te verifiëren dat de spec daadwerkelijk is geïmplementeerd, niet alleen geschreven.

Deze artefacten hoeven niet zwaar te zijn. Een eenvoudige feature kan een enkel markdown-document van twee pagina’s produceren dat alle vier de gebieden dekt. De format is minder belangrijk dan de gewoonte om intentie op te schrijven voordat de implementatie begint.

Hoe SDD Verschilt van Documentatie

De meest voorkomende verwarring is het behandelen van SDD-artefacten als documentatie. Ze zijn geen documentatie in de conventionele zin.

Documentatie beschrijft. Het vertelt je wat het systeem doet, hoe je het gebruikt en wat het bevat. Het wordt achteraf geschreven en bijgewerkt wanneer het systeem verandert.

Specs beperken. Een spec vertelt de agent wat het mag bouwen en wat het niet mag doen. Het is autoritair voordat de implementatie begint. Het wordt geverifieerd na voltooiing van de implementatie. Een spec die beschrijft wat er daadwerkelijk is gebouwd – in plaats van te beperken wat er gebouwd moet worden – heeft zijn doel al gemist.

Uitvoerbare specs begeleiden generatie en validatie. De beste SDD-specs zijn dicht genoeg bij machine-leesbaar zodat een agent ertegen kan implementeren en een testsuite ze kan verifiëren. Acceptatiecriteria geschreven als “het eindpunt moet niet-geauthenticeerde verzokken afwijzen met een 401-reactie” is een uitvoerbare spec; “het eindpunt is veilig” is documentatie.

Decision Records – ADRs, PDRs en DDRs – zijn complementair aan SDD-artefacten maar dienen een ander doel. Decision records vangen op waarom een keuze werd gemaakt en wat werd afgewezen. SDD-specificaties vangen op wat er gebouwd moet worden en hoe het geverifieerd kan worden. Beide behoren in de repository thuis. Samen geven ze AI-agenten het volledige beeld: de huidige intentie en de redenering erachter.

Hoe SDD Verschilt van TDD

Test-gedreven Ontwikkeling en Spec-gedreven Ontwikkeling worden vaak verward omdat beide expliciete artefacten produceren voordat code bestaat. Het verschil is het startpunt.

TDD begint met tests. Je schrijft een falende test die het gedrag beschrijft dat je wilt, en schrijft dan de minimale code om deze te laten slagen. TDD is een feedbacklus op het eenheidsniveau. Het produceert goede tests maar beantwoordt niet de vraag of je het juiste ding bouwt.

SDD begint met intentie. Voordat tests bestaan, voordat de architectuur is beslist, beantwoordt de spec: wie heeft dit probleem, hoe ziet correct gedrag eruit, wat valt expliciet buiten de scope. De spec informeert vervolgens welke tests geschreven moeten worden, waarom goede SDD en goede TDD complementair zijn in plaats van concurrerend.

Een praktische manier om erover na te denken: SDD drijft TDD. De acceptatiecriteria in de spec worden de testscenario’s. De ontwerpspec identificeert de integratiegrenzen die contracttests nodig hebben. Het taakplan identificeert welke eenheidsgedragingen testdekking nodig hebben voordat de agent ze implementeert.

Hoe SDD Verschilt van BDD

Behavior-Driven Development gebruikt natuurlijke taalscenario’s – typisch in Gherkin-formaat – om verwacht gedrag vanuit het perspectief van de gebruiker te beschrijven. Deze scenario’s overbruggen de kloof tussen businessintentie en technische implementatie.

SDD is breder. Het omvat gedragsbeschrijvingen (die BDD-stijl taal of platte proza kunnen gebruiken) maar dekt ook architectuurkeuzes, datamodellen, beveiligingsbeperkingen, taakplanning en traceerbaarheid. BDD kan een nuttig formaat zijn voor het schrijven van acceptatiecriteria binnen een SDD-eisenspecificatie. De spec is de container; BDD-scenario’s zijn één manier om te schrijven wat erin gaat.

Het onderscheid is in de praktijk belangrijk: BDD-tooling focust op het uitvoerbaar maken van scenario’s. SDD-praktijk focust op het duurzaam maken van intentie – over tools heen, over sessies heen en over teamleden heen.

Hoe SDD Verschilt van Formele Methoden

Formele methoden gebruiken wiskundige notatie en geautomatiseerde verificatie om eigenschappen van softwaresystemen te bewijzen. Ze zijn uiterst rigoureus en uiterst duur voor de meeste productontwikkelingscontexten.

SDD vereist geen formele notatie. Een markdown-bestand met acceptatiecriteria en architectuurkeuzes is een specificatie. Het beperkt zonder wiskundig formeel te zijn. Het niveau van rigour schaleert met de inzet: een spec voor een facturatiendienst moet preciezer en zorgvuldiger beoordeeld zijn dan een spec voor een documentatiepagina.

De relatie is een spectrum:

  • Informele prozaspec (minimum viabele SDD)
  • Gestructureerd markdown met acceptatiecriteria en niet-doelen
  • Machine-leesbare spec met schema-validatie
  • Contracttests afgeleid direct uit de spec
  • Formele spec met geautomatiseerd bewijs

De meeste teams opereren in het midden van dat spectrum. Het doel is niet wiskundige rigour – het is het expliciet maken van intentie zodat een AI-agent ertegen kan implementeren en een menselijke reviewer het resultaat kan verifiëren.

Voordelen van Spec-gedreven Ontwikkeling

Minder intentie-afwijking. De spec is de referentie. Wanneer de agent afwijkt – en dat zal het doen – heeft de reviewer iets om de implementatie tegen te vergelijken. Zonder een spec is afwijking onzichtbaar tot iets breekt.

Betere AI-outputs. Agents met expliciete beperkingen, niet-doelen en acceptatiecriteria produceren implementaties die dichter bij het beoogde liggen en gemakkelijker te corrigeren zijn wanneer ze missen. Contextkwaliteit bepaalt direct de outputkwaliteit.

Eenvoudigere review. Een pull request gekoppeld aan een spec is gemakkelijker te reviewen dan een pull request waarbij de reviewer de intentie moet reconstrueren uit de code. De spec is de review-checklist.

Teamalignering. Wanneer meerdere mensen of agents aan dezelfde feature werken, is de spec het gedeelde contract. Zonder het optimaliseert elke bijdrager lokaal en passen de stukken mogelijk niet bij elkaar.

Betere testplanning. Acceptatiecriteria in de spec mappen direct naar testgevallen. Testdekking wordt een spec-dekkingsvraag: wordt elk acceptatiecriterium gedekt door ten minste één test?

Duurzame overdracht. Wanneer een feature van handen wisselt – tussen engineers, tussen agentsessies, tussen sprints – is de spec het overdrachtsartefact. Het vangt op wat besloten is, wat buiten de scope viel en wat nog reste om te valideren.

Kosten van Spec-gedreven Ontwikkeling

Voortijdige inspanning. Het schrijven van een goede spec voordat enige code wordt geschreven kost tijd. Voor kleine features is deze overhead reëel en soms niet de moeite waard.

Valse zekerheid. Een spec die bestaat maar niet geverifieerd wordt tegen de implementatie geeft een vals gevoel van juistheid. Verouderde specs zijn soms erger dan geen spec: ze misleiden reviewers en agents die ze lezen.

Verouderde specs. Specs wijken af wanneer het team ze behandelt als planmingsartefacten in plaats van levende documenten. Het bijwerken van de spec wanneer de implementatie afwijkt van het ontwerp is niet optioneel – het is wat SDD scheidt van documentatie die ophoopt en rot.

Gegenereerde bureaucratie. AI-agenten kunnen uitputtende taaklijsten en verbaal specificaties snel genereren. Een 200-taak spec gegenereerd in dertig seconden is geen nuttige spec – het is een bureaucratiegenerator. Goede SDD vereist oordeel over wat gespecificeerd moet worden en wat impliciet mag blijven.

Tool-lock-in. Sommige SDD-tools zijn opinioneel over formaat, bestandsstructuur en workflow. Een spec geschreven in een proprietair formaat is moeilijker over te dragen tussen tools dan een markdown-bestand met duidelijke headers en acceptatiecriteria.

Conclusie

Spec-gedreven ontwikkeling is geen nieuwe methodologie. Het is een oude discipline die opnieuw praktisch wordt omdat de kosten van impliciete intentie nu zichtbaar zijn in AI-genererde code.

De discipline is eenvoudig: schrijf op wat je van plan bent te bouwen, beoordeeld en geverifieerd, voordat de agent het bouwt. Houd dat register eerlijk door het bij te werken wanneer de realiteit afwijkt. Gebruik het als referentie voor review, testen en overdracht.

De spec is geen magie. Een spec die niet geverifieerd wordt, wordt het duurste soort documentatie: één die met vertrouwen misleidt. Goede SDD is de praktijk van het eerlijk houden van specs – klein genoeg om te onderhouden, precies genoeg om te beperken, en duurzaam genoeg om elke enkele agentsessie te overleven.

SDD zit op de snijlijn van documentatiepraktijk, testarchitectuur en codeontwerp – allemaal gedekt in de App Architecture in Production cluster naast decision records, API-ontwerp en data-toegangspatronen.

Abonneren

Ontvang nieuwe berichten over systemen, infrastructuur en AI-engineering.