De Agentische Codebase

Elk hoofdstuk van De Agentische Codebase met het motto uit de gedrukte editie, wat je erna kunt, en wanneer je het nodig hebt.

1. Inleiding

   Inleiding: De repository is het Agent OS

   Een demo bewijst dat het model het werk kán doen; een repository bewijst dat het morgen opnieuw kan. De kloof tussen die twee zinnen is dit boek.

   Wat je erna kunt

   Je gaat begrijpen waarom agentische systemen falen in repositories en niet in modellen. Je leert de ziekte benoemen: agentische repo-schuld. En je vertrekt met STACK, de kaart voor de vijf lagen die elke agentische codebase op orde moet hebben.

   Gebruik dit hoofdstuk wanneer

   Een demo de zaal wint maar een nieuwe collega hem niet kan reproduceren; regels en prompts in chatgeschiedenis wonen; "vraag het de persoon die de setup kent" je onboardingplan is.

2. Hoofdstuk 1

   Het probleem van de agentische repo

   Er crashte niets. Dát was het probleem. Dezelfde agent die in zijn eerste week live de zaal had verbluft, begon in zijn tweede de codebase stilletjes te laten rotten, en stille rot heeft geen stack trace.

   Wat je erna kunt

   Je kunt straks de vier manieren benoemen waarop een ad-hoc agent-setup een repository laat vervallen. Je herkent ze stuk voor stuk in je eigen boom. En je legt uit waarom het geen vier bugs zijn, maar één ontbrekende architectuurlaag.

   Gebruik dit hoofdstuk wanneer

   Je agent draaide perfect in een demo en ging een sprint later misdragen. Of een nieuwe collega kan het gedrag dat iedereen gezien heeft niet reproduceren.

3. Hoofdstuk 2

   STACK: vijf lagen

   Hoofdstuk 1 benoemde vier manieren waarop een agentische repo verrot. Dit hoofdstuk laat zien dat die vier nooit vier problemen waren. Het was één probleem met vier maskers op: vijf soorten niet-code-intelligentie zonder plek om te wonen. STACK is waar elk van die soorten een thuis krijgt, en de kaart die je de rest van dit boek aflegt.

   Wat je erna kunt

   Je kunt straks elke repository afbeelden op vijf benoemde lagen: Structure, Toolchain, Agent configuration, Connection layer, Knowledge and quality. Daarna draai je de STACK-audit die elke laag scoort van afwezig tot geversioneerd-en-getest.

   Gebruik dit hoofdstuk wanneer

   Je een repository erft waar agents al aankomen. Ook wanneer je je eerste agent aan een bestaande codebase wilt toevoegen, of niet kunt zeggen waar prompts, rules en toolcontracten eigenlijk wonen.

4. Hoofdstuk 3

   Structure: indeling en toegangspunten

   Een agent verkent je repository niet. Hij foerageert, en een doolhof int tol op elke verkeerde afslag die geen route kent.

   Wat je erna kunt

   Je kunt straks de voordeur van een repository zo ontwerpen dat een verse agent of nieuwe engineer in de eerste minuut naar de juiste plek navigeert. Je geeft de boom benoemde toegangspunten, betekenisrijke mappen, en een navigatiekaart die elke nieuwe run eerst leest.

   Gebruik dit hoofdstuk wanneer

   Een nieuwe agent je indeling telkens opnieuw afleidt. Of hij vindt code opnieuw uit die al twee mappen verderop staat. Of "waar woont X?" wordt alleen beantwoord door degene die de repo bouwde.

5. Hoofdstuk 4

   Werkruimtes en grenzen

   Een repository die agents kunnen navigeren is de eerste helft van Structure. De tweede helft is scherper: agents moeten kunnen navigeren zonder de helft te laden die ze niet nodig hebben. Op schaal beslist dat of je agents betrouwbaar blijven of koppelingen gaan hallucineren die er nooit waren.

   Wat je erna kunt

   Je kunt straks beslissen waar je een werkruimtegrens trekt. Een agent moet de volledige context van één eenheid kunnen laden, die correct wijzigen, en de overige repository buiten beeld houden. Je leert ook instructies per werkruimte afbakenen onder één root, en de "distributed monolith" herkennen die het contextbudget opblaast.

   Gebruik dit hoofdstuk wanneer

   Je repo voorbij één samenhangend ding is gegroeid. Agents laden te veel code voor kleine wijzigingen, of je kiest tussen een monorepo en losse repo's en wilt een reden die geen kwestie van smaak is.

6. Hoofdstuk 5

   AGENTS.md en CLAUDE.md

   Een repository kan vijf tegenstrijdige beschrijvingen bevatten van hoe hij werkt, en elke agent die ze leest, gehoorzaamt een andere. De remedie is niet een beter instructiebestand. Het is één instructiebestand waar de andere voor buigen.

   Wat je erna kunt

   Je kunt straks één wortelgrondwet schrijven voor je repository: scope, commando's, shell mandate, veiligheidsvloer, quality gates en een repo-kaart. Daarna bedraad je elke agent-tool zo dat hij dat ene bestand leest, niet vijf afdrijvende kopieën.

   Gebruik dit hoofdstuk wanneer

   Je `CLAUDE.md` spreekt een `.cursorrules` tegen die de code tegenspreekt, of je voegt je eerste wortel-instructiebestand toe en wilt dat het goed veroudert in plaats van uit te dijen tot ruis.

7. Hoofdstuk 6

   Regels over tools heen

   Hoofdstuk 5 gaf NexumOS één grondwet. Dit hoofdstuk beantwoordt de vraag die haar binnen een maand breekt: elke tool wil zijn eigen kopie, in zijn eigen map, in zijn eigen dialect. Hoe houd je dan één waarheid overeind als vijf oppervlakken er elk op staan haar vast te houden?

   Wat je erna kunt

   Je gaat je regels versioneren als code, ze per glob afbakenen zodat elke regel alleen laadt waar hij geldt, en één canonieke bron bewaren die de per-tool-kopieën genereert of importeert. Daarmee genees je de regeldrift die de agent uit hoofdstuk 1 op maandag gelijk gaf en op dinsdag ongelijk.

   Gebruik dit hoofdstuk wanneer

   Je team meer dan één agent-tool gebruikt. Je `.cursor/rules` en `CLAUDE.md` spreken elkaar tegen, of je debugde ooit "de agent negeerde onze regel" en vond daarna een tweede regel die de eerste ondermijnde.

8. Hoofdstuk 7

   Agent Skills

   Hoofdstuk 6 leerde je rules nee te zeggen: wat mag een agent waar doen? Dit hoofdstuk leert je repository ja zeggen, met opzet. Je geeft een agent een capaciteit die hij kan laden, lezen, draaien en waartegen hij getest wordt. Een rule is een hek. Een skill is gelabeld gereedschap op de werkbank, zodat de juiste hand er op het juiste moment naar grijpt.

   Wat je erna kunt

   Je kunt straks een prompt die je team uit het hoofd overtypt omzetten in een geversioneerd, reviewbaar en testbaar skill-pakket. Dat pakket is een map met een `SKILL.md`: de description zet hem aan, de body laadt alleen wanneer dat nodig is en een golden test zet het gedrag vast.

   Gebruik dit hoofdstuk wanneer

   Dezelfde instructies elke week opnieuw in de chat worden geplakt. Of wanneer "goede" prompts in iemands hoofd of Slack-draad leven, en niemand kan zien of de wijziging van vorige maand een capaciteit beter of slechter maakte.

9. Hoofdstuk 8

   Rollen en subagents

   Hoofdstuk 7 gaf je repository een bibliotheek aan capaciteiten. Dit hoofdstuk beantwoordt de vraag die een bibliotheek van skills niet kan beantwoorden: wie mag ze oppakken, en wat mag die dan precies doen? Een skill is een bevoegdheid. Een rol geeft die bevoegdheid een aanstelling met een functieomschrijving.

   Wat je erna kunt

   Je vervangt straks de generieke "de agent" door een klein bestand met gecharterde rollen. Elke rol krijgt een mandaat, minimale tools, getypeerde inputs en outputs, plus een expliciet escalatiepad. In runtime wordt dat een subagent met eigen context.

   Gebruik dit hoofdstuk wanneer

   Eén manusje-van-alles support triëert, productie raakt en facturatie schrijft. Gebruik dit ook wanneer incidenten teruglopen naar "de agent had elke tool", of wanneer je sneller parallelle agent-werkers toevoegt dan je reviewproces aankan.

10. Hoofdstuk 9

    Prompts, commando's en workflows

    Hoofdstuk 8 gaf NexumOS een roster van rollen met een charter. Maar een rol benoemt een wie, terwijl een operatie een wat vraagt. De triage-agent heeft nu een mandaat; een script heeft hij nog steeds niet. Dit hoofdstuk schrijft dat script, en schrijft het als code. Want werk dat je agents veertig keer per week doen hoort niet te leven in jouw herinnering aan hoe de demo verliep.

    Wat je erna kunt

    Je verandert je meest herhaalde chatoperatie in een geparametriseerd, geversioneerd commando met een golden test. Daarna rijg je zulke commando's aaneen tot korte workflows met benoemde menselijke controlepunten, niet tot één heroïsche pijplijn.

    Gebruik dit hoofdstuk wanneer

    Je jezelf dezelfde vijfstaps-instructie uit je hoofd ziet overtypen. Of wanneer teamleden elk hun eigen lichtjes afwijkende versie van "zo leveren wij een fix" hebben, terwijl een agent-workflow van vorige maand stilletjes anders is gaan schrijven.

11. Hoofdstuk 10

    Geheugen en contextlagen

    Hoofdstuk 9 leerde je versioneren wat er draait. Dit hoofdstuk leert je besturen wat er blijft. Een commando definieert de operatie; het geheugen beslist wat de agent erin meedraagt. De meest gemaakte fout is alles meedragen, alsof een context window een kast is in plaats van een rekening.

    Wat je erna kunt

    Je schrijft een memory-policy die elk stuk staande context in drie lagen sorteert: hot session, warm project, cold archive. De agent laadt daarna bij elke run de kleinste hoog-signaal-set, niet de grootste die het venster toestaat. Je houdt een kopieerbare lagentabel en een afdwingbaar contextbudget over.

    Gebruik dit hoofdstuk wanneer

    Je agent zichzelf diep in een lange sessie tegenspreekt. Of wanneer een verschaalde beslissing telkens opnieuw opduikt, je root-instructiebestand voorbij twee schermen is gekropen, of je niet kunt zeggen welke context gekozen is en welke louter is aangekoekt.

12. Hoofdstuk 11

    MCP-servers en toolcontracten

    Wat je erna kunt

    Je verandert de tools die je agents aanroepen van kale functies in bestuurde toolcontracten. Elk contract heeft schema, auth, limieten, timeouts, idempotency en benoemde faalmodi. Je neemt ook de zwaarstwegende beveiligingsbeslissing van de hele laag bewust: lokaal versus remote.

    Gebruik dit hoofdstuk wanneer

    Je agents MCP-servers aanroepen waar niemand een spec voor schreef. Of wanneer een tool in iemands persoonlijke config leeft, niemand de scope kan noemen, of een werkende tool stilletjes iets anders is gaan doen.

13. Hoofdstuk 12

    Hooks en guardrails

    Een contract verklaart wat een tool mag doen. Het belet niet dat de tool gevraagd wordt iets anders te doen.

    Wat je erna kunt

    Je haalt de ene invariant die elke run moet gelden uit proza dat het model mag opvolgen. Daarna zet je hem in een deterministische hook die op het event vuurt en valideert wat het model ook koos. Deze week schrijf, test en lever je je eerste PreToolUse-poort.

    Gebruik dit hoofdstuk wanneer

    Een regel in je `CLAUDE.md` zegt "nooit force-pushen," "altijd tests draaien voor het committen," of "blijf van `.env` af." Je hebt de agent het toch zien doen, of je kunt je niet veroorloven dat hij het doet.

14. Hoofdstuk 13

    Plugins en marketplaces

    Een skill die je zelf schrijft is code die je vertrouwt omdat jij hem schreef. Een geïnstalleerde plugin is code die je vertrouwt omdat iemand anders hem schreef. De agent die hem draait houdt jouw credentials en een shell vast. Dit hoofdstuk dicht het gat tussen die zinnen.

    Wat je erna kunt

    Je stopt met capaciteit van derden installeren op gevoel. Je cureert die capaciteit als de supply-chain-afhankelijkheid die ze is: elke plugin scoren tegen een zesdimensionale rubriek, vastpinnen wat je houdt, en forken wat je niet kunt vastpinnen.

    Gebruik dit hoofdstuk wanneer

    Een teamlid dropt een "dit moet je proberen"-plugin in het kanaal. Een marketplace-listing belooft precies het ding dat je net wilde bouwen, of je beseft dat je niet kunt aanwijzen waar de agents in je team hun extra tools vandaan halen.

15. Hoofdstuk 14

    Shells en ReasonKit-tools

    Hoofdstuk 13 leerde je een plugin te beoordelen vóór je hem installeert. Elke plugin die je installeert, elke skill die hij meebrengt, elke tool die hij blootstelt, eindigt op dezelfde manier: hij draait een commando in een shell. De shell is de ruimte waarbinnen dat allemaal wordt uitgevoerd, en de meeste teams hebben nooit beslist wat die ruimte bevat. Dit hoofdstuk richt hem in.

    Wat je erna kunt

    Je verklaart de shell en CLI-vloer van je repository als geversioneerde config. Een mens of agent kan die vloer vanuit een verse checkout reproduceren.

    Gebruik dit hoofdstuk wanneer

    Een commando werkt op jouw laptop en faalt elders. Gebruik dit ook wanneer een agentpijplijn breekt door een andere CLI-versie, of wanneer niemand het verwachte shell-oppervlak kan aanwijzen.

16. Hoofdstuk 15

    Integraties, evals en CI voor agents

    Een groene testsuite is de enige zin in een codebase die zegt "dit werkt nog steeds" en die je kunt vertrouwen. Rule-bestanden en skill-bestanden hebben dat nooit mogen zeggen. Dit hoofdstuk verandert dat.

    Wat je erna kunt

    Je gaat `AGENTS.md`, rules en skills behandelen als de ongeteste productiecode die ze al zijn. Aan elk hang je een golden-task-eval. De merge poort je op slagingspercentage en kostenbudget. Agent-runs lees je via gestandaardiseerde traces, zodat een "onschuldige" bewerking gedrag niet langer stilletjes laat regresseren.

    Gebruik dit hoofdstuk wanneer

    Je niet kunt zeggen of de rule-aanpassing van vorige week de agent beter of slechter maakte. Of een eenregelige promptwijziging stilletjes een workflow brak. Of je enige test van "hielp dit" is of de volgende demo goed voelt.

17. Hoofdstuk 16

    Vibe coding versus productiediscipline

    Niet snelheid bedreigt de onderhoudbaarheid, maar snelheid in de verkeerde container. Dit hoofdstuk geeft die verkeerde container een gesanctioneerde vorm en een deur die alleen door de poorten heen opengaat.

    Wat je erna kunt

    Je stopt met snelheid en discipline als een keuze te behandelen. Je gaat ze behandelen als twee modi met twee territoria. De snelle, verkennende modus krijgt een gesanctioneerde baan die de invarianten van de hoofdrepo nooit raakt. De gepoorte modus beslist wat er merget. Zo kun je op volle snelheid vibe-coderen en toch een stack uitleveren die niet verrot.

    Gebruik dit hoofdstuk wanneer

    Je in de verleiding komt om de poorten "deze ene keer" over te slaan om je momentum te houden. Of wanneer een agent-spike zo goed lijkt dat je hem rechtstreeks naar main wilt mergen. Of wanneer je repo trager wordt omdat elke snelle winst een beetje schuld achterliet.

18. Conclusie

    Conclusie: Onderhoud de stack

    Een demo bewijst dat het model het werk één keer kan doen. Een geversioneerde stack bewijst dat het werk de mensen overleeft die het bouwden en het model dat hen verving. Dit boek was de afstand tussen die twee zinnen; dit hoofdstuk is de gewoonte die je op de tweede houdt.

    Wat je erna kunt

    Je vertrekt met een onderhoudsgewoonte, geen eindstreep. De STACK-audit is één keer voltooid voor NexumOS en staat op een cadans voor je eigen repo. Zo blijven de vijf lagen geversioneerd in plaats van stilletjes terug te verrotten tot folklore.

    Gebruik dit hoofdstuk wanneer

    Je de stack hebt gebouwd (structure, configuratie, connecties, kennis) en hem nu in leven moet houden door modelupgrades, nieuwe teamgenoten en de trage drift van honderd kleine "heel even dan"-shortcuts heen.