Spec-driven development

Wat is spec-driven development?

Spec-driven development is software bouwen door eerst een specificatie te schrijven en coding agents daaruit het plan, de takenlijst en de code te laten afleiden. De specificatie zegt wat je wil, welke regels het moet respecteren en aan welke criteria je ziet dat het af is. Ze staat in de repository, onder versiebeheer, naast de code die ze beschrijft.

Waar het om draait, is waar de bedoeling zit. Bouw je met een agent via chat, dan zitten de redenen achter elke beslissing in een gesprek dat niemand herleest en dat weg is zodra de context leeggemaakt wordt. Met een specificatie zit de bedoeling in een bestand. Een nieuwe sessie vertrekt van dat bestand, een collega leest het na, en een tweede agent toetst de code eraan.

GitHub omschreef het zo bij de release van zijn toolkit Spec Kit in september 2025: de specificatie is een levend contract voor hoe de code zich moet gedragen, en ze wordt de gedeelde bron van waarheid die de implementatie, de tests en de validatie stuurt. Kiro van Amazon, twee maanden eerder gelanceerd, is rond hetzelfde idee gebouwd, en lichtere alternatieven zoals OpenSpec volgden. Eerst afspreken wat je bouwt, is een oud idee. Wat veranderd is: een geschreven specificatie is nu iets waar een machine rechtstreeks mee aan de slag kan.

Vergelijk het met het plan dat je met een aannemer tekent voor de ploeg aankomt. Daar staat op hoeveel kamers er komen, welke muren dragen en wat de keuring op het einde moet bevestigen. Er staat niet op welk merk vijzen hij gebruikt. Op dat niveau werkt een specificatie.

De vier fasen

De meeste tools verdelen het werk in dezelfde vier fasen, hoe ze die ook noemen.

1. Specify. Je beschrijft wat je wil en waarom. De agent maakt daar een specificatie van: user stories, de regels die gelden en acceptatiecriteria die je kan testen. Bij Spec Kit heet dat bestand spec.md, bij Kiro requirements.md. De regel van GitHub voor dit bestand: wat gebruikers nodig hebben en waarom, zonder tech stack, zonder API-ontwerp en zonder codestructuur.

2. Plan. Nu komen de technische randvoorwaarden erbij: de stack die je al draait, de systemen waarmee het moet praten, de veiligheidsregels. De agent schrijft een implementatieplan (plan.md bij Spec Kit, design.md bij Kiro). Een developer leest dit bestand na; een zaakvoerder hoeft het niet te lezen.

3. Tasks. Het plan wordt opgedeeld in kleine, controleerbare stukken in tasks.md, elk klein genoeg om de diff die het oplevert in één keer na te lezen.

4. Implement. De agent werkt de taken af, draait de checks die de specificatie vraagt, en geeft wijzigingen terug die je kan nalezen in plaats van één grote lading code.

Spec Kit voegt optionele stappen toe, zoals een constitution met regels die voor elke feature gelden en een clarify-stap die gaten zoekt voor er gepland wordt. OpenSpec organiseert hetzelfde werk per wijziging in plaats van per feature, wat beter past bij een bestaande codebase. Allemaal bewaren ze de bestanden in de repository; Kiro zet ze onder .kiro/specs/ en kan de takenlijst opnieuw opbouwen als de vereisten veranderen. Dat is wat de specificatie doet overleven: een chatgeschiedenis is weg na de sessie, een bestand in git heeft een diff en iemand die hem naleest.

Wat in een goede specificatie staat, en wat niet

De richtlijnen van Anthropic voor Claude Code omschrijven de nuttigste specificaties als zelfstandig leesbaar: ze noemen de bestanden en koppelingen die erbij betrokken zijn, ze zeggen wat buiten scope valt, en ze eindigen met een end-to-end controle die bewijst dat de feature werkt. Ze voegen eraan toe dat tijd steken in een precieze specificatie meer oplevert dan toekijken op de implementatie.

Een specificatie die je aan een agent kan geven, heeft vier delen.

Bedoeling. Eén of twee zinnen over wat het de zaak moet opleveren. Minder retourmails bij de verkoopdienst.

Randvoorwaarden. De regels die overeind moeten blijven, wat de implementatie ook doet. Enkel gefactureerde orders. Niets verlaat de EU-regio.

Acceptatiecriteria. Uitspraken die waar of onwaar zijn zodra de feature bestaat. Kiro schrijft die in EARS-notatie, een formaat dat ingenieurs van Rolls-Royce in 2009 voor het eerst publiceerden voor de besturingssoftware van straalmotoren: "WHEN a customer submits a valid return request THE SYSTEM SHALL create a return with a reference number." Elk criterium heeft een trigger en een waarneembare reactie, zodat je er zonder interpretatie een test van maakt.

Buiten scope. Wat de agent niet mag aanraken. Dit is het deel dat mensen vergeten, en het deel dat verhindert dat de agent onderweg behulpzaam je facturatiemodule herbouwt.

Wat de specificatie weglaat, is het hoe. Stack, bibliotheken, databasetabellen, klassenamen: die horen in het plan, waar ze kunnen veranderen zonder dat de afspraak verandert. Schermindelingen en knoppen horen meestal in geen van beide bestanden. Een mock-up bij het plan doet dat werk beter, en tekst over de UI is de snelste manier om een specificatie te schrijven die niemand kan controleren.

Een uitgewerkt voorbeeld

Een groothandel wil dat klanten retours aanvragen via het klantenportaal in plaats van per mail. De zaakvoerder en de leverancier zitten samen over de specificatie voor er iemand code opent.

Bedoeling: retouraanvragen komen in het ERP terecht met de juiste lijnen eraan, zodat de verkoopdienst ze niet meer overtypt. Randvoorwaarden: enkel lijnen van gefactureerde orders die minder dan 30 dagen geleden geleverd zijn; terugbetalingen en creditnota's blijven in het ERP zoals vandaag. Drie acceptatiecriteria: WHEN een klant lijnen selecteert van een bestelling die in aanmerking komt THE SYSTEM SHALL een retouraanvraag aanmaken in het ERP met status "nieuw" en de referentie naar de klant mailen. IF de levering ouder is dan 30 dagen THEN THE SYSTEM SHALL de aanvraag weigeren en het telefoonnummer van de verkoopdienst tonen. WHEN een retour aangemaakt is THE SYSTEM SHALL de factuur en de stockniveaus ongewijzigd laten. Controle: maak een testbestelling aan die tien dagen geleden geleverd is, vraag een retour aan voor twee lijnen, en controleer dat de retour in het ERP staat met die twee lijnen en dat de mail vertrokken is.

Die pagina leest de zaakvoerder in vijf minuten, en ze kan zeggen of het klopt. Wat ze niet kan beoordelen, de keuze van de API of hoe het portaal zich aanmeldt bij het ERP, staat in het plan dat de developer naleest. De agent maakt dan de taken, voert ze uit en draait de controle. Vindt de review een gat, dan begint de fix in de specificatie, niet in de chat.

Spec-driven development versus vibe coding, klassieke vereistendocumenten en BDD

Versus vibe coding

De twee gebruiken dezelfde agents. Het verschil is waar de bedoeling zit. Bij vibe coding zit die in de chat en in het hoofd van wie typt; de code wordt ongelezen aanvaard en op één ding beoordeeld: draait ze of niet. Bij spec-driven development zit ze in een bestand onder versiebeheer dat een niet-technische zaakvoerder kan goedkeuren en waar de verification loop zijn criteria uit haalt. De blogpost van GitHub noemt het probleem waar de aanpak tegen geschreven is: beschrijf in een alinea wat je wil, en de agent geeft code terug die er juist uitziet maar niet compileert, de bedoeling mist of botst met de bestaande architectuur. Een specificatie lost het tweede en het derde op.

Versus vereistendocumenten, user stories en BDD

Een vereistendocument van voor de agents was geschreven voor mensen, werd één keer gelezen en bleef achter terwijl de code verder evolueerde. De ontwerpnotities van Spec Kit zeggen het zonder omwegen: de code was de bron van waarheid, en de specificaties hielden zelden gelijke tred. Een specificatie voor een agent moet precies genoeg zijn om er een machine mee te laten werken, en ze krijgt een diff bij elke wijziging aan de feature, wat de enige reden is waarom ze waar blijft.

User stories en de Given/When/Then van behaviour-driven development gaan bijna ongewijzigd mee; de tekst van Thoughtworks over de aanpak zegt dat de gewoontes uit BDD blijven gelden. Wat nieuw is, is de lezer. Een BDD-scenario werd gelezen door een developer die daarna de test en de code schreef. Een specificatie wordt gelezen door een agent die allebei schrijft, dus de gaten die een developer uit ervaring opvulde, moeten nu op papier staan.

Hoe ver je erin gaat

Birgitta Böckeler van Thoughtworks onderscheidt drie niveaus, en het woord "spec-driven" dekt ze alle drie.

Spec-first. Je schrijft de specificatie voor de code, voor één taak, gebruikt ze om de agent aan te sturen en houdt ze niet meer bij zodra de feature live staat. Dat doen de meeste teams, en het is wat de werkwijze van Anthropic beschrijft: laat de agent je interviewen, schrijf SPEC.md, start een verse sessie.

Spec-anchored. De specificatie blijft leven naast de code en wordt aangepast als de feature verandert. De sync tussen vereisten en taken in Kiro is daarvoor gebouwd.

Spec-as-source. De specificatie is wat je onderhoudt en de code wordt eruit gegenereerd; niemand past de code nog met de hand aan. De ontwerpnotities van Spec Kit neigen die kant op, met code als "the last-mile approach". Thoughtworks zelf is voorzichtiger: de specificatie stuurt de generatie, zoals een test de code stuurt bij TDD, maar de code die draait blijft wat je onderhoudt, want het genereren is niet deterministisch en het uiteenlopen van specificatie en code is volgens hen bijna niet te vermijden.

Voor de meeste KMO's zit de waarde bij spec-first voor alles wat groter is dan een bugfix, en spec-anchored voor de twee of drie features waar de zaak van afhangt.

Waar moet je op letten bij spec-driven development

Spec theatre. Het oordeel van Böckeler nadat ze de tools geprobeerd had: ze leest liever code na dan al die markdownbestanden. Als een bugfix van twee regels een specificatie, een plan en een takenlijst oplevert, is het proces het product geworden. De vuistregel van Anthropic voor plan mode geldt hier ook: kan je de diff in één zin beschrijven, sla het dan over.

Specificaties die van de code afdrijven. Zodra iemand iets in de code herstelt en niet in de specificatie, liegt het bestand, en een agent die het later leest, handelt naar die leugen. Behandel de specificatie als een test: ze verandert in dezelfde pull request als het gedrag dat ze beschrijft, of ze gaat weg.

De UI te ver vastleggen. Een specificatie die elk label en elke kolombreedte dicteert, is niet te controleren en veroudert snel. Leg het gedrag en de data vast; laat het plan de mock-up dragen.

De agent negeert ze toch. Böckeler zag ook agents instructies uit de specificatie overslaan of te gretig opvolgen, tot ze code dubbel schreven die al bestond. De specificatie legt de criteria vast; de verification loop en een menselijke review moeten nog altijd nagaan of ze gehaald zijn.

Wie schrijft ze. De tools gaan ervan uit dat iemand een wens uit de zaak kan omzetten in testbare criteria. In een klein bedrijf zijn dat de zaakvoerder en de leverancier samen, in één vergadering, voor er een agent draait. Plan die vergadering in. Het is het goedkoopste uur van het project.