Hoe leg je beslissingen vast zodat AI ze later begrijpt?

Kort antwoord

Leg elke beslissing vast in een vaste vorm: de context, het besluit, de status en de gevolgen, met een datum. Ontwikkelaars kennen dat als Architecture Decision Record. Het waarom is het belangrijkste deel: zonder reden kan een AI, net als een nieuwe collega, een besluit alleen blind volgen of blind terugdraaien. Vervangen besluiten markeer je als vervallen in plaats van ze te wissen.

Het besluit staat er, het waarom niet

De meeste teams vinden hun besluiten wel terug: in een mail, een notulen, een regel in een handboek. Wat bijna altijd ontbreekt, is de reden. “We werken niet meer met leverancier X.” Waarom niet? Was het de prijs, de levertijd, een ruzie, een fout in een factuur? Een AI die die regel tegenkomt, weet niet of hij moet gelden voor een spoedorder, voor een ander product, of nog na drie jaar.

Michael Nygard beschreef dit probleem in 2011 voor softwareteams. Een nieuwe collega die een besluit tegenkomt zonder de reden, heeft twee keuzes: het besluit “blind accepteren” of het “blind veranderen”. Beide zijn slecht. Een AI-tool zit in precies dezelfde positie, alleen leest hij meer en vraagt hij niets na.

Een vaste vorm per besluit

Nygards vorm, het Architecture Decision Record, is kort en werkt ook buiten software:

Onderdeel Wat erin staat Voorbeeld
Titel Het besluit in een korte zin Spoedorders alleen via de binnendienst
Context Wat er speelde, welke krachten er waren Twee keer een spoedorder vergeten door de webshop; klanten belden toch al
Besluit Wat we doen, in actieve vorm “Spoedorders nemen we alleen telefonisch aan, via de binnendienst.”
Status Voorgesteld, geaccepteerd, vervangen Geaccepteerd per 1 maart 2026
Gevolgen Wat er makkelijker en moeilijker wordt Binnendienst krijgt meer telefoon; webshop toont spoedmelding

De site adr.github.io beschrijft een ADR als het vastleggen van één belangrijke keuze met de reden erbij, en de verzameling van alle records als de decision log van een team.

Zo begin je

  1. Kies welke besluiten tellen. Alles wat een collega of AI later anders zou doen als hij het niet weet: afspraken met klanten, uitzonderingen, gekozen werkwijzen, afgevallen opties.
  2. Eén besluit per record. Kort, een halve pagina is genoeg.
  3. Altijd een datum en een status. Zonder datum weet niemand of het nog geldt.
  4. Vervang, wis niet. Komt er een nieuw besluit, zet dan bij het oude “vervangen door” en een verwijzing. Nygard raadt dat expliciet aan.
  5. Bewaar het waar gezocht wordt. Bij de klant, het project of het proces waar het over gaat, niet in een losse map die niemand opent.

Het misverstand: de AI vindt het wel in de mail

Moderne AI-tools kunnen mail en documenten doorzoeken, dus waarom nog vastleggen? Omdat een besluit in een mailwisseling zelden op één plek staat. Het voorstel staat in de ene mail, de twijfel in een andere, het definitieve “ja, zo doen we het” in een Teams-bericht. Een AI die zoekt, vindt misschien het voorstel en mist het besluit, of vindt het besluit van vorig jaar en mist dat het is teruggedraaid.

Tijd is daarbij het lastigste. Systemen die met kennis werken, lossen dat steeds vaker op door elk feit een periode te geven waarin het gold. Graphiti, een open-source kennisgraaf, maakt oude feiten volgens zijn eigen documentatie “ongeldig, niet verwijderd”, zodat je kunt vragen wat nu geldt en wat op een eerder moment gold. Een decision log met status en datum doet met de hand hetzelfde.

Wat dit voor een team betekent

Een besluit dat niet is vastgelegd, vertrekt met de persoon die het nam. Zie Wat gebeurt er met de AI-kennis als een medewerker vertrekt? En een besluit dat in iemands persoonlijke ChatGPT-geheugen staat, helpt de collega met Copilot niet. Veel besluiten vallen in vergaderingen; hoe je die vastlegt staat in Hoe maak je wat in vergaderingen besloten wordt bruikbaar voor AI?

Waar Bombos past

Bombos legt besluiten en geleerde regels vast met hun bron en de context waarin ze gelden, zoals één klant of één proces, en haalt ook op wat er al in mail, documenten en repo’s ligt. Elke AI-tool van het team, Claude, ChatGPT, Copilot, Grok, Claude Code, Codex, Cursor en eigen agents, leest uit dezelfde plek, en je ziet waarop een antwoord rust. Eén persoon kan het eerst voor zichzelf proberen.

Vragen die hierbij horen

Wat is een Architecture Decision Record?

Een kort document dat één belangrijke ontwerpkeuze vastlegt, met de reden en de gevolgen. Michael Nygard beschreef de vorm in 2011. De verzameling van alle records heet een decision log.

Werkt dit ook buiten softwareontwikkeling?

Ja. De vorm past op elk besluit dat later uitleg nodig heeft: een leverancier die afvalt, een prijsafspraak met een klant, een vaste werkwijze voor spoedorders. Het principe is hetzelfde: wat, waarom, sinds wanneer, en wat het betekent.

Moet ik oude besluiten verwijderen?

Nee. Nygard raadt aan een vervangen besluit te laten staan en als vervangen te markeren. Zo blijft zichtbaar waarom het ooit zo was, en weet een AI dat het niet meer geldt.

Bronnen

  1. Michael Nygard: Documenting Architecture Decisions (Cognitect, 2011)
  2. Architectural Decision Records (adr.github.io)
  3. Graphiti (GitHub)
Het eerste half uur · kosteloos

Wat vergeet jullie AI?

  1. 01Je vertelt welke AI jullie gebruiken en waar het steeds opnieuw moet.
  2. 02We laten zien wat een gedeeld geheugen daar verandert, op jullie eigen voorbeelden.
  3. 03Je krijgt het plan mee. Dat houd je, ook zonder Bombos.
Piet Baudoin
Piet BaudoinJe spreekt Piet, van het team van BombosNederlands team uit Utrecht en Nijmegen · data in Europa
We reageren dezelfde werkdag.