Specificatiegestuurde ontwikkeling in Jira
Specificatiegestuurde ontwikkeling betekent dat je eerst een gestructureerde specificatie schrijft voordat een agent iets bouwt, zodat de agent het juiste bouwt in plaats van iets samenstelt op basis van een aannemelijke gok. In Jira staat die specificatie in het werkitem waar je al aan werkt zodra het een duidelijke bedoeling heeft: resultaten, scope, beperkingen en acceptatiecriteria. Een werkitem kan de volledige specificatie voor één taak bevatten, of één deel van een grotere functiespecificatie die is opgesplitst over meerdere werkitems.
In deze handleiding leggen we uit wat een specificatie geschikt maakt voor gebruik door een agent, waarom het werkitem hiervoor de juiste plek is en hoe je de eerste specificatie kunt opstellen. Kort gezegd geeft specificatiegestuurde ontwikkeling in Jira je drie dingen:
Eén bron van waarheid waarop de agent voortbouwt en op basis waarvan de beoordelaar controleert
Acceptatiecriteria die bepalen wat voltooid betekent voor zowel de agent als de persoon
Minder herzieningen, omdat de intentie is vastgesteld voordat de agent een regel code schrijft
Wat is specificatiegestuurde ontwikkeling?
Specificatiegestuurde ontwikkeling is een praktijk waarbij je een gestructureerde specificatie schrijft die definieert wat moet worden gebouwd, hoe succes wordt gemeten, en de agent die implementeert, in plaats van te gissen op basis van een prompt van één regel.
De specificatie wordt de bron van waarheid. Deze stuurt het plan, de build en de controle aan, en in Jira vinden alle drie plaats op hetzelfde werkitem. Het idee dateert van vóór AI, omdat het voortkwam uit API-ontwerp en de praktijk van formele methoden, waarbij je gedrag definieert voordat je iets bouwt.
De definitie blijft verschuiven naarmate de tools volwassener worden, dus zie het als een werkwijze, niet als een vaste specificatie-indeling. Wat constant blijft, is de kernstap: definieer het werk voordat de agent het samenstelt.
Het verschil komt neer op wanneer je ambiguïteit oplost. Bij vibe coding wordt deze opgelost nadat de code is geschreven, bij specificatiegedreven ontwikkeling van tevoren.
Vibe coding: je stuurt de agent aan met prompts en accepteert wat hij teruggeeft, waardoor de scope, beperkingen en randgevallen waarvan de agent uitgaat, zichtbaar worden wanneer de code bestaat.
Specificatiegedreven: je legt eerst de intentie, beperkingen en acceptatiecriteria vast, zodat de agent bouwt volgens een definitie in plaats van een vermoeden, en bij de beoordeling controleer je het werkitem aan de hand van diezelfde definitie, op de plek waar het zich bevindt.
Voor code die moet blijven werken in een echte codebase, kan een agent zonder vaste context het ticket te letterlijk afhandelen en een belangrijke randvoorwaarde missen. Daar begint de herbewerking.
Prompts vervagen vaak twee dingen: de specificatie is wat je samenstelt, het plan is hoe dit gebeurt. Bij specificatiegedreven ontwikkeling wordt eerst de 'wat' bepaald en op basis daarvan de 'hoe'. Dat is de stap die de planmodus in AI-programmeertools vaak overslaat: de 'hoe' wordt rechtstreeks bepaald op basis van een prompt, meestal zonder overeengekomen onderliggende specificaties.
De planningsmodus kan fungeren als vervanging van een lichte specificatie, maar de 'hoe' wordt bepaald op basis van een prompt op dat moment, niet op basis van een overeengekomen specificatie die bij het werk behouden blijft.
Waarom specificaties belangrijk zijn voor programmeren met AI
Wanneer codegeneratie goedkoop wordt, is het lastige deel niet langer het opstellen van code. Wat lastig wordt, is juist definiëren wat moet worden opgesteld. Dat maakt de specificatie, niet de prompt, het door jou geproduceerde artefact met de grootste impact.
Een eenmalige prompt laat de hiaten over aan de agent, die deze opvult met aannames en code produceert die er goed uitziet, maar het verkeerde probleem oplost. Een specificatie dicht die hiaten eerst, zodat de agent toewerkt naar een definitie in plaats van naar een gok. In Jira is die specificatie het werkitem waarmee je team al plant, toewijst en beoordeelt.
Wat hoort in een specificatie waarmee een agent iets kan opstellen?
Een specificatie die klaar is voor agents beantwoordt de vragen die een goede engineer zou stellen voordat hij of zij aan de slag gaat. In Jira staan deze in de samenvatting, omschrijving, gekoppelde vereisten en acceptatiecriteria van het werkitem. Zes elementen zijn belangrijk:
Resultaten: wat de wijziging moet opleveren, in termen die een beoordelaar kan controleren.
Scope: wat erbij hoort en, net zo belangrijk, wat erbuiten valt.
Beperkingen: de limieten qua architectuur, beveiliging en prestaties die in acht moeten worden genomen.
Eerdere beslissingen: context die al is vastgesteld, zodat de agent die niet opnieuw ter discussie stelt.
Taakverdeling: het werk opgedeeld in stappen die klein genoeg zijn om te verifiëren.
Acceptatiecriteria: de testbare definitie van gereed waar de agent naartoe werkt en op basis waarvan wordt beoordeeld. In Jira staan ze in het werkitem, en een AI-codebeoordeling kan de wijziging hieraan toetsen voordat de wijziging een persoon bereikt.
Hoe het werkitem de specificatie wordt in Jira
Een goed opgesteld werkitem kan dienen als de specificatie waarvan de agent uitgaat bij het opstellen en op basis waarvan de agent beoordeelt. De specificatie kan ook in een gekoppeld document staan, en zo werken veel SDD-tools. Met Jira kan de specificatie gewoon staan waar het werk al wordt uitgevoerd. Een document is geschikt voor gebruik als specificatie als het de zes bovenstaande elementen bevat. Een werkitem met de ene regel "los de bug met het inloggen op" is dat niet.
Het bewaren van de specificatie bij het werkitem heeft één structureel voordeel: de specificatie bevindt zich dan waar het werk zich ook bevindt, waardoor de specificatie minder snel wordt genegeerd dan een markdown-bestand in een repo die niemand opnieuw opent. Dat zorgt echter nog niet dat ze vanzelf wordt nageleefd. Het betekent alleen dat de specificatie en het werk nooit uit elkaar gaan lopen.
Alles beweegt met elkaar mee: samenvatting, omschrijving, gekoppelde Confluence-vereisten en acceptatiecriteria bevinden zich op één plek, waar zowel de agent als de beoordelaar ze lezen.
Een repobestand bevindt zich daarentegen op een andere plek dan waar werk wordt bijgehouden, beoordeeld en afgerond, en raakt dus verouderd op het moment dat het plan verandert.
Hetzelfde werkitem wordt het beoordelingsgebied zodra de agent klaar is: de plek waar je team afstemming bereikt over vereisten en openstaande vragen.
Jira definieert plannen met ingebouwde duidelijke vereisten, taken en schattingen.
Hoe Jira Planner een gestructureerde specificatie genereert
In het vorige gedeelte werd de basis behandeld: zelf één werkitem omzetten in een specificatie. Jira Planner is bedoeld voor complexe initiatieven die meerdere teams omvatten, waarbij het vanwege de schaal niet mogelijk is om elke specificatie met de hand te schrijven. Begin bij het initiatief en splits dit op in gestructureerde werkitems, elk met een eigen specificatie.
Jira Planner is de versneller, niet de basis. De standaard SDD-methode is een goed opgesteld werkitem plus acceptatiecriteria, en elk team kan dit vandaag de dag realiseren. Jira Planner versnelt het lastigste deel van dat werk: een complexe, dubbelzinnige aanvraag omzetten in een gestructureerde specificatie.
Voor complexe projecten gebruikt Jira Planner de Teamwork Graph, inclusief je codebase, Jira- en Confluence-geschiedenis en teamcontext om vereisten te definiëren en een gestructureerde technische specificatie in Confluence te genereren, klaar voor een ontwikkelaar of programmeeragent om op voort te borduren. Eén plan, vele doelgroepen: leesbaar voor een mens, bruikbaar voor een agent.
Wat het doet:
Biedt een gedeeld oppervlak waarop jij en je team kunnen samenwerken, zodat je vooraf afstemming hebt voordat een agent wordt uitgevoerd.
Haalt context op uit je werk, zodat de specificatie begint met wat je team al weet in plaats van met een lege prompt.
Produceert een specificatie die voor een mens duidelijk leesbaar is en voor een agent goed is te parseren, zodat hetzelfde artefact geschikt is voor beoordeling en uitvoering.
Houdt de specificatie in Confluence, gekoppeld aan het werk, zodat de intentie en beslissingen vastgelegd blijven.
Jira Planner zet ruwe ideeën om in gestructureerde specificaties die klaar zijn voor agents
Jira Planner bevindt zich in het stadium voor vroege toegang — laat je op de wachtlijst zetten
Hoe je jouw eerste specificatie die bruikbaar is voor agents opstelt in Jira
Neem één werkitem en maak er handmatig een specificatie van die bruikbaar is voor agents, met de zes elementen als checklist.
Begin met een werkitem. Leg in de omschrijving het resultaat, de scopegrenzen en de beperkingen vast, niet alleen een titel.
Zet de intentie om in een gestructureerde specificatie. Dit is het echte SDD-werk. Vorm eerdere context om tot resultaten, scope en beperkingen voor het werkitem, zodat de agent een definitie overneemt.
Stel testbare acceptatiecriteria op. Dit zijn de contracten waar de agent naartoe werkt en waaraan de beoordelaar toetst. De meeste criteria hebben vaak een paar iteraties nodig voordat ze testbaar zijn.
Wijs het toe aan een programmeeragent. Een werkitem van specificatiekwaliteit geeft de agent voldoende om te implementeren en een pull request te openen die is gekoppeld aan het item.
Beoordeel de pull request op basis van de criteria en verfijn hem vervolgens. Maak de specificatie strakker waar de agent heeft gegokt en hergebruik het patroon bij het volgende werkitem.
Veelgestelde vragen over specificatiegestuurde ontwikkeling
Heb ik Jira Planner nodig om specificatiegestuurde ontwikkeling te realiseren?
Nee. De basis is een goed opgesteld werkitem met acceptatiecriteria, dat elk team vandaag nog kan opstellen. Voor complex werk versnelt Jira Planner dit door te beginnen met een plan op hoofdniveau, een initiatief, en dit op te splitsen in gestructureerde Jira-werkitems, elk met ingevulde specificaties, zodat je ze niet allemaal handmatig hoeft op te stellen.
Wat is het verschil tussen een specificatie en acceptatiecriteria?
De specificatie definieert de volledige wijziging: resultaten, scope, beperkingen en context. Acceptatiecriteria vormen één onderdeel, de testbare definitie van 'gereed' waar de agent naartoe werkt en waaraan de beoordelaar toetst.
Is een heel goede prompt genoeg?
Voor klein, omkeerbaar werk vaak wel. Bij alles wat complex is of moeilijk ongedaan te maken, moet de agent bij een prompt raden wat je hebt weggelaten. Een specificatie maakt gissen overbodig.
Moet de spec in een repobestand of een Jira-werkitem staan?
Een werkitem zorgt dat de specificatie zich bevindt waarin werk wordt bijgehouden, beoordeeld en gesloten. Daardoor is het risico kleiner dat het veroudert dan bij een markdown-bestand in een repo die niemand opnieuw opent.
Vertraagt specificatiegestuurde ontwikkeling teams?
Het kost vooraf extra inspanning, maar voorkomt herstelwerk in een later stadium. Bij complex werk is het resultaat hiervan per saldo voordelig. Sla bij triviale oplossingen de specificatie over en ga direct naar de prompt.
Wanneer moet ik een specificatie opstellen en wanneer kan ik dit overslaan?
Stel er een op voor complex werk, werk met grote impact of werk dat lastig terug te draaien is, of voor alles met echte architecturale of beveiligingsbeperkingen. Sla dit over voor kleine, omkeerbare oplossingen waarbij een snelle prompt vlotter werkt.