AI4

Agent-ready documentatie & context

Kennis is zo vastgelegd dat mens én agent er goed werk mee leveren. Voor een agent is documentatie infrastructuur: zonder context gaat hij raden.

Volwassenheidsniveaus

Van basis naar strategisch verankerd.

  1. Basis

    Documentatie ontbreekt of is verouderd. Kennis zit in hoofden, en elke agentsessie begint bij nul.

  2. Verkennend

    Er zijn losse README's, prompts of rules files, bijgehouden door individuen. Documentatie voor mensen en voor agents leeft apart en loopt uit elkaar.

  3. Toepassend

    Elke repo heeft agent-instructies (AGENTS.md/CLAUDE.md) in versiebeheer. Documenten zijn gelaagd en dienen beide lezers: BLUF bovenaan voor de mens, detail eronder voor de agent.

  4. Geïntegreerd

    Documentatie wordt beheerd als infrastructuur: met eigenaarschap, vaste structuur, skills die over teams heen gedeeld worden en MCP-koppelingen. Een agentfout leidt tot een doc-update.

  5. Strategisch

    Organisatiekennis (domein, ADR's, standaarden) is voor mens en agent ontsloten over teams heen. Agents houden documentatie actueel en signaleren gaten; mensen vinden in seconden de kern.

Aandachtspunten

Begrippen en risico's om mee te wegen.

Agent-instructies
Een bestand in de repo dat een agent bij elke sessie leest, zoals AGENTS.md of CLAUDE.md. Het beschrijft hoe je bouwt en test, welke conventies gelden en wat verboden terrein is.
Skill
Een vastgelegde werkwijze die een agent op verzoek uitvoert, zoals een release of een review. Zo gaat herhaalbaar werk elke keer op dezelfde manier.
MCP
Model Context Protocol, een standaard waarmee agents actuele bronnen raadplegen, zoals tickets, wiki's en databases.
ADR
Architecture Decision Record, de vastgelegde reden achter een architectuurkeuze.

Verbeterstappen

Concrete acties om per niveau door te groeien.

BasisVerkennend

agents krijgen de eerste vaste context.

  1. Schrijf per repo een agent-instructiebestand

    Hoe bouw en test je, welke conventies gelden, wat is verboden terrein. Een half A4 volstaat.

  2. Leg vast wat je de agent steeds opnieuw vertelt

    Elke correctie die je twee keer geeft, hoort erin.

  3. Beschrijf de architectuur in één diagram of alinea

    Dan zet de agent code op de goede plek.

VerkennendToepassend

context is gedeeld, consistent en in versiebeheer.

  1. Neem agent-instructies op in de Definition of Done

    Verandert een conventie, dan verandert het bestand mee in dezelfde PR.

  2. Standaardiseer de opbouw over repo's

    BLUF, bouwen, testen, conventies, valkuilen, detail.

  3. Schrijf gelaagd met vaste koppen

    De kern bovenaan voor de mens, de diepte eronder voor de agent.

  4. Houd één bron voor mens en agent

    Laat agent-instructies verwijzen in plaats van kopiëren.

ToepassendGeïntegreerd

documentatie wordt beheerd als infrastructuur.

  1. Wijs eigenaren toe aan agentcontext

    Zonder eigenaar veroudert het, net als een pipeline.

  2. Bundel herhaalbaar werk in gedeelde skills

    Release, migratie en review op één manier, voor elk team.

  3. Ontsluit bronnen via MCP

    Agents halen actuele context op, binnen de datagrenzen van capability 5.

GeïntegreerdStrategisch

kennis is een levend, organisatiebreed asset voor mens en agent.

  1. Maak ADR's en domeinkennis machine-leesbaar

    Vaste structuur, zodat agents ze vinden en toepassen.

  2. Laat agents documentatie onderhouden

    Ze stellen updates voor als code en documentatie uit elkaar lopen; de mens keurt goed.

  3. Meet de kwaliteit van context

    Elke correctie op iets dat gedocumenteerd had moeten zijn, wijst een gat aan.

Hier helpen we bij

Zo werken we met teams aan deze capability.

Weten waar jullie staan?

De audit meet alle 35 capabilities, ook deze.

Begin met de quick scan

In een paar minuten een eerste beeld van waar jullie team staat, gratis en anoniem.

Doe de quick scan