Agents geven prachtige demo’s. Daarna begint de repository te stinken. Prompts in vier verschillende bestanden. Dezelfde regel in een README, een host-configuratie en in iemands hoofd. Een MCP-server die nergens gedocumenteerd staat. Die stank heeft een naam: agentic repo-schuld.
De ziekte
Een zwak model is zelden de oorzaak. Het echte probleem is een agent-OS dat niet als besturingssysteem is gebouwd. Het is een stapel losse onderdelen.
Applicatiecode zou je nooit op die manier live zetten. Je versioneert de app. Je laat de code reviewen. Je weet exact wie eigenaar is van een package. De helft van de repo waar de agent in leeft, verdient diezelfde afkeer voor aannames en losse verhalen.
Vijf lagen
STACK is de kaart die ik gebruik:
- Structuur — de enige plek waar agent-artefacten leven, nergens anders.
- Toolchain — de hosts en runners, vastgezet, niet simpelweg “wat er toevallig op de laptop staat.”
- Agent-configuratie — mandaten, prompts en skills, altijd met eigenaren.
- Connectie — MCP en andere contracten voor tools. Zichtbaarheid, mutatie, logs.
- Kennis en kwaliteit — wat de agent als waarheid mag zien, plus de tests die een slechte wijziging direct afkeuren.
Als een wijziging niet onder een van deze lagen valt, hoort die ook niet thuis in de beschrijving van je PR. “De agent een beetje aangepast” is geen geldige commit message.
Versioneer het
Behandel prompts, skills en servercontracten exact als code.
- Ze horen in de repo thuis.
- Ze hebben reviewers.
- Er is een mogelijkheid tot rollback.
- De override-doctrine is een vastgelegd bestand, geen vage herinnering in Slack.
Wanneer een tool iets kan versturen, geld kan uitgeven of data kan verwijderen, staan er bij de eerste tien aanroepen een menselijke naam naast. Daarna vormt de log de review. Zonder log is er geen tool.
Waar dit in past
The Agentic Codebase is het boek. De introductie is het lanceerartikel. Deze pagina beschrijft de architectuur die je installeert nadat de demo vlekkeloos werkte, maar de repo een puinhoop werd.
MCP uitgelegd voor ondernemers is het complementaire stuk voor de connectielaag. Lees dat voordat je een server koppelt die een mail naar een klant kan sturen.
Als je deze week maar één ding doet: kies één specifieke map uit als je agent-OS, verplaats de rondslingerende prompts daarheen en zet een naam op de CODEOWNERS-regel. Folklore stopt bij de eerste eigenaar.