Het Probleem met Luchtig Aan de Gang Gaan

Stel je voor: je hebt een duidelijke feature in gedachten. Je opent je favoriete AI coding assistant, typt snel een verzoek, en kijkt hoe hij zelfverzekerd de helft van je codebase herschrijft. Een uur later sta je naar een PR te kijken die een probleem oplost dat je niet helemaal bedoelde, op een manier die dingen breekt die je niet van plan was om kapot te maken.

Herkenbaar? Je bent niet de enige. Nu AI coding agents zijn geëvolueerd van vraag-beantwoorders naar code-editors, ontdekken veel developers dat dezelfde losse prompting-aanpak die prima werkt voor chatbots, tekortschiet als er echte repositories op het spel staan.

De oplossing is niet gedetailleerdere prompts. Het gaat om een fundamentele shift in hoe we nadenken over de documenten die we naar deze agents sturen.

Prompts vs. Specs: Een Belangrijk Onderscheid

Hier is het ding over prompts: ze zijn geoptimaliseerd om werk te starten. Ze zijn prima voor snelle uitleg, wegwerpscripts en verkennende gesprekken. Een prompt leeft in een chat-sessie, kan afkortingen gebruiken, en gaat vaak uit van context die alleen de auteur begrijpt.

Dat werkt prima als je alleen vragen stelt.

Maar wanneer een AI agent op het punt staat om gedeelde code te bewerken, terminal commands uit te voeren, en branches te produceren die collega's gaan reviewen? Dan wordt je informele prompt een opdracht. En opdrachten hebben meer nodig dan goede formulering — ze hebben de juiste context nodig, duidelijke grenzen, concrete voorbeelden en validatiecriteria.

Hier komen specs om de hoek kijken.

Een spec is geen mooiere prompt. Het is een gestructureerd document dat vastlegt welk probleem je oplost, welk gedrag moet veranderen, wat hetzelfde moet blijven, en hoe je weet of het werk is geslaagd. In tegenstelling tot een prompt die verdwijnt zodra de agent aan het werk gaat, blijft een spec zichtbaar gedurende de hele workflow — de agent begeleidend, reviewers informerend, en toekomstige maintainers helpend begrijpen waarom beslissingen zijn genomen.

Wat Erin Zit: Een Goede AI-Agent Spec

Je hebt geen 20-pagina's document nodig. Wat je nodig hebt zijn vijf kernelementen:

1. Context: Waarom gebeurt deze taak? Welk gebruikersprobleem of technische schuld drijft het? Welke beperkingen bestaan er in de codebase die de agent moet begrijpen?

2. Gedrag om te veranderen: Welke specifieke functionaliteit moet worden aangepast, toegevoegd of verwijderd? Wees concreet — "gebruikers ontvangen e-mailnotificaties wanneer X gebeurt" werkt beter dan "verbeter het notificatiesysteem."

3. Beperkingen om te behouden: Wat moet absolút niet veranderen? Welke bestaande functionaliteit, API-contracten of performance-karakteristieken moeten intact blijven?

4. Voorbeelden van correctheid: Concrete scenario's die demonstreren wat goed looks. Gegeven/Wannear/Dan-format werkt hier goed, maar zelfs een paar expliciete testgevallen helpen de agent om je verwachtingen te begrijpen.

5. Validatiecriteria: Hoe weet een reviewer of het werk compleet is? Wat moeten ze inspecteren? Welke vragen moeten ze stellen?

Dit framework zal bekend klinken als je hebt gewerkt met BDD-scenario's, issue-templates met acceptatiecriteria, of design documents. Het specifieke formaat doet er minder toe dan de juiste informatie in een deelbare, reviewbare vorm hebben.

Waar Specs Thuishoren in Je Workflow

Een van de beste dingen aan specs is hun flexibiliteit. Het hoeven geen aparte documenten te zijn die je vertragen. Een spec kan overal leven waar dat zinvol is voor je team:

• Een GitHub issue met expliciete acceptatiecriteria
• Een PR-beschrijving die het veranderde gedrag benoemt
• Een BDD-scenario in je featurebestanden
• Een lichtgewicht designnotitie voor implementatie
• Tools zoals OpenSpec of GitHub Spec Kit die dit patroon formaliseren

De sleutel is context en reviewcriteria zichtbaar en persistent maken. Je spec zou niet moeten verdwijnen wanneer de chatsessie eindigt. Het moet met het werk meereizen, collega's iets concreets geval om te evalueren.

De Opdrachtlaag: Intentie en Uitvoering Scheiden

Hier wordt het echt interessant.

De sterkste specs werken als kleine behavior contracts. Ze scheiden drie onderscheiden vragen:

1. Welk gedrag moet veranderen? (De requirement)
2. Welke beperkingen of voorbeelden definiëren correctheid? (De acceptatiecriteria)
3. Welke implementatieroute lijkt nu gepast? (De technische aanpak)

Deze vragen zijn verbonden, maar ze zouden niet moeten samensmelten tot één klomp instructies.

Waarom is dit belangrijk voor AI coding agents? Omdat wanneer je intentie en implementatie te vroeg mengt, de agent kan optimaliseren voor het verkeerde ding. Hij kan braaf een gesuggereerd implementatiedetail volgen terwijl hij het eigenlijke gedrag dat je nodig had mist. Of hij produceert code die technisch interessant is maar het gestelde probleem niet oplost.

Een opdrachtlaag houdt de requirement stabiel terwijl de implementatie kan evolueren. Terwijl de agent de codebase leest, complicaties ontdekt en zijn aanpak verfijnt, blijft de spec het anker: "Heeft het werk dit bevredigd?"

Dit is vooral waardevol voor bestaande codebases. De meeste engineering werk is geen greenfield — je verandert gedrag dat al bestaat. Een goede spec zegt: hier is het huidige gedrag, en hier is wat moet veranderen. Reviewers hoeven je intentie niet mentaal te reconstrueren uit implementatiedetails.

De Shift Maken

Als je gewend bent om AI coding agents te behandelen als supercharged zoekmachines, kan dit aanvoelen als overdenken. Maar denk aan het alternatief: ongecontroleerde wijzigingen in gedeelde code, PRs die moeilijk te reviewen zijn, en werk dat niet helemaal past bij wat je je had voorgesteld.

De shift naar spec-driven AI samenwerking draait niet om bureaucratie. Het draait om beide mens en machine de duidelijkheid geven die ze nodig hebben om effectief samen te werken.

Begin klein. De volgende keer dat je op het punt staat een AI coding agent in een repository los te laten, neem vijf minuten de tijd om context, de gedragsverandering en de succescriteria op te schrijven. Zet het ergens zichtbaar — zelfs als het maar in de PR-beschrijving is.

Je toekomstige zelf (en je collega's) zullen je dankbaar zijn.

De bottom line: AI coding agents zijn krachtige medewerkers. Behandel ze als medewerkers. Geef ze een goed briefing, en je krijgt werk dat de moeite van het reviewen waard is.