AI-agents in echte projecten

Wat werkt, wat faalt, en waar een mens onmisbaar blijft. Uit een platform dat we op dit moment met agents bouwen.

We bouwen op dit moment een cloudplatform waarbij het grootste deel van de code door AI-agents wordt geschreven. Niet als experiment en niet als demo: het is een systeem waar straks andermans applicaties op draaien, en dat betekent dat de lat niet lager ligt omdat er een agent aan het toetsenbord zit.

Dit artikel gaat over wat we daar hebben opgezet en waarom. Het project is nog niet af, dus dit is geen terugblik. Het is een tussenstand van iemand die er nu in zit.

Het probleem is niet de code

Agents schrijven prima code. Geef een agent een falende test en hij maakt hem groen. Geef hem een duidelijk afgebakende opdracht en er komt iets uit dat werkt. Dat is niet waar het misgaat.

Waar het misgaat is alles eromheen. Een agent begint elke sessie zonder geheugen. Hij weet niet welke afweging je vorige week hebt gemaakt, waarom een bepaalde bibliotheek er wel in zit en een andere niet, of dat er drie maanden geleden een besluit is genomen dat de helft van je architectuur bepaalt. Hij weet wat er in de bestanden staat en wat jij hem in dit gesprek vertelt.

Dat verandert wat “documentatie” is. Bij een team van mensen is documentatie een service aan de nieuwe collega. Bij agents is het de invoer. Wat niet opgeschreven staat, bestaat niet, en de agent gaat het invullen met wat aannemelijk lijkt.

Wat vooraf vastligt bepaalt wat eruit komt

De eerste beslissing die we in dit project namen ging niet over techniek. Het was dat er niets gebouwd wordt zonder goedgekeurde specificatie en goedgekeurd plan.

De cyclus is:

Idee → spec → goedkeuring → plan → goedkeuring → implementatie (TDD) → review → klaar

Twee goedkeuringsmomenten, en die worden nooit samengevoegd. De spec legt vast wat en waarom; het plan legt vast hoe, inclusief het testplan en de opdeling in taken. Pas daarna mag er productiecode komen.

Dat klinkt zwaar voor een project waar snelheid het punt zou moeten zijn. In de praktijk is het omgekeerd. Een agent die een goedgekeurd plan uitvoert doet dat in één keer goed, omdat de moeilijke vragen al beantwoord zijn. Een agent die zonder plan begint produceert iets dat er goed uitziet, waar je vervolgens een uur op reviewt om te ontdekken dat hij een aanname heeft gedaan die je niet deelt.

De uitzondering staat er ook expliciet in: een wijziging mag spec en plan overslaan als er geen extern zichtbaar gedrag verandert, het rond de twintig regels blijft, en er geen afhankelijkheid, API of schema bij betrokken is. Bij twijfel is het geen kleine wijziging. Zonder die uitzondering ga je hem zelf stilzwijgend oprekken, en dan is de regel weg.

Eén plek per feit

De tweede regel is strenger dan hij klinkt: elk feit staat in precies één bestand. Elke andere plek die het nodig heeft, linkt ernaar.

De toets die we gebruiken: “als dit morgen verandert, hoeveel bestanden moet ik dan aanpassen?” Het enige goede antwoord is één.

Bij mensen is een beetje herhaling onschuldig. Iemand leest twee varianten van dezelfde regel, ziet dat de ene ouder is, en handelt naar de nieuwe. Een agent doet dat niet. Die vindt beide, kiest er een (vaak degene die het dichtst bij zijn context staat) en bouwt verder op de verkeerde. En omdat het antwoord plausibel is, merk je het pas als het al ergens in productie zit.

Het routeringsbestand van het project begint daarom met de zin dat het zelf geen regels bevat. Het zegt alleen waar elke regel woont. Een tabel met wie wat bezit: workflow hier, teststandaarden daar, architectuurbeslissingen weer ergens anders. Een agent die een regel zoekt komt op precies één plek uit.

Wat besloten is en wat opgeschreven is, zijn twee dingen

Dit is de regel die we hebben toegevoegd nadat het misging.

Er is in dit project een keuze gemaakt voor een andere container-orchestrator. Die keuze is besproken, hij is meteen toegepast, en hij is nergens vastgelegd. Het gevolg: de hele verzameling documenten bleef de oude keuze beschrijven, terwijl de code de nieuwe volgde. Elke agent die daarna een spec las kreeg een beeld dat niet meer klopte.

Bij een menselijk team was dat een vervelend half uur geweest. Iemand zegt “dat hebben we omgegooid”, en klaar. Met agents als lezer heeft niemand dat geheugen. “Besloten” en “vastgelegd” drijven stil en snel uit elkaar.

De regel die er nu staat is absoluut: een keuze die in een gesprek is gemaakt en niet is opgeschreven, bestaat niet. Geen chat, geen inleiding van een spec, geen commit-bericht telt. Alleen een regel in het besluitenregister of, als het zwaar genoeg weegt, een eigen beslisdocument.

En daar kwam een tweede ding uit voort dat achteraf het belangrijkste is: elke spec vermeldt in de kop waar hij op rust. Welke beslissingen eronder liggen. Als een van die beslissingen later wordt vervangen, rolt er een lijst uit van alle specs die opnieuw bekeken moeten worden, in plaats van dat het afhangt van of iemand het zich herinnert.

Dat is geen agent-probleem dat we hebben opgelost. Dat is een probleem dat elk langlopend project heeft en dat agents alleen sneller zichtbaar maken.

Regels die alleen in tekst staan, worden overtreden

Een standaard die in een document staat is een verzoek. Agents houden zich er grotendeels aan, tot ze het onder druk niet doen. Precies zoals mensen.

Dus staan de dingen die echt niet mogen niet in tekst maar in code. Een paar voorbeelden uit dit project.

Er is een hook die git commit --no-verify weigert. Dat commando slaat de kwaliteitscontroles over die in de definitie van “klaar” staan. Vraag een agent of hij dat wil gebruiken en hij zegt nee. Maar als de tests roodstaan en de opdracht is “zorg dat dit gecommit wordt”, dan is het een voor de hand liggende uitweg. Nu kan het niet meer, en is de enige weg vooruit de test repareren.

Er is een tweede hook die afgaat zodra een bestand met regels of afspraken wordt gewijzigd. Die controleert niet de inhoud, maar herinnert aan de enige-plek-controle: grep de kernzinnen van wat je net veranderde door het hele project, en bevestig dat het feit nog steeds op één plek staat en de links kloppen. Een deterministische trigger op precies het moment waarop drift ontstaat.

Het verschil is belangrijk. De hook beoordeelt niets. Hij zorgt ervoor dat de controle niet vergeten kán worden. Alles wat op oordeel berust, kan een slechte dag hebben; alles wat een exit 2 is, niet.

De review kent de regels niet uit zijn hoofd

De laatste stap van elke wijziging is een reviewstap die het werk toetst aan de standaarden. De constructie daarvan is het vermelden waard: de review leest de standaardenmap tijdens het uitvoeren.

Dat betekent dat een regel aanpassen automatisch aanpast wat er wordt afgedwongen. Er is geen tweede lijst die bijgewerkt moet worden, geen checklist die achterloopt op de standaarden. De regels staan op één plek en de handhaving haalt ze daar op.

Het alternatief, de regels in de reviewprocedure zetten, lijkt sneller en is precies het probleem dat de enige-plek-regel bestrijdt.

Waar een mens onmisbaar blijft

Na een paar maanden zo werken is dit de eerlijke verdeling.

Agents zijn goed in uitvoeren. Een goedgekeurd plan omzetten in code, test-first, taak voor taak. Mechanisch werk over veel bestanden. Onbekende code lezen en uitleggen. De eerste versie van vrijwel alles.

De mens beslist wat er gebouwd wordt, en wat niet. Dat is niet uit voorzichtigheid. Een agent kan een technische afweging uitstekend uiteenzetten, maar hij kent de commerciële context niet: wat een klant volgend jaar nodig heeft, welke afhankelijkheid je niet wilt aangaan omdat je van die leverancier af wilt kunnen, welke functionaliteit beter niet gebouwd kan worden. De twee goedkeuringsmomenten in de cyclus zitten daar niet als formaliteit. Ze zitten daar omdat dat de twee plekken zijn waar een verkeerde aanname het duurst is.

De mens ziet wat er ontbreekt. Dit project heeft een apart register van dingen die het ontwerp nog niet beantwoordt. Geen takenlijst voor code, maar een lijst van plekken waar we zouden gokken als we nu zouden beginnen. Elke regel benoemt wat mist, wat het blokkeert, en waarmee het gesloten wordt. Dat is werk dat een agent uit zichzelf niet doet: die vult een gat liever plausibel in dan dat hij hem meldt.

De mens bepaalt wanneer een gat een gok is. In datzelfde register staat een opmerking die het hele project typeert: een aantal open vragen kan pas beantwoord worden zodra er een ontwikkelomgeving draait om tegenaan te testen. Dat maakt die ene spec het kritieke pad in plaats van een zijproject. Zo’n herordening is een oordeel over waar onzekerheid zit, niet over hoe code eruitziet.

Wat dit kost, en wat het oplevert

Eerlijk zijn over de prijs: dit is meer administratie dan een project van deze omvang normaal draagt. Specs, plannen, beslisdocumenten, een besluitenregister, een gatenregister, vier vaste procedures en drie hooks. Voor een klus van twee weken zou dat onzin zijn.

Wat het oplevert is dat de context niet aan één persoon hangt. Elke agent, elke sessie, elke nieuwe medewerker begint met dezelfde afgebakende waarheid. En de bijvangst is de eigenlijke winst: dit is óók de documentatie die je wilt hebben als er over twee jaar iemand anders aan zit. We schreven het op omdat agents niet zonder kunnen. Het blijkt precies wat een project langer dan een jaar overeind houdt.

De meeste dingen die agents productief maken, zijn dingen die goede projecten altijd al hoorden te hebben. Het verschil is dat je er nu niet meer omheen kunt.

---

Hexxore bouwt software met AI-agents en adviseert over hoe je dat verantwoord inricht. Wat een agentic workflow productiewaardig maakt, staat op onze pagina over agentic workflows. Loopt er bij jou een project waarbij die vraag speelt? Vertel het ons.