Spec-driven development met Claude Code: een begeleide tutorial

Wat is spec-driven development?

Spec-driven development is een workflow gebaseerd op drie documenten, in deze volgorde: een document dat vertelt wat een wijziging moet doen, een plan dat de stappen specificeert, en code die tegen het plan in wordt geschreven, met een menselijke review tussen elk paar.

De drie reviewmomenten waar een feature doorheen gaat bij spec-driven development.

Een spec is een kort document, in gewone taal en vóór elke code, dat zegt wat een wijziging moet doen. Neem een feature als "laat gebruikers hun data exporteren". Een spec hiervoor legt de antwoorden vast die een agent anders zou moeten raden. Hij somt op 

• Ondersteunde bestandsformaten
• De leveringswijze
• Het gedrag tijdens een half-afgeronde export
• De delen van de feature die bewust buiten scope blijven

Hier is de echte opening van een spec die Claude Code schreef voor een workout-shape-verification-wijziging in een Telegram-gebaseerde accountability-app van mij. De wijziging vervangt een kwetsbare hartslagdrempel door een controle op de vorm van de hartslagcurve door de tijd heen:

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

Het plan is het volgende document. Het breekt de bovenstaande spec op in genummerde taken waar de agent één voor één aan kan werken; elke taak noemt een bestand, een wijziging, een volgorde en een test. Waar de spec het "wat" beantwoordt, beantwoordt het plan "in welke stappen". 

De code komt als laatste, geschreven tegen het plan, stap voor stap.

Drie documenten. Een menselijke review zit tussen elk paar. Je beoordeelt de spec vóór deze een plan wordt. Je beoordeelt het plan vóór het code wordt. Je beoordeelt de code vóór de merge.

Hoe spec-driven development verschilt van planmodus

Je hebt misschien Claude Code’s ingebouwde planmodus gebruikt (druk twee keer op Shift+Tab om deze te openen) en je afgevraagd wat hier anders is. Planmodus produceert in één enkele chatbeurt een plan. Het plan leeft in het geheugen, zonder bewaarde spec en zonder reviewstap tussen de fases.

Spec-driven development bewaart de spec en het plan als bestanden op schijf. Elk document krijgt een menselijke review vóór de volgende fase begint, en de artefacten overleven over sessies heen. Planmodus perst twee fasen van softwareontwikkeling in één chatbeurt. Dat werkt voor kleine klussen en faalt zodra de codebase groeit en echte gebruikers gaat bedienen.

Waarom vibe-coding een muur raakt

Vibe-coding werkt voor prototypes, enkele bestanden en wegwerpscripts. Het wordt lastiger in echte applicaties met gebruikers en in bestaande, grote codebases. De nuttige grens ligt rond 4 bestanden. Elke wijziging die zoveel bestanden raakt, heeft een spec nodig—net als elke refactor met een helder einddoel, of elke taak waarbij "wat moet dit precies doen?" het moeilijke deel is.

De oorzaak van de mislukking is helder. Een vage prompt zoals "voeg fotodelen toe aan mijn app" dwingt het model duizenden onuitgesproken requirements te raden.

Neem één zo’n requirement: notificatievoorkeuren. De productmanager verwacht per-kanaal-toggles. De backend bouwt een aan/uit-schakelaar. De frontend gaat uit van OS-integratie. Vier redelijke lezingen van drie woorden, vier verschillende producten.

Elke reviewstap in spec-driven development vangt een andere foutklasse af voordat het duur wordt. De specreview vangt scope creep en verkeerde probleemkaders. De planreview vangt half-afgeronde implementaties en conflicterende patronen. De codereview vangt plannen die goed lezen maar breken bij de eerste falende test.

De payoff is echt en bouwt langzaam op. De specfase kost uren schrijven vóór er code draait, en de eerste paar features voelen langzamer dan vibe-coding. Mijn eigen break-even kwam rond de vierde of vijfde feature. Toen onderschepten de specs ontwerpfouten die ik anders had verscheept en een week later had herschreven.

De komende drie secties behandelen drie open-source aanpakken die deze workflow binnen Claude Code draaien. Ze staan geordend van lichtste naar zwaarste in de structuur die ze afdwingen.

Superpowers

Superpowers is de lichtste van de drie. Dit is degene die ik dagelijks gebruik, en die we het meest in detail zullen behandelen.

Wat is Superpowers?

Superpowers is een Claude Code-plugin van Jesse Vincent (obra/superpowers, MIT-licentie), met ongeveer 194k sterren op GitHub. 

Het levert een set skills mee. Een Claude-skill is, in Claude Code, een benoemd instructiebestand dat de agent on demand laadt om een specifieke workflow te volgen. Superpowers levert skills die Claude Code in de spec-driven loop houden in plaats van het direct naar code te laten springen.

De projectpagina van Superpowers op GitHub.

Hoe installeer je Superpowers

Installeer het via de officiële plugin-marktplaats van Claude Code:

/plugin install superpowers@claude-plugins-official

Een SessionStart-hook laadt automatisch de using-superpowers-skill, zodat de workflow actief is zodra je begint te typen. (Claude code hooks zijn scripts die de agent draait bij een specifieke lifecycle-event.) Er is niets per project te koppelen.

De Superpowers-workflow

Daarna beheren vier skills je dagelijkse werk:

Een subagent is een aparte Claude Code-instantie die de ouder dispatcht om gefocust werk te doen in een eigen contextvenster. De reviewersubagents in de tabel hierboven draaien als subagents, zodat ze de code koud lezen, zonder de framing van de ouder.

Hoe gebruik je Superpowers

Je roept de vier skills aan door in gewone taal te beschrijven wat je wilt. De brainstorming-skill hoort "laten we deze nieuwe feature bespreken" en start uit zichzelf het specgesprek. De andere skills triggeren op dezelfde manier.

De vier Superpowers-skills op volgorde, met de twee menselijke reviewmomenten tussen brainstorming en writing-plans.

De walkthrough hieronder gebruikt dezelfde workout-shape-verification-feature uit de spec hierboven.

Fase 1: brainstorm naar spec

Ik open Claude Code en typ:

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

De brainstorming-skill neemt het over en stelt een stuk of tien vragen terug, waaronder:

• Wat telt als de juiste "vorm"
• Welke datastromen te combineren
• Wat te doen met sessies die qua vorm goed lijken maar op een oude drempel falen
• Of de wijziging ook voor Run en Ride moet gelden

Hier vallen twee menselijke reviewmomenten. De eerste is de designreview, waarin ik bevestig dat de antwoorden die ik gaf kloppen met wat ik wil. De tweede is de specreview. Ik lees het bestand dat Claude heeft geschreven en keur het goed voordat er planwerk begint.

Fase 2: spec naar plan

Ik draai de writing-plans-skill. Die leest de goedgekeurde spec en schrijft een planbestand met vier delen:

• Een definitie van wat ‘Klaar’ betekent
• Een file map van aangeraakte bestanden
• Een user journey door het demopad
• Een genummerde takenlijst met checkbox-substappen. 

Ik beoordeel het plan, geef tegengas bij taken die onlogisch geordend of te grof lijken, en keur goed.

Fase 3: plan naar code

Ik draai subagent-driven-development. Vanaf dit punt loopt de lus zonder mij. Voor elke taak in het plan doet de skill:

1. Schrijft een falende test
2. Schrijft de code om die te laten slagen
3. Refactort
4. Start een codereview-subagent die de diff koud leest

Als de reviewer een issue markeert, fixt de lus dat vóór de volgende taak. Er is geen menselijk reviewmoment binnen deze fase. De reviews die hier tellen, zijn de twee fases ervoor.

Fase 4: full-diff review

Zodra het plan klaar is, draai ik requesting-code-review. Een frisse subagent leest de hele diff tegen de spec en het plan, en plaatst een review. Ik neem de suggesties over vóór de merge.

Wanneer een taak in het plan een tegenspraak met de spec onthult, stopt de lus en vraagt om input. Ik kan de spec bewerken (of Claude dat laten doen) en de getroffen taken opnieuw genereren. De andere optie is een eenmalige correctie in de taak zelf. Superpowers werkt specfouten niet stilzwijgend weg.

Echte specs en plannen op schijf

Hier is de spec voor de workout-shape-verification-feature, geopend in een editor:

Het specbestand zoals het op schijf belandt nadat de brainstorming-skill het heeft geschreven.

De header bevat de velden Created, Status en Supersedes die de brainstorming-skill standaard schrijft. Daarna volgt de sectie Problem. Het is geen code. Het bestand gaat door voorbij de screenshot met secties voor de voorgestelde oplossing en de beperkingen op wat de wijziging wel en niet mag raken.

Het bijpassende plan opent met de User Journey:

Het planbestand dat de writing-plans-skill produceert op basis van de goedgekeurde spec.

De journey loopt het demopad stap voor stap door, en noemt de exacte commando’s, bestanden en argumenten bij elke stap. De genummerde taken die volgen, vertalen elke stap naar checkbox-substappen waar de subagent-driven-development-skill doorheen kan werken.

De twee documenten horen zo bij elkaar:

Spec en plan naast elkaar. De spec beantwoordt wat er verandert en waarom. Het plan beantwoordt in welke stappen.

Voor grotere specs en plannen voeg ik één stap toe die niet in de officiële lus zit: een red-team-pass. Voor ik teken, laat ik één of meerdere Opus-subagents de spec koud lezen, op zoek naar gaten vanuit verschillende hoeken. Dat is een persoonlijke gewoonte, geen Superpowers-functie. Het heeft genoeg foute aannames onderschept dat ik het blijf doen.

Wanneer Superpowers de verkeerde keuze is

Superpowers past bij solowerk aan één repo. Het werkt het best als de hele codebase in één Claude Code-sessie past, en je daadwerkelijk een spec van 2 pagina’s leest. De gedetailleerde vergelijking staat in Hoe kies je tussen de drie verderop. De korte versie: Superpowers worstelt met features over meerdere repo’s en met werk dat duidelijke rol­scheiding nodig heeft.

Een developer signaleerde een vierde faalscenario in een publieke klacht over de plugin: “Zelfs de kleinste taken duren eeuwig, met Claude die subagents opstart en plannen schrijft die compleet overkill zijn. Een beetje CSS aanpassen duurt nu eeuwig.”

De oplossing is om Superpowers over te slaan voor piepkleine wijzigingen. De skills activeren alleen op de brainstorming-trigger. Een CSS-edit van één regel kan door Claude Code gaan zonder ooit de speclus te starten. De echte faalmodus daar is de workflow te vaak toepassen op werk dat geen spec nodig heeft.

GitHub Spec Kit

Spec Kit is de keuze wanneer de spec langer moet meegaan dan één Claude Code-sessie. Het is ook de juiste keuze wanneer mensen die Claude Code nooit openen de spec moeten kunnen lezen.

Wat is de GitHub spec-kit?

Spec Kit is een GitHub-project (github/spec-kit, MIT-licentie), onderhouden door GitHub zelf, met meer dan 100k sterren. Het levert een CLI plus een workflow die op dezelfde manier draait bij elke grote AI-codeagent. Claude Code, Cursor, Aider, Cline en Roo Code worden allemaal ondersteund. Het agent-neutrale ontwerp is wat de spec buiten Claude Code laat leven.

De projectpagina van Spec Kit op GitHub.

Hoe installeer je de GitHub spec-kit

Er is nog geen officiële PyPI-package, dus installeer de CLI vanaf de Git-tag met uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Vervang vX.Y.Z door de huidige releasetag. Het pakket heet specify-cli, en het commando dat het registreert is specify.

De GitHub spec-kit-workflow

De workflow loopt via negen slashcommando’s die de CLI toevoegt aan de slash-commandlijst van je agent. Zes zijn kern voor de lus, drie zijn optioneel voor gevallen die de kernlus niet dekt.

De scheider tussen commandogroep en werkwoord is een punt, geen dubbele punt: /speckit.specify, niet /speckit:specify. 

De negen Spec Kit-slashcommando’s: zes kerncommando’s op de pipeline, drie optionele commando’s eronder.

De artefacten die deze commando’s produceren zijn dezelfde spec en hetzelfde plan die je in de Superpowers-sectie zag, ook weggeschreven op schijf en gevolgd door Git. Het verschil is de portabiliteit: Spec Kits artefacten zijn ontworpen om met elke AI-codeagent te werken, niet alleen Claude Code, en de workflow is ingericht op stakeholderreview via GitHub-pull requests in plaats van als bijproduct van de loop van één tool.

Wanneer gebruik je GitHub spec-kit

Op een soloproject heb je Spec Kit waarschijnlijk niet nodig. Gebruik het wanneer:

• Het project groter wordt dan één persoon
• Je spec beoordeeld moet worden door mensen die Claude Code nooit openen
• Je voor een deel van het werk een niet-Claude-Code-agent draait
• Je een specformaat wilt dat buiten een enkele tool leeft en maanden later nog leesbaar is

De BMAD-methode

Waar Spec Kit artefacten organiseert, organiseert BMAD mensen. Het splitst de spec-naar-code-workflow in vier fases, elk uitgevoerd door een benoemde rol-agent.

Wat is BMAD?

BMAD-METHOD (bmad-code-org/BMAD-METHOD, MIT-licentie, ongeveer 47k sterren) is op versie 6. Het acroniem staat in de eigen documentatie voor "Breakthrough Method for Agile AI-Driven Development." Het draait bovenop Claude Code en andere agents, en installeert als een module-ecosysteem. De standaardinstallatie geeft je een coremodule met zes rol-agents, vier workflowfases en 34 of meer benoemde workflows.

De projectpagina van BMAD-METHOD op GitHub.

Hoe installeer je BMAD

Installeer BMAD met Node:

npx bmad-method install

De zes rol-agents zijn promptpersonae die de gebruiker bij naam activeert vanuit de agenthost. In Claude Code betekent dat het intypen van het activatiecommando dat BMAD installeert. Check de README voor de exacte syntax, die tussen releases verschuift. 

Kennismaking met de BMAD-collega-agents en artefacten

Eenmaal geactiveerd neemt de agent de instructies, tone of voice en outputs van die rol over totdat je van persona wisselt. De zes zijn:

• Mary, de Analist
• Paige, de Technisch Schrijver
• John, de Productmanager
• Sally, de UX-designer
• Winston, de Architect
• Amelia, de Developer

Twee rollen die je zou verwachten ontbreken in v6: er is geen Scrum Master-agent en geen losse QA-agent. Sprintplanning en storyvoorbereiding vallen bij de Developer-agent, en QA-testgeneratie is een workflow die de Developer triggert.

De set artefacten is zwaarder dan één enkele spec. Je krijgt:

• een productbrief
• een PRD (Product Requirements Document)
• een UX-spec
• een architectuurdocument
• epics, opgesplitst in user stories (wat gebruikers kunnen zodra het werk live is)

Het PRD en het architectuurdocument spelen samen dezelfde rol als de Superpowers-spec. De splitsing verdeelt ze over twee rol-agents en in een formeler format. De set als geheel dekt een volledige software-ontwikkelcyclus, waarbij elke feature context erft van de laag erboven.

De BMAD-workflow

De v6-workflow draait in vier fases.

De vier BMAD-fases en de rol-agent die elke fase draait. Het Quick Flow-spoor slaat de eerste drie fases over voor klein werk.

Fase 1, analyse, is optioneel. Mary (Analist) en Paige (Tech Writer) doen onderzoek en produceren een productbrief. Sla de fase over als je al weet wat je gaat bouwen.

Fase 2, planning, is verplicht. John (PM) schrijft het PRD. Sally (UX-designer) voegt een UX-spec toe wanneer de feature een UI heeft.

Fase 3, solutioning, is Winston’s fase. De Architect schetst eerst de architectuur, daarna breekt John requirements op in epics en stories. Stories ná de architectuur plaatsen is een v6-keuze die ze afstemt op echte implementatiegrenzen. Winston draait vervolgens een implementatiegereedheidscheck die eindigt in een PASS-, CONCERNS- of FAIL-oordeel.

Fase 4, implementatie, is waar Amelia (Developer) story voor story werkt: story aanmaken, bouwen en codereviewen. Zodra een volledige epic klaar is, triggert ze een QA-testgeneratieworkflow over de hele epic. Dit is de fase waarin Claude Code het daadwerkelijke coderen doet, werkend als Amelia.

Voor klein, goed afgebakend werk levert BMAD een "Quick Flow"-spoor dat Amelia direct activeert en de eerste drie fases overslaat. Het activatiecommando staat in de BMAD-README (de exacte syntax verschuift tussen releases). Quick Flow produceert geen PRD en geen architectuurdocument, alleen een korte story en de code die daaraan voldoet. Dit is het antwoord op de “dit is overkill voor een knopwijziging”-tegenwerping.

Wanneer de spec halverwege implementatie toch fout blijkt, loopt BMAD terug via Winston’s oordeel in Fase 3. Een FAIL stuurt je terug naar Fase 2 om het PRD te herschrijven. Een CONCERNS gaat door met Winston’s genoteerde risico’s aan de story gekoppeld. De splitsing laat je doorwerken bij kleine inconsistenties en hard stoppen bij grote.

Wanneer de complexiteit loont

BMAD loont bij langlopende projecten met echte gebruikers. Het past ook bij teams met meerdere developers, waarbij werk wordt overgedragen tussen mensen. De scheiding in fases en rollen moet meer tijd besparen dan ze kost.

Het past niet bij een eenpersoons sideproject. Bij solowerk is de splitsing in vier fases en zes agents vooral overhead. Er is geen tweede persoon in het team voor wie rolscheiding uitmaakt.

Hoe kies je tussen de frameworks

Drie regels bepalen de keuze.

• Gebruik Spec Kit als de spec gelezen moet worden door mensen die Claude Code nooit openen, of als deze in Git moet leven als langeterminartefact.
• Als meerdere mensen in duidelijke rollen werken, of er een echte PM-achtige stakeholder in de loop zit, gebruik dan BMAD.
• Anders gebruik je Superpowers.

Drie vragen over je project, vier frameworkkeuzes aan de overkant.

Er is een vierde optie die de beslisboom noemt: Spec Kit combineren met Superpowers. Gebruik Spec Kit voor de specfase zodat de artefacten in Git leven voor review door meerdere teams. Wijs daarna met één regel config de subagent-driven-development-skill van Superpowers naar het Spec Kit-planbestand. Je krijgt de duurzame spec van Spec Kit naast de strakke implementatielus van Superpowers.

Conclusie

Spec-driven development is drie documenten op rij. De spec zegt wat je bouwt, het plan zegt in welke stappen, en de code volgt het plan. Een menselijke review zit tussen elk paar.

Loop de beslisboom hierboven door om een framework te kiezen, wat voor de meeste lezers op Superpowers zal uitkomen. Installeer het en kies één feature die je anders vibe-coded zou hebben, iets dat 3 tot 5 bestanden raakt. Draai het end-to-end door brainstorm, spec, plan en uitvoering. Eén echte run leert de workflow beter dan welke beschrijving ook.

Wil je eerst de basis van Claude Code opfrissen, dan heeft DataCamp een praktische Claude Code-tutorial, een best practices-gids over planmodus, CLAUDE.md en TDD, en een deep dive in de planmodus zelf.