Specificatiegestuurde ontwikkeling: de goede punten - en wat we na drie maanden hebben geleerd
Na drie maanden hadden we een duidelijker beeld van wanneer de extra structuur hielp en wanneer ze in de weg zat.
Een van onze engineers was een gegevensmigratie aan het voorbereiden en besloot om spec-driven development (SDD) te gebruiken om het werk te plannen. SDD was bedoeld om hen te helpen hiaten vroegtijdig te ontdekken, de aanpak gemakkelijker te beoordelen en de medewerker een duidelijke richting te geven. Het resulterende plan was gedetailleerd en zag er op papier behoorlijk redelijk uit. Het structureerde het werk als volgt:
Probleem → Onderzoek → Specificatie → Beoordeling → Implementatie → Verificatie
Naarmate de implementatie vorderde, realiseerde de engineer zich dat twee taken elkaar konden inhalen en dubbele aangepaste velden konden creëren. De aanpak maakte de code ook steeds complexer en moeilijker te volgen. Gelukkig ontdekten ze het probleem, stopten ze met de implementatie, schreven ze een ontwerpdocument van één pagina en tagden ze een paar collega's voor inbreng. Samen werkten ze het ontwerp uit en vonden ze een veiligere aanpak.
De oorspronkelijke specificatie deed wat we vroegen: ze hield het project in de oorspronkelijke richting. Het probleem was dat de richting verkeerd was. Dankzij een gedetailleerde specificatie was het gemakkelijk om het project voort te zetten, zelfs toen het uitgangspunt wankel was. De medewerker kon dat idee sneller uitbouwen dan mensen konden stoppen en het in twijfel konden trekken.
Dat project toonde één risico van extra structuur: één agent kon dezelfde foute veronderstelling uit de specificatie overnemen in de code en de tests. De specificatie, de code en de tests stemden met elkaar overeen, maar dat betekende niet dat de onderliggende veronderstelling juist was. Voor risicovollere beslissingen moest iemand anders nog steeds terugkeren naar het oorspronkelijke doel en zoeken naar manieren waarop de implementatie het zou kunnen schenden.
Toch namen agenten werk aan dat langer duurde dan één sessie, en een prompt was vaak niet genoeg om vast te houden aan wat het project probeerde te doen of waarom. Dat bracht ons ertoe om /spec-driven te bouwen, een workflow-harnas met een specificatie in het middelpunt. De spec hield de richting van het project beschikbaar voor de volgende sessie. Scripts brachten context in en voerden controles uit. Wanneer een run een ontbrekende regel, controle of context blootlegde, konden we deze toevoegen aan de workflow, zodat latere agenten dezelfde leemte niet opnieuw hoefden te ontdekken.
Er is nog steeds behoorlijk wat onenigheid over de vraag of de extra structuur van SDD de moeite waard is. Microsoft en AWS promoten SDD, terwijl Thoughtworks het beschrijft als opkomend en omstreden en praktijkmensen gemengde ervaringen melden. Critici waarschuwen dat SDD meer Markdown kan produceren dan engineers kunnen onderhouden, een gedetailleerde specificatie kan omzetten in code geschreven in proza, of een andere beschrijving van het systeem kan achterlaten die afwijkt van de code.[1][2][3]
Na drie maanden echt gebruik leerden we dat de belangrijke vraag niet was of we SDD moesten gebruiken. Het was wat de medewerker miste bij dat project. Soms was het antwoord een specificatie. Soms was het een beter voorbeeld, een geautomatiseerde controle of een engineer die het gebied kende.
Waarom we /spec-driven hebben gebouwd
Sommige engineers bij Asana hadden GitHub Spec Kit en OpenSpec al geprobeerd, maar geen van beide werd onderdeel van hun reguliere workflow. We wilden een versie die we konden aanpassen naarmate we leerden en die we konden koppelen aan het ontwikkelingsproces van Asana.
De ingebouwde planmodus kon al de codebase onderzoeken en een nuttig implementatieplan opstellen vóór er wijzigingen werden aangebracht. SDD voegde meer structuur toe aan dat plan: het hield het probleem, de belangrijkste beslissingen en de acceptatiecriteria zichtbaar tijdens de implementatie en verificatie.
Vóór de implementatie gaf /spec-driven zijn inzicht in het probleem weer en stelde het de vragen die het plan zouden kunnen veranderen. Dat gaf de engineer de kans om de richting te corrigeren voordat er code was om te herschrijven.
We hebben die status in de repository opgeslagen, zodat latere sessies niet hoefden te raden wat er was gebeurd. We wilden dat de regels van de workflow deterministisch waren, dus scripts verzorgden de administratie en controles. Het model behandelde de onderdelen die baat hadden bij oordeel: vragen stellen, afwegingen maken en beslissingen toelichten.
De workflow bevatte verschillende opdrachten. Engineers gebruikten /spec-driven spec om open vragen te behandelen en een specificatie en implementatieplan op te stellen. Na het beoordelen van het plan gebruikten ze /spec-driven ship om het te implementeren, het resultaat te verifiëren en het werk voor te bereiden op beoordeling. Een statusmachine hield het project bij terwijl het deze opdrachten doorliep, zodat latere sessies wisten wat er was gebeurd en wat er daarna kwam.
Vanaf het begin wilden we dat /spec-driven meer zou zijn dan alleen een manier om specificaties te schrijven en uit te voeren. We wilden ook dat het agentic-workflows zou organiseren. Het rangschikt taken op afhankelijkheid en houdt overlappende bestandswijzigingen in aparte uitvoeringsrondes. Het stuurt onafhankelijk werk parallel naar meerdere agents en gebruikt vervolgens de resultaten om te beslissen wat er vervolgens kan worden uitgevoerd.
Het voelt als een GPS voor het werk: op elk moment is het duidelijk wat de volgende stap is en waar de echte beslissingen liggen, dus het is moeilijk om vast te lopen.”
Asana-engineers gebruikten /spec-driven zowel op spec-first- als op spec-anchored-manieren. Met spec-first gebruikten ze een spec om een richting te kiezen en stopten ze vervolgens met het bijwerken ervan. Met spec-anchored hielden ze de specificatie actueel naarmate het werk veranderde. Engineers schreven ook onafhankelijke specificaties voor delen van een grotere inzet, zodat één persoon de workflow kon gebruiken zonder het hele team te vragen om deze aan te nemen.
Wanneer /spec-driven het extra werk waard is
De extra structuur loonde het meest wanneer belangrijke context moest worden behouden tijdens sessies, handoffs of veel gerelateerde taken. Engineers konden bekijken hoe het plan was veranderd, en de richting van het project bleef beschikbaar wanneer het werk werd overgedragen naar een andere agentsessie of persoon. Twee productinspanningen hielden levende specificaties bij gedurende ongeveer twee tot drie maanden: de ene bouwde een belangrijke nieuwe functie, de andere rolde subtakendata door naar bovenliggende taken.
Ik heb net een vrij groot initiatief afgerond met spec-driven en ik denk dat het me echt heeft geholpen! Ik heb ongeveer twee dagen aan het plan gewerkt en daarna heb ik in drie dagen al het engineeringwerk gedaan en samengevoegd.”
Specificaties maakten overdrachten gemakkelijker. Iemand die een gepauzeerd project oppakte, kon zien wat het team probeerde te doen, waarom het die vorm had aangenomen en wat er nog te doen was. Ze hoefden het project niet te reconstrueren aan de hand van commits en gesprekken.
Engineers gebruikten ook /spec-driven om grote batches werk uitgevoerd door agents te coördineren. In de beheerdersconsole van Asana, waar IT-teams bij klantbedrijven de beveiligings-, toegangs-, integratie- en deelininstellingen voor de hele organisatie beheren, gebruikten engineers deze om 66 instellingen naar gedeelde raamwerken te verplaatsen. Het verplaatsen van die instellingen vereiste ongeveer 150 migraties over verschillende raamwerken van de Beheerdersconsole. Elke migratie werd een Asana-ticket voor een cloudagent, en engineers voerden ze uit in parallelle batches, waarbij ze de resterende tickets bijwerkten op basis van eerdere resultaten.
Het team dat deze inzet uitvoerde, meldde dat 91% van de migraties na beoordeling geen herziening nodig had en dat de totale inzet meer dan een maand eerder dan het oorspronkelijke plan werd opgeleverd.
Een andere grote migratie had slechts een korte prompt nodig. Het verschil was hoe duidelijk de codebase al was. Het bevatte voorbeelden die agenten konden volgen en controles waarmee het resultaat kon worden geverifieerd. De agenten van de Beheerdersconsole konden niet elke eis uit de code achterhalen, dus het werk had meer structuur nodig.
/spec-driven hielp ook bij snelle prototyping. Engineers konden snel net genoeg van de open productvragen beantwoorden om een werkende end-to-end ervaring te bouwen. PM's en ontwerpers konden een prototype uitproberen voordat engineers investeerden in productieverbetering. Als engineers besloten de code te behouden, moest deze meestal aanzienlijk worden opgeschoond voordat deze kon worden samengevoegd. Tegen die tijd had het prototype al aangetoond of het idee de moeite waard was om verder uit te werken.
Wat de eerste cijfers lieten zien
We moedigden iedereen aan om /spec-driven eenmaal te proberen, maar eisten geen voortgezet gebruik. Ongeveer de helft van de ingenieurs heeft het geprobeerd. In de laatste maand varieerde het wekelijkse gebruik van 30 tot 50 engineers. Onder de ingebouwde en door Asana ontwikkelde agentvaardigheden die engineers rechtstreeks aanriepen, stond /spec-driven op de derde plaats. Het voortdurende gebruik was bemoedigend, maar het vertelde ons niet hoe /spec-driven de oplevering beïnvloedde.
De snelheid van engineering is berucht moeilijk te meten. Pull-aanvragen en toevoegingen aan implementatiecode zijn onvolmaakte indicatoren voor productiviteit, maar we geloven dat ze vaak directioneel nuttige maatstaven zijn. Voor de vergelijking van de snelheid hebben we gekeken naar zeven engineers en 524 samengevoegde pull-aanvragen over een periode van vier maanden. We vergeleken het werk voor en na het eerste duidelijke gebruik van /spec-driven door elke engineer en sloten specificaties, plannen en andere workflowartefacten uit. Voor de vergelijking van terugdraaien classificeerden we een pull-aanvraag als /spec-driven wanneer deze de projectbestanden van de workflow wijzigde.
Pull-aanvragen per week stegen met 38% en toevoegingen van implementatiecode stegen met 2,66×. Eén korte periode met een ongewoon hoog volume beïnvloedde het resultaat van de toevoegingen. Zelfs zonder dit waren de toevoegingen nog steeds 66% hoger. Het percentage expliciete terugdraaiingen was ook iets lager: 1,2% voor /spec-gestuurd werk, vergeleken met 1,66% voor andere pull-aanvragen.
Meer code is niet noodzakelijk een goed resultaat. Een medewerker kan een grote implementatie produceren wanneer een kleinere voldoende zou zijn, dus de toename van code-toevoegingen zou kunnen duiden op onnodig grote oplossingen in plaats van meer voltooid werk. De normale beoordeling gaf ons één controle op die foutmodus. We vertrouwden erop dat reviewers implementaties zouden signaleren die groter of ingewikkelder waren dan het probleem vereiste, en deze wijzigingen werden nog steeds goedgekeurd. Dat gaf ons enig vertrouwen dat te grote implementaties niet de hele stijging veroorzaakten.
Deze vergelijkingen werden niet gecontroleerd en we konden het effect van /spec-driven niet scheiden van de projectmix of bredere verbeteringen in de tooling van agenten. Zelfs met die beperkingen werden we aangemoedigd door de resultaten.
Wat er nog moet gebeuren
Het beoordelen van de documenten kan een knelpunt worden
Het maken van een specificeerde tussen de 30 minuten en enkele dagen, afhankelijk van de bekendheid van de engineer met het gebied en de complexiteit en het risico van het project. Engineers konden /spec-driven gebruiken om een agent snel een spec te laten opstellen, maar het beoordelen ervan kostte nog steeds tijd.
Bij één inzet besteedde een engineer uren aan het beoordelen van een pull request met research.md, een werkbestand waarin de agent vastlegde wat hij had geleerd van de codebase, de documentatie en eerdere beslissingen voordat hij de specificatie opstelde. Sommige van die bevindingen waren vaag, onnauwkeurig of enigszins onjuist.
Uit die beoordeling bleek dat we het er niet over eens waren of deze bestanden tijdelijke werknotities waren of documentatie waarop toekomstige engineers zouden moeten vertrouwen. Sommige engineers hechtten waarde aan het verslag van hoe een beslissing werd genomen. Anderen maakten zich zorgen dat het inchecken van onvolmaakt onderzoek het er gezaghebbend uit zou laten zien.
Bij één infrastructuurteam werd de beoordeling van specificaties een nieuwe blokkade vóór de implementatie.
Ik vond de opdrachten en de workflow veel ingewikkelder en tijdrovender dan gewoon een plan maken en vervolgens uitvoeren.”
De meeste beoordelaars wilden geen lange specificatie lezen en vervolgens ook nog de code beoordelen. Tegen de tijd dat het werk een pull-aanvraag bereikte, moest de overdracht de beslissing samenvatten, waarom we die hadden genomen, wat er riskant uitzag en hoe we het resultaat hadden gecontroleerd. Als de richting zelf moest worden beoordeeld, moesten we daar eerder om vragen, toen het nog eenvoudig te veranderen was.
Een nuttige specificatie verandert naarmate het project vordert
Engineers bleven leren terwijl ze het plan implementeerden. Het bijwerken van de specificatie met wat ze hadden geleerd, vergde inzet. De details ervan hielpen tijdens de implementatie door te laten zien wat de agent dacht dat hij aan het bouwen was. Achteraf herhaalde een groot deel van die details de code.
We denken nu dat een werkende specificatie moet groeien zolang het project onzeker is en moet krimpen zodra de code de implementatie kan uitleggen. Wat overblijft, moet de volgende lezer helpen het ontwerp, de belangrijke beslissingen, de beperkingen en de onopgeloste risico's te begrijpen.
Voltooide specificaties roepen een gerelateerde vraag op: wat moet er met hen gebeuren? We hebben te lang gewacht om die vraag te beantwoorden. Als we ze in de monorepo laten staan, zijn ze gemakkelijk te vinden, maar laten we ook documenten achter waarvoor niemand verantwoordelijk is. We verplaatsen ze naar een apart archief. We hebben nog steeds een kortere overdracht nodig die bewaart wat later belangrijk is. Als een document meer werk creëerde dan het bespaarde, hielp het niet.
Feedbacklussen inbouwen in het harnas
Soms was het antwoord niet een ander document, maar een wijziging in het systeem rond de agent. Een voorbeeld was een bug in de manier waarop /spec-driven Markdown las: kopteksten en selectievakjes in voorbeelden konden worden aangezien voor daadwerkelijke mijlpalen of onvoltooide taken. Nadat we de bug hadden geregistreerd, hebben we de rest van /spec-driven doorzocht en verschillende opdrachten gevonden met hun eigen kleine Markdown-parser en dezelfde blinde vlek. We hebben ze vervangen door één gedeelde parser, regressietests en een architectuurcontrole toegevoegd en de oplossing in de omgeving geplaatst. OpenAI beschrijft een gerelateerde aanpak als harness engineering: belangrijke kennis plaatsen waar agenten deze kunnen vinden, regels afdwingbaar maken en fouten gebruiken om de omgeving rond de agent te verbeteren.
Andere lessen konden niet worden omgezet in een test of architectuurregel. We hebben terugkerende fouten samengevat in richtlijnen. Aangezien /spec-driven gebruikers door een voorspelbare workflow leidde, konden we elke les tonen wanneer de agent de relevante stap bereikte. Engineers beslisten nog steeds welke lessen van toepassing waren buiten het oorspronkelijke project.
We hebben de richtlijnen getest op acht historische pull-aanvragen, samen met synthetische gevallen die zijn ontworpen om irrelevant advies op te sporen. In een vervolg hebben we drie van die historische taken getest met korte, gemiddelde en gedetailleerde prompts, voor in totaal negen vergelijkingen. De begeleiding bracht in acht van de negen vergelijkingen een nuttige extra vraag of planningsgrens aan het licht. Een aparte test omvatte nog eens drie historische taken. Het verbeterde duidelijk twee plannen; in het derde had de agent zonder begeleiding het probleem al opgemerkt.
De meest nuttige begeleiding stelde vragen over gedragsveranderingen, betrokken consumenten en varianten, en contracten tussen API's, schema's of parsers. De evaluaties hadden alleen betrekking op vragen en plannen. We hebben niet gemeten of de richtlijnen de implementatie hebben versneld. Beperkte begeleiding werd ook sneller verouderd en kwam soms naar voren in niet-gerelateerd werk.
Het onderhouden van de richtlijnen en evaluaties kostte meer werk dan het bouwen van de eerste versie. We konden de landmijn in kaart brengen met richtlijnen, deze opruimen door het onderliggende systeem te repareren, of het risico accepteren dat een medewerker of beoordelaar deze opnieuw zou moeten vinden. We brachten het meestal eerst in kaart, omdat dat goedkoper was. Het repareren van de onderliggende API, test, documentatie of het voorbeeld kostte meer werk, maar kwam iedereen ten goede en maakte de begeleiding overbodig.
Hoe we /spec-driven nu zouden benaderen
We wilden voorkomen dat engineers dezelfde prompts herhaalden en het project opnieuw uitlegden, zonder de nuttige wrijving weg te nemen. De agent moest nog steeds stoppen wanneer hij een belangrijke vraag had, er bewijs ontbrak of de volgende stap menselijk oordeel vereiste. We kwamen met een paar praktische richtlijnen:
Voor de meeste kleine, lokale wijzigingen is een gesprek of een kort plan voldoende.
Gebruik spec-first om het eens te worden over een richting. Houd de specificatie verankerd wanneer beslissingen later in sessies of handoffs moeten worden overgenomen.
Zet niet elk ontbrekend stuk in de specificatie. Het harness moet context bieden en controles uitvoeren; architectonisch oordeel heeft nog steeds menselijke beoordeling nodig.
Als een specificatie de moeite waard is om te behouden, schrijf deze dan voor de volgende lezer. Zorg dat beslissingen en risico's makkelijk te vinden zijn, link naar bewijs in plaats van het te kopiëren, en beslis wat er met de specificatie moet gebeuren wanneer het project eindigt.
Waar we vanaf hier naartoe gaan
Na drie maanden gebruiken engineers nog steeds /spec-driven wanneer het werk zich over meerdere sessies uitstrekt, van de ene persoon naar de andere gaat of wordt opgesplitst in veel verwante taken. Ze hebben het gebruikt om projecten van meerdere maanden in beweging te houden en grote hoeveelheden werk van agenten te organiseren. Dat is een goed resultaat voor een intern experiment.
Toen we /spec-driven uitbreidden om meer soorten werk te ondersteunen, losten sommige nieuwe functies echte problemen voor bepaalde teams op, maar maakten ze de workflow voor iedereen complexer. In de volgende versie willen we toewerken naar een kleinere, meer gerichte kern.
Mensen hebben sterke meningen over SDD en harness engineering. We leerden meer door ze uit te proberen op echt werk dan door over elk van beide te debatteren. Voordat we meer processen toevoegen, vragen we nu wat de agent mist in dat project. Begin klein, kijk waar de workflow helpt of in de weg staat, en pas vervolgens aan op basis van wat je leert.
[1] Birgitta Böckeler, “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl,” oktober 2025.
[2] François Zaninotto, “Spec-Driven Development: The Waterfall Strikes Back,” november 2025.
[3] Gabriella Gonzalez, “A sufficiently detailed spec is code,” maart 2026.
Over de auteur
Walter Li is Software Engineer bij het Core Storage Infrastructure-team van Asana, en Rohan Batra is Software Engineer bij het Backend Frameworks-team. Beiden hebben een paar maanden in het Agent Success Tiger Team gezeten, waar ze de ontwikkeling en evaluatie van de /spec-driven workflow hebben geleid die in dit bericht wordt beschreven.
Bedankjes aan het team
Speciale dank aan Leo Zhang, Karol Krupa, Gordie Levitsky en Mitch Conquer voor hun hulp bij het vormgeven en ontwikkelen van /spec-driven en voor het feit dat ze er vroegtijdig mee aan de slag zijn gegaan.