Spec-driven development is werken met een geschreven specificatie die je afspreekt voordat een AI-agent code schrijft, en het resultaat beoordelen op die spec in plaats van op een prompt van één regel. Het klinkt als een terugkeer naar waterval. In de praktijk is de spec één pagina, staat hij er in een paar minuten, en haalt hij het duurste gesprek in softwareontwikkeling, "zo bedoelde ik het niet", naar het moment waarop het het goedkoopst is.
Waarom een agent het harder nodig heeft dan een mens
Een developer die een ticket niet begrijpt, vraagt het. Een AI-agent vult het gat met de meest aannemelijke lezing en gaat door, snel en vol overtuiging. Het resultaat ziet er af uit, slaagt voor de tests die hij zelf schreef, en is fout op een manier die je pas in de review ontdekt. Hoe sneller de agent, hoe meer verkeerde code je reviewt.
Wat er in de spec hoort
Na een paar duizend runs zijn dit de onderdelen die hun plek verdienen:
- Functionele interpretatie: wat het verzoek betekent, in de woorden van wie het vroeg.
- Technische aanpak: hoe het gebouwd wordt, en wat er hergebruikt wordt in plaats van opnieuw geschreven.
- Betrokken componenten: echte bestandspaden en wat ervan afhangt, niet "de backend".
- Impact op datamodel en API: migraties en contractwijzigingen, omdat die moeilijk terug te draaien zijn.
- Risico's: wat er mis kan gaan, beveiliging voorop.
- Teststrategie: welke tests bewijzen dat het werkt.
- Open vragen: alles wat het verzoek onduidelijk laat, gevraagd in plaats van gegokt.
Een voorbeeld
Het verzoek: "Klanten moeten hun facturen als pdf kunnen downloaden." Een spec op basis van de codebase maakt daarvan een knop per factuur voor beheerders, een endpoint dat de template hergebruikt die de factuurmail al rendert, een eigenaarschapscontrole als belangrijkste risico, twee tests, en één open vraag: krijgen creditnota's de knop ook? Wie het vroeg, beantwoordt dat in één zin. Zonder spec was dat antwoord binnengekomen als reviewcommentaar op afgemaakte code.
Wie keurt goed, en wanneer
Wie eigenaar is van het resultaat: een tech lead bij een structurele wijziging, de product owner bij gedrag, de developer die om een kleine fix vroeg. Waar het om gaat: er start geen run voor de goedkeuring, en de goedkeuring hoort bij een specifieke versie van de spec, zodat de pull request precies kan aanwijzen wat er is afgesproken.
Fouten om te vermijden
- Specs schrijven zonder de code te lezen. "Betrokken componenten" die gegokt zijn, maken de hele spec een gok.
- Goedkeuren zonder te lezen. Een spec die niemand leest, is een tragere prompt.
- Specs zo lang als de code. Heeft een spec pagina's nodig, dan moet de taak worden opgesplitst.
- De spec weggooien na de merge. Het is het beste verslag van waarom de wijziging bestaat.
Zo werkt CodeLynq bij elke taak: de spec wordt geschreven op basis van je repositories, open vragen gaan naar een validatiechat, en de run wordt aan de goedgekeurde versie gehouden. Meer op de pagina spec-driven development, of zie hoe het zich verhoudt tot agents die de spec overslaan in CodeLynq vs Devin.