Eén agent met een plan wint van vier tegelijk: eerst drie documenten, dan pas code

Ik heb me nooit prettig gevoeld bij het parallel laten draaien van meerdere AI-agents in dezelfde codebase. De belofte is duidelijk: vier agents, vier bestanden, vier keer zoveel doorvoer. Maar op elk project waar ik het daadwerkelijk heb geprobeerd, bleek de praktijk rommeliger. Daarom werk ik inmiddels in een ander ritme: eerst drie documenten schrijven voordat een agent de codebase aanraakt, daarna één fase tegelijk, één agent, valideren, committen. Het voelt trager op de stopwatch, terwijl het in mijn projecten van begin tot eind sneller gaat. Hieronder leg ik uit wat voor mij werkt, waarom elk onderdeel erin zit en welke faalscenario's deze aanpak voorkomt.

Het echte faalscenario bij parallelle agents

Snelheid is het probleem niet. Als twee agents tegelijk aan dezelfde feature werken, werkt elke agent op een momentopname van de codebase zoals die was toen hij begon. Ze delen geen geheugen en lezen elkaars werk onderweg niet terug, dus geen van beide ziet wat de ander in de afgelopen 8 minuten heeft besloten. Tegen de tijd dat beiden klaar zijn, heb je twee implementaties die elk afzonderlijk correct lijken en samen niet kloppen.

De concrete dingen die misgaan.

• Dubbel werk. Agent A bouwt een helper in lib/format-amount.ts. Agent B weet daar niets van en schrijft dezelfde helper inline op drie plekken. Je verwijdert er een of voegt ze handmatig samen. Hoe dan ook heb je voor beide betaald.
• Conflicterende implementaties. Agent A geeft geld terug als een getal met centen. Agent B serialiseert het als een string met een valutasuffix. Beide onafhankelijk gecommit. De derde agent kiest de ene, de vierde de andere, en jij besteedt de middag aan het rechttrekken van de verschillen.
• Onnodige refactoring. Elke agent leest de codebase, besluit "dit zou schoner zijn als we X eruit halen" en refactort. Drie agents, drie refactors, geen daarvan essentieel voor de daadwerkelijke feature. De diff groeit hard en het reviewen wordt zwaar.
• Architecturale drift. De traagste en de duurste. Geen van de vier agents had het volledige beeld van waar de feature in de architectuur zou moeten landen. Elk maakte een redelijke lokale keuze. De lokale keuzes vormen samen geen coherent geheel.

Parallellisme vermenigvuldigt het tempo waarin er code bij komt. Het vermenigvuldigt net zo goed de kosten van elke beslissing die eigenlijk centraal genomen had moeten worden en dat niet is.

Eerst het denkwerk opschrijven, dan pas code

Wat voor mij daadwerkelijk werkt: het denkwerk zichtbaar maken, vastleggen en laten uitkristalliseren voordat er één regel code geschreven wordt. De agent hoeft dan niet meer te bepalen wát er moet gebeuren, alleen nog hoe. Ik besteed een middag aan dat denkwerk en leg het vast in drie documenten, en daarmee wordt de implementatiefase een veel scherper afgebakend probleem.

Ik bewaar ze in de repo, in een map genaamd /feature-docs/. Elke feature krijgt een eigen submap. Drie bestanden, in deze volgorde.

1. brainstorming.md

Hier denk ik hardop na over het probleemgebied voordat ik besluit wat ik ga bouwen. Een gepolijst document is niet het doel. Ik leg het rommelige deel van het denkwerk vast, zodat ik er later op kan terugvallen.

Wat erin komt.

• De daadwerkelijke job to be done: wat de klant echt gedaan wil krijgen, in de woorden van de klant als ik die heb.
• Het onderliggende probleem achter het oppervlakkige verzoek. Vaak is het verzoek al een voorgestelde oplossing en staat het echte probleem er niet in.
• Twee of drie plausibele oplossingsrichtingen, elk beschreven in een alinea.
• Trade-offs daartussen.
• Edge cases waaraan ik heb gedacht, inclusief de edge cases die waarschijnlijk niet uitmaken maar die ik wil markeren als "niet aangepakt vanwege X".
• Anti-patronen die ik wil vermijden. De verleidingen waarvan ik weet dat ik er zonder geschreven herinnering weer intrap.
• Architecturale aandachtspunten. Waar de feature het bestaande systeem raakt op manieren die niet lokaal zichtbaar zijn.

Het doel is helderheid van denken, niet volledigheid. Als ik geen korte alinea kan schrijven die de gekozen aanpak verdedigt tegenover de twee alternatieven, heb ik niet genoeg nagedacht. Ik lees de brainstorm opnieuw wanneer ik aan de PRD begin, vaak met als resultaat dat de PRD ervan afwijkt. Dat is prima; de brainstorm heeft dan zijn werk gedaan.

2. prd.md

PRD staat voor product requirements document: een kort document dat vastlegt wat je bouwt, voor wie, en wanneer het af is. Dit is de ene plek waar de waarheid over de feature staat, in het vak heet dat de single source of truth. Zodra het geschreven is, los je elke onenigheid over wat we bouwen op door dit document te lezen en bij te werken. De PRD gaat boven de code, niet andersom. Als de implementatie om een goede reden van de PRD afwijkt, pas je de PRD aan en commit je die opnieuw.

Wat erin komt.

• Productcontext. Een alinea of twee over waarom deze feature bestaat en hoe succes eruitziet.
• Feature-vereisten. De concrete dingen die de feature moet doen, scherp genoeg geformuleerd dat je elk punt kunt afvinken zodra de implementatie klaar is.
• User stories. Een paar primaire, geschreven vanuit het perspectief van de gebruiker, om vast te pinnen wat de feature daadwerkelijk mogelijk moet maken.
• Low-fidelity wireframes. ASCII-boxen, schetsen, screenshots met pijlen erop. Alles wat de ruwe layout vastlegt. De agent hoeft de layout niet pixel-perfect te kennen, hij moet alleen weten: "deze drie dingen op de pagina, in deze volgorde, met deze hiërarchie".
• UX-beslissingen. De paar keuzes die de implementatie beïnvloeden. Modal versus inline. Server-rendered versus client-rendered. Direct het resultaat tonen en achteraf bevestigen (optimistic UI) versus een laadindicator.
• Technische beperkingen. Bestaande services om te gebruiken, performancebudgetten, security-vereisten, alles wat de oplossingsruimte afbakent.
• Verwacht gedrag. Edge cases, errorstates, lege states, laadstates, wat er gebeurt als de gebruiker iets doet dat niet wordt ondersteund.

De PRD hoeft niet lang te zijn. De goede PRD's die ik heb geschreven tellen 800 tot 2.000 woorden. Alles daarboven is meestal de brainstorm die in de PRD lekt, of implementatiedetails die in het volgende document thuishoren.

3. implementation-plan.md

Zodra het denkwerk stabiel is en de vereisten vastgepind zijn, breekt dit document het werk op in fases in plaats van in losse taken. Een fase is een eenheid die je als één logische stap kunt implementeren, valideren en committen.

Elke fase heeft dezelfde vorm.

• Implementatiedoelen. Wat deze fase oplevert, in een of twee zinnen.
• Afgebakende taken. De concrete aanpassingen, in ruwe volgorde. Gedetailleerd genoeg dat een agent ze kan uitvoeren, beknopt genoeg dat ik ze niet hoef te herschrijven wanneer de realiteit iets afwijkt.
• Afhankelijkheden. Wat waar moet zijn voordat deze fase begint. Meestal de vorige fase, soms iets extern.
• Validatiecriteria. Hoe ik weet dat de fase klaar is. Specifiek. "Ga naar /settings, verander de taal, ververs, zie de nieuwe taal behouden" is goed. "Instellingen werken" is dat niet.
• Testcases. De twee of drie scenario's die ik gedekt wil zien voordat deze fase als afgerond telt.

Voor de meeste features kom ik uit op 3 tot 6 fases. Auth-feature, 5 fases. Data-exportfeature, 3 fases. Een refactor die door meerdere lagen van het systeem snijdt, 7 tot 10 fases.

Daarna: één fase tegelijk

Met het implementatieplan op tafel is het daadwerkelijke werk saai, op de best denkbare manier. Ik start de agent, wijs hem naar de PRD en de huidige fase in het implementatieplan, en vraag hem die ene fase uit te voeren. Niets anders.

Wat dit me oplevert.

1. De agent heeft een scherpe specificatie om mee te werken in plaats van een vage featurebeschrijving.
2. De schade die een enkele agent-run kan aanrichten blijft beperkt tot één fase, dus een slechte run is goedkoop terug te draaien.
3. Validatie vindt plaats na elke fase. De agent vertelt me dat hij klaar is. Ik controleer dat tegen de validatiecriteria. Als het klopt, commit ik. Zo niet, dan lost de agent het op binnen dezelfde fase voordat er nieuw werk begint.
4. De agent hoeft niet de hele feature in zijn hoofd te houden. Hij hoeft alleen de huidige fase plus de relevante vereisten uit de PRD vast te houden.
5. Als een fase aan het licht brengt dat het plan verkeerd was, werk ik eerst het implementatieplan bij, commit dat, en ga dan verder. Het plan is een levend document, geen vast contract.

Ik heb geprobeerd om één agent alle fases achter elkaar in een enkele run te laten doorlopen. Het werkt bij kleine features. Het gaat mis bij alles waar de validatiestap een verkeerde aanname vroeg had kunnen opvangen. Daarom stop ik na elke fase, ook als de agent door zou kunnen.

Waarom dit beter werkt dan onbeperkt parallel werken

Drie redenen waarom dit bij het soort werk dat ik doe consequent beter presteert dan de aanpak met parallelle agents.

Context blijft behouden tussen fases

De PRD en het plan zijn de blijvende context. Elke fase begint met het opnieuw doorlezen ervan. De agent hoeft nooit te reconstrueren wat de feature is, want het document ligt er gewoon. Bij parallelle agents reconstrueert elke agent zijn eigen context, en die reconstructies lopen uiteen.

Minder herwerk

De grootste kostenpost bij parallelle agent-runs is het werk dat je weggooit wanneer er twee botsen. Bij gefaseerde uitvoering met één agent botsen er geen agents, want er schrijft er maar één tegelijk. Het herwerk dat ik doe is "deze fase voldeed niet helemaal aan de validatiecriteria", wat klein en beperkt is.

Product en engineering blijven op elkaar afgestemd

De PRD is een productartefact. Het implementatieplan is een engineeringartefact. Beide staan in de repo en beide zijn geversioneerd. Als een PR terugkomt voor review, leest de reviewer eerst de PRD, dan het plan, dan de code. De beslissingen zijn zichtbaar. Die coherentie is waardevoller dan pure snelheid aan de implementatiekant.

Naast elkaar gezet ziet het verschil er zo uit.

Waarom het denkwerk een lege middag vraagt

De drie documenten goed schrijven is echt lastig. Het is het deel van het werk dat zich niet laat delegeren, parallelliseren of versnellen met tools. Het vraagt aanhoudende aandacht. Als ik een PRD probeer te schrijven tussen meetings door, in blokjes van 20 minuten, komt er een checklist uit zonder dat er een echt argument in zit. De agent werkt ermee en levert code op die er qua vorm goed uitziet, terwijl de essentie van de feature ontbreekt.

Daarom reserveer ik een lege middag voor de documentatieronde. Geen gesprekken, geen Slack, geen e-mail. Alleen de brainstorm, de PRD, het plan. Het eerste uur is meestal zichtbaar onproductief, omdat ik bestaande code en oude tickets herlees om de context te laden. In uur twee en drie schrijf ik de documenten daadwerkelijk uit. In uur vier check ik het implementatieplan tegen de PRD, vind ik de gaten, en dicht ik ze.

Na die middag zijn de volgende twee of drie sessies vooral uitvoering. De agent doet het meeste typewerk, ik doe de validatie tussen de fases. Het denkwerk zit geconcentreerd in één blok, en daarna gaat de rest van de week snel.

Wanneer dit overkill is, en wanneer niet

De eerlijke versie. Deze workflow is overkill voor eenmalige kleine wijzigingen, verkennende experimenten waarbij je alleen iets wilt uitproberen (in het vak spikes), of elke taak waarbij de kosten van het weggooien van het resultaat laag zijn. Schrijf geen brainstorm voor het toevoegen van een knop. Schrijf geen PRD voor het fixen van een typefout.

Waar de workflow loont.

• Features die drie of meer bestanden raken, vooral over product/engineering-grenzen heen.
• Alles wat gereviewd gaat worden door een menselijke reviewer die de beslissingen niet heeft meegemaakt.
• Alles waarbij een verkeerd opgezette oplossing duur is om terug te draaien. Nieuw datamodel, nieuw API-oppervlak, nieuw auth-pad.
• Alles waar je over zes maanden nog op terug wilt kunnen komen en het dan nog wilt begrijpen.

Voor de rest: gewoon bouwen, zonder documenten.

Voor welke teams dit nu speelt

Even nuchter over waar dit gesprek staat. Parallelle agents zijn op dit moment vooral een discussie onder power-users die al maanden dagelijks met code-agents werken. Het gros van de Nederlandse development-teams dat ik spreek zit een stap eerder: ze zetten net hun eerste code-agent serieus in, of experimenteren nog met wat ze de agent durven toe te vertrouwen. Voor deze workflow is dat eerder een voordeel dan een achterstand. Wie dit ritme vanaf de eerste agent aanleert, slaat de dure leerfase over waarin je ontdekt waarom vier agents tegelijk een middag opruimwerk opleveren.

Voor een beslisser is de rekensom een andere dan voor een developer. De winst zit in minder herwerk, minder review-uren en een oplevering die voorspelbaarder wordt. Meer code per uur levert het niet op. Een feature die in één keer door review komt omdat de beslissingen op papier staan, is goedkoper dan een feature die twee keer sneller getypt is en drie keer terugkomt.

De realistische eerste stap kost geen tooling en geen budget: kies één feature die meerdere bestanden raakt, reserveer één middag voor de drie documenten, en laat daarna één agent fase voor fase uitvoeren. Vergelijk na afloop het aantal correctierondes met hoe zo'n feature er normaal doorheen gaat. Dan weet je binnen één sprint of dit voor jouw team werkt.

De trade-offs

Drie eerlijke kosten, zodat dit artikel niet als een verkooppraatje leest.

• De eerste middag voelt traag. Stakeholders die naar het aantal bestanden kijken, zien pas op dag twee code. Je moet bereid zijn de documentatiefase te verdedigen als werk, niet als voorbereiding op werk.
• De PRD veroudert als je hem niet onderhoudt. Zodra de implementatie van de PRD afwijkt zonder dat je die bijwerkt, ben je het voordeel van de single source of truth kwijt. Dat vraagt discipline.
• Het schaalt niet naar teams die er niet in geloven. Als de helft van het team PRD's schrijft en de andere helft niet, krijg je twee culturen binnen één repo. Kies dan liever één aanpak en handhaaf die, in plaats van het half te doen.

Waar ik uitkom

Ik denk niet dat het parallel laten draaien van AI-agents in principe verkeerd is. De tooling eromheen wordt bovendien snel beter: geïsoleerde werkkopieën per agent, takenwachtrijen, orkestratielagen die agents op elkaar laten wachten. Mijn inschatting is dat parallel werken zinvol wordt zodra taken echt onafhankelijk van elkaar zijn, zoals een migratie in het ene deel van het systeem en een losse bugfix in het andere. Bij samenhangend featurewerk, het soort werk dat de meesten van ons doen, blijft het denkwerk de bottleneck, en dat laat zich slecht over meerdere agents verdelen.

De winst van parallel werken is meteen zichtbaar, de faalscenario's pas veel later. Daardoor ziet de rekensom er beter uit dan hij is. Gefaseerde uitvoering met één agent op basis van een geschreven PRD kent in mijn projecten minder uitschieters, is van begin tot eind eerder klaar en produceert code die een mens daadwerkelijk kan reviewen.

Het lastige zit niet in de documenten zelf, maar in de gewoonte om het denkwerk te behandelen als werk en niet als iets dat je er nog even bij doet.

Wil je een kritische blik op een workflow die je aan het uitproberen bent, stuur me dan een bericht. Mail info@jermayads.nl of gebruik jermayads.nl/contact.