AI-projecten beginnen altijd hetzelfde. Een Jupyter notebook, een paar experimenten, misschien een eerste werkende versie die iemand indruk maakt. Dan wordt het serieuzer. De notebook wordt een map met scripts. De map wordt een repo. De repo groeit uit tot een monorepo waar niemand meer doorheen kan navigeren.
Na drie maanden is de codebase onbeheersbaar. Niet door slechte code, maar door het ontbreken van structuur. De logica van de agent staat verspreid over vijf mappen. De integraties zijn half generiek, half project-specifiek. De infra-configuratie zit naast de business-logica. Niemand weet meer precies waar iets staat.
Dit is geen theoretisch probleem. Het is de standaard manier waarop AI-projecten groeien als je er niet bewust over nadenkt.
Het probleem
De eerste versie werkt. Dat is het probleem.
Als de eerste versie werkt, is er geen directe druk om structuur aan te brengen. De tweede feature komt erboven op. De derde ook. Elke toevoeging is op zichzelf logisch. Maar na genoeg van zulke toevoegingen is de samenhang verdwenen.
In een AI-project groeien typisch de volgende dingen door elkaar heen:
Agent-logica — de graaf, de tools, de retrieval-strategie, de prompts. Dit is de kern van wat het systeem doet en verandert het vaakst.
Integraties — verbindingen met externe systemen: databases, API's, webhooks, kanalen. Sommige zijn gedeeld tussen agents, andere zijn agent-specifiek.
Infra — Kubernetes-configuraties, secrets management, CI/CD pipelines, monitoring. Dit verandert minder vaak maar heeft grote impact als het fout gaat.
Shared utilities — logging, foutafhandeling, authenticatie, database-abstracites. Code die in principe door alles gebruikt wordt maar geen duidelijk eigenaar heeft.
Meerdere agents — als het project groeit, komen er meerdere agents bij. Elk met eigen logica, maar wel op dezelfde infra.
Zonder structuur groeit dit organisch samen. Na verloop van tijd weet niemand meer: wie is eigenaar van welke map? Waar staat de business-logica? Welke code is echt gedeeld en welke is per ongeluk gedeeld omdat iemand een import niet wilde dupliceren?
De codebase is technisch gezien correct. Ze werkt. Maar ze is niet meer te begrijpen door iemand die er niet van het begin bij was. En zelfs die persoon heeft inmiddels moeite.
Wat goede structuur betekent voor agent-projecten
Goede structuur voor een AI-project is niet hetzelfde als goede structuur voor een webapplicatie. De specifieke uitdagingen zijn anders.
In een agent-project heb je te maken met een paar spanningen die je expliciet moet adresseren:
Meerdere agents die onafhankelijk evolueren. Agent A heeft andere requirements dan Agent B. Ze delen infra, maar niet hun logica. Als je ze door elkaar gooit, blokkeert een wijziging in Agent A de deployment van Agent B.
Gedeelde infra die door alle agents gebruikt wordt. De Kubernetes-configuratie, de secrets-store, de CI/CD-pipeline: die zijn gemeenschappelijk. Een wijziging daar raakt alles. Dat moet zo zijn, maar het moet ook expliciet zijn.
Secrets die per agent en per environment zijn. Productie-credentials voor Agent A mogen niet zichtbaar zijn voor de deployment van Agent B. En test-credentials mogen niet in productie terechtkomen. Dat klinkt vanzelfsprekend, maar zonder structuur glipt het er altijd doorheen.
Deployment die consistent blijft over alle agents heen. Als Agent A anders wordt gedeployed dan Agent B, heb je geen gestandaardiseerde manier om problemen te debuggen. Je hebt twee los-gedefinieerde systemen die toevallig op dezelfde infra draaien.
Goede structuur maakt al deze spanningen expliciet en lost ze op via de manier waarop de repo is georganiseerd. Niet via afspraken in een Notion-pagina die niemand leest.
De platform/agent scheiding
De oplossing die wij consequent toepassen is een harde scheiding tussen de platform-layer en de agent-workspaces.
De platform-layer
De platform-layer bevat alles wat gedeeld is en stabiel moet blijven. Concreet:
Helm-charts en infra-definities voor de gedeelde omgeving. Dit is de basis waarop alle agents draaien. Wijzigingen hier hebben direct effect op alles.
Secrets management: de configuratie van hoe secrets worden opgeslagen, geroteerd en beschikbaar gesteld aan agents. Niet de secrets zelf, maar de structuur eromheen.
CI/CD workflows die voor alle agents gelden. Standaard pipelines voor bouwen, testen en deployen. Individuele agents kunnen deze uitbreiden, maar niet omzeilen.
Docker base-images en gedeelde build-configuraties. Als alle agents dezelfde base-image gebruiken, zijn security-patches eenmalig door te voeren.
Monitoring en alerting: de centrale stack voor logs, metrics en traces. Agents pluggen hier in via standaard-interfaces.
De agent-workspace
Elke agent heeft een eigen workspace binnen de monorepo. Die workspace is zelfstandig genoeg om onafhankelijk te kunnen evolueren, maar volgt de structuur die de platform-layer verwacht.
Een typische agent-workspace bevat:
packages/db — database-schema, migraties en repositories. Dit is de data-laag van de agent. Schema-wijzigingen worden hier bijgehouden, niet verspreid over losse SQL-bestanden.
services/agent — de agent-kern: de graaf, de tools, de retrieval-strategie. Dit is waar de meeste ontwikkeling plaatsvindt. Het is ook het meest agent-specifieke onderdeel.
services/api — de ingang van buiten: HTTP-endpoints, authenticatie, kanaal-integraties. Hier komen berichten binnen en gaan antwoorden uit.
Elke agent-workspace is een op zichzelf staand geheel. Je kunt hem begrijpen zonder de rest van de repo te kennen.
Waarom de scheiding werkt
De scheiding werkt omdat ze de aard van de wijzigingen volgt.
Infra-wijzigingen, zoals een nieuwe Kubernetes-versie, een gewijzigde secrets-store of een aangepaste monitoring-stack, moeten alle agents tegelijk raken. Dat is de bedoeling. Ze horen in de platform-layer en worden van daaruit uitgerold.
Agent-wijzigingen, zoals een nieuwe tool, een gewijzigde retrieval-strategie of een extra API-endpoint, zijn geïsoleerd tot de betreffende workspace. Een deployment van Agent A raakt Agent B niet.
Teams kunnen parallel werken. Het team dat aan Agent A werkt hoeft niet te wachten op het team dat Agent B deployt. Ze zitten niet in elkaars weg, letterlijk niet in de repo en ook niet in de deployment-pipeline.
Een nieuwe agent toevoegen is een workspace scaffolden, niet de bestaande structuur aanpassen. Je maakt een nieuwe map volgens het standaard patroon, je plugt in op de platform-layer, en je kunt beginnen. Je hoeft geen bestaande code aan te passen om een nieuwe agent toe te voegen. Dat is het verschil tussen een uitbreidbare architectuur en een grote bal modder.
De rol van expliciete grenzen
Een minder voor de hand liggend voordeel van deze structuur is dat grenzen expliciet worden. Als iets in de agent-workspace staat, is het agent-specifiek. Als iets in de platform-layer staat, is het gedeeld. Er is geen tussengebied waar code "misschien gedeeld" is.
Expliciete grenzen maken code-reviews eenvoudiger. Een reviewer hoeft niet te redeneren over wat de impact is van een wijziging op de rest van het systeem. De structuur geeft het antwoord.
Ze maken ook on-call makkelijker. Als er iets misgaat om drie uur 's nachts, weet je meteen of het een platform-probleem is dat alle agents raakt, of een agent-specifiek probleem. Dat bepaalt wie je wakker maakt.
De praktijk
Hoe het eruitziet als je het goed doet
Een goed gestructureerde repo is saai. Dat is een compliment. Je opent een agent-workspace en je weet waar alles staat. De database-migraties staan in packages/db. De agent-logica staat in services/agent. De API staat in services/api. Je hoeft niet te zoeken.
De CI/CD-pipeline is begrijpelijk. Er is een standaard flow voor alle agents. Elke agent kan die flow uitbreiden met agent-specifieke stappen, maar de basis is overal hetzelfde.
Een nieuwe ontwikkelaar die voor het eerst de repo opent, kan binnen een uur de structuur begrijpen. Niet de volledige implementatie, maar de structuur. Waar staat wat. Wie is eigenaar van wat. Hoe worden wijzigingen doorgevoerd.
Hoe het eruitziet als je het organisch laat groeien
Een organisch gegroeide repo is het tegenovergestelde. Er zijn mappen waarvan niemand meer weet waarom ze bestaan. Er is code die op drie plekken staat, licht verschillend, omdat iemand het ooit gekopieerd heeft. Er is een utils-map die alles bevat wat nergens anders past.
De CI/CD-pipeline is een verzameling scripts die in de loop van de tijd zijn toegevoegd. Sommige zijn gedocumenteerd. De meeste niet. Je kunt niet zomaar een nieuwe agent toevoegen zonder eerst te begrijpen hoe de bestaande pipelines werken.
Deployment is eng. Niet omdat de code slecht is, maar omdat je nooit zeker weet wat er nog meer verandert als je iets aanpast.
De kosten van slechte structuur
De echte kosten van slechte structuur zijn onboarding, debugging en deployment.
Onboarding kost tijd die je niet hebt. Een nieuwe ontwikkelaar die drie weken nodig heeft om de codebase te begrijpen is drie weken niet productief. Dat is drie weken vertraging voor het project.
Debugging duurt langer als je niet weet waar iets staat. Een fout in productie die twintig minuten zou kosten om op te lossen duurt twee uur als je eerst moet uitzoeken welke code er verantwoordelijk voor is.
Deployment wordt een risico als de structuur onduidelijk is. Teams gaan voorzichtiger deployen. Ze wachten op rustige momenten. Ze bundelen wijzigingen om het aantal deployments te beperken. Dat vertraagt alles en maakt elke deployment groter en risicovoller.
Concrete tips voor teams die nu in de puinhoop zitten
Als je nu naar je repo kijkt en je herkent de beschrijving van de organisch gegroeide codebase, zijn er een paar dingen die je kunt doen zonder alles opnieuw te schrijven.
Begin met het benoemen van de grenzen. Besluit wat platform is en wat agent is. Schrijf het op. Dat is al de helft van het werk.
Verplaats infra-configuraties naar één plek. Niet in één keer alles, maar begin met de dingen die het meest pijn doen. Secrets beheer is een goed startpunt.
Maak de agent-workspaces expliciet. Als je meerdere agents hebt, geef ze elk een eigen map met een vaste structuur. Het hoeft niet perfect te zijn. Het moet consistent zijn.
Documenteer de structuur nadat je hem hebt ingericht. Niet een uitgebreid document, maar een bestand in de root van de repo dat in vijf regels uitlegt hoe de repo is opgebouwd. Iemand die de repo voor het eerst opent, moet dat bestand als eerste zien.
Refactor incrementeel. Je hoeft de hele repo niet in één sprint te reorganiseren. Elke keer als je een bestand aanraakt, zet je het op de juiste plek. Dat is langzaam, maar het werkt.
De structuur is de communicatie
De repo-structuur is niet alleen technisch. Het is ook hoe je communiceert over wie verantwoordelijk is voor wat, hoe het systeem in elkaar zit, en hoe een nieuwe persoon het kan begrijpen.
Een slechte structuur zegt: dit systeem is historisch gegroeid en niemand heeft ooit de tijd genomen om er over na te denken. Een goede structuur zegt: we weten wat we bouwen, we weten hoe het in elkaar zit, en we hebben er bewust voor gekozen het zo te organiseren.
Dat laatste is geen luxe voor grote teams. Het is de basis voor elk AI-project dat verder wil komen dan de eerste werkende versie.