Spec-Driven Development: eerst specificeren, dan bouwen

"Bouw een checkout flow." Drie woorden, en Claude begint meteen te typen. Controllers, views, payment integrations. Na twintig minuten code heb je een checkout die niet doet wat je bedoelde. En dan begin je opnieuw.

Dit is het probleem met direct bouwen: je krijgt wat Claude denkt dat je wilt, niet wat je nodig hebt. Spec-Driven Development lost dit op door eerst te specificeren, dan pas te bouwen.

Het probleem met "bouw X"

Wanneer je Claude vraagt om iets te bouwen zonder spec, gebeuren drie dingen:

1. Aannames - Claude vult gaten in met zijn eigen interpretatie
2. Scope creep - features die je niet vroeg worden toegevoegd
3. Verkeerde richting - pas halverwege ontdek je dat het niet klopt

Dit is geen Claude-probleem. Het is een communicatieprobleem. Vaagheid leidt tot verkeerde output. Dat geldt voor mensen, en dat geldt voor AI.

De oplossing: spec-first

Bij Spec-Driven Development beschrijf je eerst WAT je wilt voordat je vraagt HOE het gebouwd moet worden. Dit heeft drie voordelen:

Alignment - Je dwingt jezelf om na te denken over wat je echt nodig hebt. Vaak ontdek je tijdens het specificeren dat je iets anders wilt dan je dacht.

Approval moment - Er zit een checkpoint tussen plan en uitvoering. Je kunt de spec reviewen, aanpassen, en pas dan groen licht geven.

Referentiepunt - Tijdens de bouw kun je terugverwijzen naar de spec. "Dit matcht niet met wat we afspraken."

De workflow

Mijn feature workflow volgt een vaste structuur:

1. Trigger

Een Linear issue of /feature command start het proces. Dit geeft context over WAT er gebouwd moet worden.

2. Research

Voordat er iets gespecificeerd wordt, verzamelt Claude context. Welke patterns bestaan al in de codebase? Welke dependencies zijn relevant? Dit voorkomt dat de spec iets voorstelt dat niet past.

3. Spec (Plan Mode)

Plan Mode is hiervoor gemaakt. Claude kan lezen en analyseren, maar niet schrijven. Dit dwingt focus op het plan, niet op de implementatie.

De spec bevat:

• Wat doet de feature (user perspective)
• Welke files worden geraakt
• Hoe integreert het met bestaande code
• Edge cases die afgehandeld moeten worden

Wat er NIET in hoort: code. Specs beschrijven, ze implementeren niet.

4. Approval

Hier komt het approval moment. Je reviewt de spec, stelt vragen, vraagt aanpassingen. Pas als je akkoord bent, gaat Claude door.

5. Sub-tasks

Voor complexere features breekt Claude de spec op in sub-tasks. Dit maakt voortgang trackbaar en voorkomt dat Claude verdwaalt in grote implementaties.

6. Implement

Nu pas wordt er code geschreven. Met de spec als leidraad, niet als suggestie.

Complexiteit inschatten

Niet elke feature verdient dezelfde aanpak:

Voor een simpele bugfix is een volledige spec workflow overkill. Maar voor een nieuwe feature met database changes, API endpoints en frontend componenten? Dan wil je dat approval moment.

Wat hoort in een spec?

Een goede spec beantwoordt deze vragen:

Functioneel:

• Wat kan de gebruiker doen na deze feature?
• Welke edge cases moeten afgehandeld worden?
• Wat gebeurt er bij errors?

Technisch:

• Welke models/tables worden aangemaakt of aangepast?
• Welke routes en controllers zijn nodig?
• Hoe integreert dit met bestaande authentication/authorization?
• Welke bestaande code moet aangepast worden?

Scope:

• Wat zit er expliciet NIET in deze feature?
• Welke follow-up werk is er na deze implementatie?

Het verschil in praktijk

Zonder spec:

"Bouw een notificatie systeem"
→ Claude bouwt 20 files
→ Gebruikt verkeerde notification driver
→ Geen rate limiting
→ UI past niet bij design system
→ Moet opnieuw

Met spec:

"Spec een notificatie systeem"
→ Claude onderzoekt bestaande code
→ Spec: database notifications, max 5/uur, Flux UI components
→ Review: "voeg ook email fallback toe"
→ Aangepaste spec goedgekeurd
→ Implementatie volgt spec exact

Het verschil is niet de tijd die je erin steekt. Het verschil is verspilde tijd die je voorkomt.

Integratie met Claude Code

Claude Code heeft native ondersteuning voor deze workflow:

• Plan Mode - read-only modus voor specs
• Tasks - track sub-tasks en voortgang
• Skills - automatiseer de workflow

In mijn setup triggert een Linear issue automatisch de hele flow. Research, spec, approval, implement, test, document. Elke stap gestructureerd, elke stap tracked.

Wanneer NIET spec-first

Spec-Driven Development is niet voor alles:

• Bugfixes - als het probleem duidelijk is, fix het gewoon
• Refactoring - je weet al wat de code moet doen
• Exploratie - soms moet je eerst bouwen om te begrijpen wat je wilt
• Triviale changes - een tekst aanpassen heeft geen spec nodig

De regel: als je het in je hoofd kunt houden, heb je geen spec nodig. Zodra je dingen gaat vergeten, wel.

Conclusie

Spec-Driven Development is niet meer werk. Het is ANDER werk. In plaats van tijd verspillen aan verkeerde implementaties, investeer je tijd in alignment vooraf.

Het resultaat: minder frustratie, betere output, snellere delivery. Niet omdat Claude slimmer is, maar omdat Claude weet wat je wilt.

Wil je dit leren toepassen? Bekijk mijn trainingen of neem contact op.