Schrijf een spec voordat je een AI-codeeragent aanstuurt

Een verzoek direct in een codeeragent typen voelt sneller dan eerst iets opschrijven, en bij een echt triviale taak is dat vaak ook zo. Het probleem begint bij alles wat meer dan één redelijke uitleg heeft: de agent kiest er een, bouwt daarnaartoe, en jij merkt pas dat het de verkeerde was als je de afgeronde code leest. Elke extra ronde daarna kost meer dan de paar minuten die een spec had gekost.

Een spec draait de volgorde om. Voordat er code wordt geschreven, schrijf je drie dingen in gewone taal op: wat het ding moet doen, voor wie het is en de klaar-wanneer-checks die bewijzen dat het werkt. Het is geen technisch document. Het lijkt meer op het briefje dat je zou achterlaten voor een capabele assistent die je nog nooit heeft ontmoet: genoeg detail zodat die niet hoeft te gokken bij de onderdelen die ertoe doen.

Het werkt om een eenvoudige reden. De agent vult de gaten in je verzoek niet meer aan met eigen aannames, omdat er minder gaten overblijven. En jij ontdekt niet meer achteraf, door de uitvoer van de agent te lezen, wat je eigenlijk wilde, want je had het al opgeschreven voordat je iets vroeg.

Dit is niet aan één tool gebonden. Claude Code, Codex, Copilot, Cursor en elke andere codeeragent werken in principe hetzelfde: instructies in gewone taal erin, code en commando's eruit. Een spec verandert wat erin gaat, en daarmee wat eruit komt, met welke agent je ook praat.

GitHub's Spec Kit is een open-sourcetoolkit, onderhouden in de eigen repository van GitHub onder de MIT-licentie, gebouwd om AI-codeeragents gestructureerde processen, herbruikbare sjablonen en vastgelegde uitkomsten te geven in plaats van losse gesprekken. Het installeert via een eigen opdrachtregeltool, en de README beschrijft het als een toolkit om aan de slag te gaan met spec-driven development, of met elk ander gestructureerd proces dat je een agent wilt laten volgen.

De kern van de spec-driven workflow loopt volgens de documentatie van het project langs een benoemde reeks van zes commando's: een legt de leidende principes van een project vast, een schrijft de spec zelf, een zet die spec om in een technisch plan, een splitst het plan in een geordende takenlijst, een voert de taken uit en schrijft de eigenlijke code, en een laatste controleert hoe dicht het resultaat bij de spec is gekomen. Het project raadt zelf aan deze een voor een uit te voeren, elk resultaat te bekijken voordat je verdergaat, en de stappen implementeren en convergeren te herhalen tot de convergentiestap meldt dat het werk geconvergeerd is, in plaats van de hele klus in één keer aan de agent over te laten.

De toolkit levert ook losse extensies die je bovenop de kernworkflow toevoegt, opnieuw volgens de eigen documentatie: een set commando's rond het beoordelen en oplossen van een specifieke bug, en een andere rond het doorlopen van onderzoek en definitie van een ruw idee voordat je besluit of je het wel gaat bouwen.

Over de agents waarmee het koppelt noemt de installatiedocumentatie van Spec Kit er een aantal via een integratiesleutel die je bij de installatie meegeeft, waaronder Claude Code en GitHub Copilot, en verwijst het naar aparte documentatie om verdere agents te koppelen. Beschouw elke lijst met specifieke agents, ook deze, als een momentopname: controleer de actuele documentatie van Spec Kit voordat je aanneemt dat een bepaalde tool vandaag wel of niet wordt ondersteund.

Voor iemand zonder programmeerachtergrond die één klein ding bouwt, kan de volledige Spec Kit-workflow meer plechtigheid zijn dan de taak vraagt. De spec in drie delen, als allereerste bericht getypt aan de agent die je al gebruikt, doet op zichzelf al het meeste werk, zonder dat je iets hoeft te installeren.

Plak de spec en laat de agent je verhelderende vragen stellen voordat die iets schrijft. Een capabele agent vraagt door als iets onduidelijk is, en een spec geeft die agent iets concreets om over te vragen in plaats van stilzwijgend te gokken en met veel zelfvertrouwen het verkeerde te bouwen.

Deze eenvoudige vorm van de gewoonte is overal bruikbaar. Dezelfde brief in drie delen werkt of je nu met Claude Code, Codex, Copilot, Cursor of een andere codeeragent praat, omdat niets ervan afhangt van een functie die bij één tool hoort. Het is een gewoonte die je opbouwt, geen plug-in die je installeert.

Voor één kleine build is een gewone spec in drie delen, rechtstreeks in de chat getypt, genoeg, en het gaat sneller dan iets installeren. De meeste voorbeelden in deze gids zijn precies voor dat geval geschreven.

Spec Kit begint de installatie terug te verdienen als je dit op hetzelfde project blijft herhalen, de principes automatisch wilt laten afdwingen bij elke nieuwe functie, of de structuur van de extensies voor bugfixes en ideebeoordeling wilt gebruiken in plaats van elke keer je eigen versie te verzinnen.

In beide gevallen is de eigenlijke vaardigheid dezelfde: vastleggen wat het doet, voor wie het is en hoe je weet dat het af is, voordat er ook maar één regel code wordt geschreven. De toolkit automatiseert alleen het consequent opschrijven daarvan, zodra de gewoonte zo vaak terugkomt dat automatiseren de moeite loont.