STACK: versioneer het agent-OS zoals je de app versioneert

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.

Het signaal is reproduceerbaar falen. Een tweede engineer krijgt op een tweede machine niet hetzelfde agentgedrag. Een modelupgrade verandert diffs en niemand kan het bestand aanwijzen dat dat toeliet. Een tool kan een klant mailen en het enige spoor is een vendor-dashboard dat verloopt. Demokwaliteit is geen repokwaliteit.

Wat is STACK? is de definitie van de vijf namen. Deze pagina is de installatie: behandel het agent-OS als code.

Vijf lagen

STACK is de kaart die ik gebruik:

1. Structuur. De enige plek waar agent-artefacten leven, nergens anders.
2. Toolchain. De hosts en runners, vastgezet, niet simpelweg “wat er toevallig op de laptop staat.”
3. Agent-configuratie. Mandaten, prompts en skills, altijd met eigenaren.
4. Connectie. MCP en andere contracten voor tools. Zichtbaarheid, mutatie, logs.
5. 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 commitmessage.

Benoem per laag een eigenaar. Eén mens, geen rol. Een rol is hoe het bestand de week dat die persoon vrij is weer folklore wordt. CODEOWNERS is genoeg. Een wikipagina is dat niet.

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.

Een praktische snede. Structuur is één directory, bijvoorbeeld agent-os/, met een README die een kaart is, geen essay. Toolchain is een lockfile plus een gedocumenteerde commandolijst die het CI-image ook heeft. Agent-configuratie zijn de staande bestanden die een host daadwerkelijk leest, met een CODEOWNERS-regel, geen tweede kopie in een chat. Connectie is een contract per server: wat hij mag zien, wat hij mag wijzigen, hoe de aanroep wordt gelogd. Kennis en kwaliteit is minstens één eval of test die faalt als de agent een verboden pad aanraakt.

Rollback is het deel dat teams overslaan. Kun je een prompt niet terugdraaien zoals je een functie terugdraait, dan heb je hem niet geversioneerd. Je hebt hem gepubliceerd. Git is de versiebeheer. Een Notion-pagina met “latest” in de titel is dat niet.

Wat je weigert

Drie veelvoorkomende installs die de schuld toch laten staan.

Een host met “memory” aan en geen bestand in de repo. De staande context woont nu bij een vendor. Verloopt de stoel, dan verloopt het OS.

Vijf kopieën van dezelfde regel, “in sync” gehouden met de hand. Ze zullen drijven. Kies één bestand. Verwijder de rest in dezelfde PR.

Een MCP-server toegevoegd omdat een demo een tool nodig had, met het contract “later.” Later is hoe de billingmodule een comment-bot krijgt. 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.

Een maandag die je echt kunt draaien

1. Zet elk bestand op een lijst dat een agent bij een koude start leest. Is de lijst langer dan één boom, dan heb je Structure-schuld.
2. Draai de agent in CI, niet alleen op een laptop. Kan CI hem niet draaien, dan is Toolchain een verhaal.
3. Zet een menselijke naam naast elke staande prompt en skill. Lege naam betekent: het bestand is van niemand. Bestanden zonder eigenaar gaan niet mee.
4. Schrijf per MCP-server zichtbaarheid, mutatie, log in drie regels. Ontbrekende mutatie betekent: hij gaat niet live.
5. Voeg één test toe die faalt als de agent een pad bewerkt dat hij niet mag raken. Dat is het begin van Kennis en kwaliteit, niet het eind.

Je maakt het OS op maandag niet af. Je stopt folklore bij de eerste eigenaar.

Waar dit in past

The Agentic Codebase is het boek. De introductie is het lanceerartikel. Wat is STACK? is de definitie. Deze pagina beschrijft de architectuur die je installeert nadat de demo vlekkeloos werkte, maar de repo een puinhoop werd.

Een CHORUS-charter redt geen repo waarvan de regels in vijf tools leven. STACK versioneert de bestanden. CHORUS benoemt de coördinatie die die bestanden alleen niet aankunnen.

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.