Beslisregistraties voor AI-gestuurde softwareontwikkeling

Beslissingenregistraties vormen de ontbrekende geheugelaag in AI-gestuurde softwareontwikkeling. Ze vastleggen niet alleen wat er is gebouwd, maar ook waarom — en dat onderscheid wordt cruciaal wanneer AI-tools je code schrijven.

Beslissingenregistraties vormen de ontbrekende geheugelaag

AI-gedreven programmeren verandert de economie van softwareontwikkeling door code goedkoper te maken om te genereren, eenvoudiger te refactoren en sneller weg te gooien. Dat is nuttig. Het is ook gevaarlijk, omdat wanneer code makkelijker te produceren is, de schaarste niet langer typen is — de schaarste is oordeel.

Waarom koos het team voor PostgreSQL in plaats van DynamoDB? Waarom vereist het product een menselijke controle voordat AI-gegenereerde e-mails worden verzonden? Waarom toont de interface suggesties in een zijpaneel in plaats van ze direct toe te passen? Waarom werd een eenvoudigere aanpak zes maanden geleden afgewezen? De code kan laten zien wat er bestaat, maar zelden uitleggen waarom het bestaat.

Beslissingenregistraties lossen dit probleem op door een kort, versiebeheerd document te bieden dat een belangrijke keuze vastlegt, de context erachter, de overwogen alternatieven en de consequenties die het team aanvaardde. In een AI-gestuurde codebase worden deze registraties meer dan documentatie — ze worden duurzaam projectgeheugen dat zowel mensen als AI-programmagelezen kunnen lezen voordat ze toekomstige wijzigingen aanbrengen. De praktische werkregel is eenvoudig: houd beslissingenregistraties als Markdown-bestanden in de repository, review ze als code en laat toekomstige AI-tools ze lezen voordat ze wijzigingen voorstellen of implementeren.

Wat zijn beslissingenregistraties?

Een beslissingenregistratie is een schriftelijk verslag van een betekenisvolle beslissing, gestructureerd om vier basisvragen te beantwoorden: wat hebben we besloten, waarom hebben we dat besloten, welke alternatieven hebben we overwogen en welke consequenties hebben we aanvaard? De meest voorkomende vorm is de Architectuurbeslissingregistratie, afgekort tot ADR. ADR’s worden veel gebruikt om technische beslissingen te documenteren, en hetzelfde patroon kan worden uitgebreid naar product- en ontwerpwerk.

Voor AI-gedreven programmeren zijn drie types bijzonder nuttig:

Samen beschrijven ADR’s, PDR’s en DDR’s niet alleen de structuur van het systeem, maar ook de intentie van het product en de redenering achter de gebruikerservaring. Die combinatie is belangrijk omdat AI-agenten code kunnen lezen, maar code alleen niet genoeg context bevat om goede beslissingen te nemen. Beslissingenregistraties geven AI-systemen een gereviewd, duurzaam, menselijk goedgekeurd bron van projectintentie.

Architectuurbeslissingenregistraties

Architectuurbeslissingenregistraties vangen technische en structurele beslissingen op. Gebruik een ADR wanneer een beslissing de vorm van het systeem beïnvloedt — zijn grenzen, afhankelijkheden, operationele model of langetermijn-onderhoudbaarheid.

Voorbeelden van beslissingen die het waard zijn om als ADR te worden vastgelegd, zijn:

• Het kiezen van PostgreSQL als primaire database
• Het gebruik van een event-gedreven architectuur voor achtergrondverwerking
• Het behouden van de applicatie als een modulaire monoliet
• Het introduceren van een wachtrij voor berichten
• Het kiezen van REST in plaats van GraphQL
• Het gebruik van server-side rendering voor de webapplicatie
• Het vereisen dat alle achtergrondtaken idempotent zijn
• Het aannemen van een specifiek authenticatie- en autorisatiemodel

Een ADR is geen volledig architectuurdocument — het is opzettelijk klein, en legt één belangrijke beslissing vast op een specifiek moment in de tijd. Een goede ADR voorkomt architectuuramnesie: zonder het kunnen toekomstige bijdragers dezelfde afwegingen opnieuw ontdekken, oude debatten heropenen of per ongeluk belangrijke beperkingen ongedaan maken.

In AI-gedreven programmeren hebben ADR’s nog meer gewicht. AI-tools zijn vaak bedreven in lokale optimalisatie, en ze kunnen een technisch plausibele wijziging voorstellen die een grotere architectuurbeperking schendt. Een ADR geeft de AI een duidelijke grens: “Zo moet dit systeem gevormd zijn.”

Productbeslissingenregistraties

Productbeslissingenregistraties vangen productgedrag, scope en gebruikersgerichte intentie op. Dit komt minder vaak voor dan ADR’s, maar het is vaak net zo waardevol — productbeslissingen zijn vaak verspreid over tickets, roadmappingtools, chatthreads, vergadernotities en het geheugen van mensen, waardoor ze voor mensen makkelijk te vergeten zijn en voor AI-tools bijna onmogelijk betrouwbaar af te leiden.

Gebruik een PDR wanneer een beslissing beïnvloedt wat het product doet, wie het bedient, wat opzettelijk buiten scope valt of hoe een gebruikersgerichte functie zich moet gedragen. Voorbeelden zijn:

• AI-gegenereerde berichten moeten concepten blijven tot ze door een mens zijn gereviewd
• Gebruikers van het gratis tarief kunnen maximaal drie projecten aanmaken
• Verwijderde workspaces zijn 30 dagen terug te halen
• Teamfacturatie valt buiten scope voor versie 1
• Gebruikers kunnen hun gegevens exporteren zonder contact op te nemen met support
• AI-samenvattingen met lage betrouwbaarheid tonen een waarschuwing in plaats van verborgen te worden

Een PDR is vooral nuttig wanneer een productkeuze uit de code willekeurig lijkt. De code kan een limiet van drie projecten voor gratis gebruikers bevatten, en zonder een PDR kan een AI-tool dat aantal behandelen als een magische constante en voorstellen om het te wijzigen. Met een PDR kan de AI zien dat de limiet verbonden is aan prijsstrategie, onboardingkosten of supportlast — en dat het wijzigen een bewuste productbeslissing vereist, geen snelle editie.

Ontwerpbepalingenregistraties

Ontwerpbepalingenregistraties vangen gebruikerservaring, interactie, visuele en contentontwerpbeslissingen op. Gebruik een DDR wanneer een beslissing beïnvloedt hoe gebruikers met het product interacteren, hoe informatie wordt gepresenteerd of hoe een ontwerpprincipe moet worden toegepast in toekomstig werk.

Voorbeelden van ontwerpbeslissingen die het waard zijn om vast te leggen, zijn:

• Gebruik inline validatie in plaats van validatie alleen bij verzenden
• Plaats AI-suggesties in een zijpaneel in plaats van direct in de editor
• Gebruik progressieve openbaarmaking voor geavanceerde instellingen
• Vereis bevestiging voordat destructieve acties worden uitgevoerd
• Gebruik “Concept” en “Gepubliceerd” in plaats van “Inactief” en “Actief”
• Houd primaire acties zichtbaar op mobiele schermen

Ontwerpintentie is makkelijk te verliezen tijdens implementatie. Een ontwikkelaar kan een flow vereenvoudigen, of een AI-agent kan een component genereren die technisch werkt maar het beoogde interactiemodel breekt. Bijvoorbeeld, een DDR kan vastleggen: “We tonen AI-schrijfsuggesties naast het document, niet erin, omdat gebruikers gegenereerde tekst moeten vergelijken met hun eigen concept voordat ze wijzigingen accepteren.” Die registratie geeft toekomstige bijdragers een principe om te behouden, niet alleen een lay-out om te kopiëren.

Waarom beslissingenregistraties belangrijker zijn met AI

AI-programmatools zijn krachtig, maar ze zijn vaak stateless of slechts gedeeltelijk bewust van projectgeschiedenis. Ze kunnen bestanden inspecteren, patronen afleiden en wijzigingen genereren — maar ze weten niet automatisch welke beslissingen intentioneel zijn, welke per ongeluk, en welke al zijn gedebatteerd en opgelost. Dit creëert verschillende specifieke risico’s.

AI kan besloten debatten heropenen

Als het team al besloot om een modulaire monoliet te gebruiken, kan een AI-agent nog steeds voorstellen om een service te extraheren omdat dat geïsoleerd schoon oogt. Zonder een ADR heeft de AI geen duurzame manier om te weten dat het team dat pad al overwoog en afwees, en het resultaat is verspilde inspanning of een subtiele regressie in systeemcoherentie.

AI kan lokaal optimaliseren en globaal schade aanrichten

Een gegenereerde refactor kan één bestand schoner maken terwijl het systeemgrenzen schendt. Een UI-wijziging kan componentcomplexiteit verminderen terwijl het de beoogde gebruikerservaring verzwakt. Een productwijziging kan de implementatie vereenvoudigen terwijl het prijs- of compliance-aannames breekt. Beslissingenregistraties geven de AI een groter referentiekader voordat het handelt op nauw omschreven signalen.

AI kan code behouden maar intentie verliezen

Een model kan bestaande patronen in de codebase volgen, maar patronen zijn niet hetzelfde als principes. Soms is bestaande code een compromis. Soms is het overgangsfase. Soms bestaat het vanwege een externe beperking die niet zichtbaar is in het bestand. Beslissingenregistraties verklaren het verschil tussen “dit is hoe het werkt” en “dit is waarom het zo is gebouwd.”

AI kan plausibele maar verkeerde redenering genereren

AI kan beslissingenregistraties opstellen, maar het kan ook zelfverzekerd klinkende verklaringen verzinnen die niet overeenkomen met de echte beslissing. Dit is waarom menselijke review ononderhandelbaar is: AI kan het eerste concept van een registratie genereren, maar een mens moet verifiëren dat het de daadwerkelijke beslissing, alternatieven en consequenties nauwkeurig beschrijft voordat de registratie wordt samengevoegd.

Beslissingenregistraties als onderdeel van een bredere methodologie

Beslissingenregistraties zijn niet zomaar documentatie — ze zijn onderdeel van een bredere manier van werken die op het snijpunt zit van lichtgewicht architectuurgovernance, docs as code, AI-augmented knowledge management workflows, productdiscoverie, ontwerpredenering, AI-governance en code review. Een nuttige manier om het grotere proces te beschrijven is Beslissingsgerichte Ontwikkeling.

De meeste AI-gedreven programmeren workflows focussen smal op de genereren-review-commit cyclus:

Die cyclus is te dun voor serieus systeemwerk. Een sterkere workflow behandelt de repository als een opslagplaats voor zowel code als intentie — de diagrammen hier gebruiken Mermaid, een lichtgewicht formaat dat ook goed werkt binnen Markdown beslissingenregistraties:

Dit proces maakt van de repository meer dan een codeopslagplaats. Het wordt de bron van waarheid voor implementatie, intentie en redenering — een duurzaam artefact dat met elke genomen beslissing waarde accumuleert.

Beslissingenregistraties en docs as code

Beslissingenregistraties werken het best wanneer ze volgen docs-as-code principes, wat betekent dat ze in dezelfde repository als de code moeten worden opgeslagen, geschreven in gewone Markdown, gereviewd in pull requests, versiebeheerd met Git, gekoppeld aan gerelateerde issues en pull requests, en zoekbaar door zowel mensen als AI-tools. Dit is veel betrouwbaarder dan het opslaan van belangrijke beslissingen in chat, wiki-pagina’s, presentaties of vergadernotities — die tools kunnen nog steeds nuttig zijn voor discussie, maar de aanvaarde beslissing moet altijd dicht bij de code leven.

Een goed georganiseerde repositorystructuur voor beslissingenregistraties kan er zo uitzien:

docs/
  decisions/
    architecture/
      0001-use-postgresql-for-primary-storage.md
      0002-keep-billing-inside-the-core-app.md
    product/
      0001-ai-generated-email-requires-human-review.md
      0002-free-tier-project-limit.md
    design/
      0001-use-inline-validation.md
      0002-place-ai-suggestions-in-side-panel.md

Voor kleinere projecten werkt een vlakke structuur net zo goed. De exacte maporganisatie is minder belangrijk dan consistentie — de registraties moeten makkelijk te vinden zijn, makkelijk te reviewen en makkelijk voor AI-tools te laden als context voordat ze handelen op de codebase. Voor Go-teams past deze docs/decisions/ structuur natuurlijk naast de cmd/, internal/, en api/ lay-out beschreven in Go Project Structuur: Praktijken & Patronen, die docs/ aanbeveelt als thuis voor architectuurbeslissingen en API-referenties.

Een praktische beslissingenregistratie sjabloon

Een nuttige beslissingenregistratie sjabloon moet kort genoeg zijn zodat mensen hem daadwerkelijk gebruiken. Hier is een praktische Markdown sjabloon die een optionele maar waardevolle AI-richtlijnsectie bevat:

# Beslissing: Korte titel

Status: Voorgesteld | Geaccepteerd | Vervangen | Verouderd
Datum: YYYY-MM-DD
Type: Architectuur | Product | Ontwerp
Eigenaren: Team of namen

## Context

Beschrijf het probleem, beperkingen, doelen, gebruikersbehoeften, technische feiten,
en bedrijfsfactoren die leiden tot deze beslissing.

## Beslissing

Stel de beslissing duidelijk.

## Overwogen alternatieven

### Optie 1

Voordelen:
- ...

Nadeelen:
- ...

## Consequenties

Beschrijf wat makkelijker wordt, wat moeilijker wordt, en welke risico's
of follow-up werk dit creëert.

## AI-richtlijn

Wanneer een AI-assistent in dit gebied werkt, moet het:
- Behouden ...
- Vermijden ...
- Voorkeuren ...
- Vragen om review wanneer ...

## Links

- Gerelateerde issues:
- Gerelateerde pull requests:
- Gerelateerde bestanden:
- Vervangt:
- Vervangen door:

De “AI-richtlijn” sectie is optioneel, maar voor AI-gedreven programmeren is het extreem waardevol — het maakt van de beslissingenregistratie een duurzame instructie voor toekomstige agenten die in hetzelfde gebied van de codebase werken.

Wat hoort in een beslissingenregistratie?

Niet elke keuze verdient een registratie, en als elke kleine implementatiedetail een beslissingenregistratie wordt, stort het proces in lawaai. Maak een beslissingenregistratie wanneer een keuze betekenisvol is en waarschijnlijk later van belang zal zijn.

Goede kandidaten zijn beslissingen die:

• Meerdere delen van het systeem beïnvloeden
• Een productbelofte coderen
• Een echt debat oplossen
• Een langetermijnafweging introduceren
• Afhankelijk zijn van bedrijfs-, compliance- of operationele beperkingen
• Duurzaam zouden zijn om later opnieuw te ontdekken
• Toekomstige AI-tools plausibel verkeerd zouden kunnen interpreteren
• Toekomstige bijdragers zouden kunnen proberen casual om te keren

Slechte kandidaten zijn kleine refactorkeuzes, voor de hand liggende bugfixes, tijdelijke experimenten, lokale naamkeuzes en implementatiedetails zonder blijvende consequentie. Een goede vuistregel is eenvoudig: als het omkeren van de beslissing discussie vereist, leg dan de beslissing vast.

Statuswaarden en levenscyclus

Beslissingenregistraties moeten een levenscyclus hebben om hun huidige status aan te geven. De eenvoudigste statuswaarden zijn voldoende.

Voorgesteld — De beslissing wordt overwogen maar nog niet geaccepteerd. Gebruik dit wanneer het team een beslissing wil bespreken in een pull request voordat het zich ertoe verbindt.

Geaccepteerd — De beslissing is actief en moet toekomstig werk leiden. De meeste nuttige beslissingenregistraties zullen het grootste deel van hun leven in deze staat doorbrengen.

Vervangen — De beslissing is vervangen door een nieuwere registratie. Verwijder oude registraties niet; behoud ze voor de geschiedenis en link naar de nieuwere beslissing zodat de evolutie van denken zichtbaar blijft.

Verouderd — De beslissing wordt niet langer aanbevolen maar kan nog steeds bestaande delen van het systeem beschrijven. Dit is bijzonder nuttig tijdens migraties, wanneer oude patronen in de codebase bestaan naast nieuwere benaderingen.

Het belangrijke principe is dat beslissingenregistraties append-vriendelijk moeten zijn. Wanneer het team van richting verandert, creëer dan een nieuwe registratie en link de oude in plaats van de geschiedenis te herschrijven om het verleden schoner te laten lijken.

Hoe AI beslissingenregistraties moet genereren

AI kan helpen bij het creëren van beslissingenregistraties, en dit is een van de betere gebruiken van AI in softwareontwikkeling — het is snel in het opstellen van gestructureerde documenten uit context. Na een discussie, architectuurreview of pull request, kun je een AI-assistent vragen om een registratie op te stellen:

Stel een Architectuurbeslissingenregistratie op voor de beslissing in deze pull request.
Inclusief context, alternatieven, consequenties en AI-richtlijn.
Sla het op als Markdown onder docs/decisions/architecture.

Voor productwerk:

Stel een Productbeslissingenregistratie op die uitlegt waarom AI-gegenereerde berichten
concepten moeten blijven tot ze door de gebruiker zijn gereviewd.
Inclusief gebruikersimpact, out-of-scope gedrag, afwegingen en AI-richtlijn.

De door AI gegenereerde registratie mag echter niet automatisch vertrouwd worden. Menselijke review moet verifiëren dat de context nauwkeurig is, dat de AI geen redenering heeft verzonnen, dat de opgesomde alternatieven echt zijn, dat de consequenties eerlijk zijn, en dat de AI-richtlijn overeenkomt met de daadwerkelijke intentie van het team. AI is een opstelassistent — het is niet de eigenaar van de beslissing.

Hoe AI beslissingenregistraties moet lezen

De andere helft van de praktijk is het instructeren van AI om de registraties te lezen voordat het handelt. Voordat je een AI-assistent vraagt om een wijziging te implementeren, voeg dan een instructie als deze toe:

Lees docs/decisions voordat je deze feature aanpast.
Identificeer alle Architectuur-, Product- of Ontwerpbepalingenregistraties die van toepassing zijn.
Volg geaccepteerde beslissingen. Als je voorgestelde wijziging in conflict komt met een
beslissingenregistratie, leg dan het conflict uit voordat je code wijzigt.

Voor grotere taken, versterk de rol van de registraties als projectgeheugen:

Gebruik de beslissingenregistraties als projectgeheugen.
Maak geen geaccepteerde beslissingen ongedaan zonder een nieuwe vervangende beslissing voor te stellen.
Wanneer je code genereert, leg uit welke beslissingenregistraties de implementatie beïnvloedden.

Dit verandert de rol van de AI van “plausibele code voorspellen” naar “opereren binnen een gedocumenteerd systeem van beperkingen” — een significante verbetering in betrouwbaarheid voor complexe of langlevende projecten.

Beslissingenregistraties in pull requests

Beslissingenregistraties moeten onderdeel zijn van normale pull request review in plaats van een apart proces. Een eenvoudige PR-checklistentry maakt de gewoonte zichtbaar:

## Beslissingenregistratie checklist

- [ ] Deze PR introduceert geen significante architectuur-, product- of ontwerpbeslissing.
- [ ] Deze PR introduceert een significante beslissing en bevat een nieuwe beslissingenregistratie.
- [ ] Deze PR verandert een eerdere beslissing en bevat een vervangende registratie.
- [ ] Relevante bestaande beslissingenregistraties zijn overwogen.
- [ ] AI-gegenereerde code volgt de geaccepteerde beslissingenregistraties.
- [ ] AI-gegenereerde beslissingenregistraties zijn door een mens gereviewd.

Deze checklist is eenvoudig, maar het verandert gedrag door het team eraan te herinneren dat code niet het enige artefact is dat in een pull request belangrijk is. Het maakt het ook natuurlijk om op te vangen wanneer een AI-gegenereerde wijziging stilletjes een eerdere beslissing schendt.

Beslissingenregistraties en architectuurgovernance

Traditionele architectuurgovernance faalt vaak omdat het te zwaar, te langzaam of te losgekoppeld is van implementatie — centrale goedkeuringscomités, grote vooraf documenten en gatekeepingprocessen die blokkeren in plaats van leiden. Beslissingenregistraties bieden een lichtgewicht alternatief dat direct integreert in de ontwikkelworkflow.

Ze vereisen geen centraal architectuurcomité voor elke wijziging, noch blokkeren ze teams van leren en aanpassen. In plaats daarvan creëren ze een spoor van beslissingen dat kan worden gereviewd, gerefereerd en gebouwd in de loop van de tijd. Dit ondersteunt evolutionaire architectuur: de architectuur kan veranderen, maar het verandert met geheugen in plaats van ondanks dat. Het team kan oude beslissingen opnieuw bekijken zonder te hoeven ontdekken waarom ze werden genomen, wat een gezondere en eerlijkere vorm van governance is:

• Kleine registraties in plaats van enorme documenten
• Review dicht bij de code in plaats van aparte goedkeuringstheater
• Historische context in plaats van tribale kennis
• Expliciete afwegingen in plaats van verborgen aannames

Beslissingenregistraties en productmanagement

Productwerk heeft ook beslissingengeheugen nodig, en dit is een gebied waar de waarde van beslissingenregistraties vaak wordt onderschat. Een roadmap zegt wat er kan gebeuren. Een ticket zegt wat er als volgende moet worden gebouwd. Analytics zeggen wat gebruikers deden. Geen van die volledig uitlegt waarom een productgedrag bestaat.

Productbeslissingenregistraties vullen dat gat en zijn vooral nuttig voor prijs- en pakketbeslissingen, permissiemodellen, limieten en quotas, AI-veiligheid en reviewflows, onboardingkeuzes, gebruikersroldefinities, samenwerkingsregels, dataretentiebeleidingen en featurescope grenzen. Eenmaal geïmplementeerd, worden productbeslissingen onzichtbaar in de code — later ziet iemand alleen de code en vraagt, “Waarom werkt het zo?” Een PDR geeft het antwoord in een vorm die zowel mensen als AI-tools kunnen vinden en gebruiken.

Beslissingenregistraties en ontwerpsystemen

Ontwerpsystemen documenteren vaak componenten, tokens en gebruikregels, maar ze documenteren zelden waarom het systeem zo werkt. Ontwerpbepalingenregistraties vullen dit gat. Een componentbibliotheek kan zeggen “gebruik de bevestigingsdialoog voor destructieve acties”, terwijl een DDR de redenering uitlegt: “We vereisen bevestiging voor destructieve acties omdat gebruikers vaak werken met gedeelde teamdata, en per ongeluk verwijderen een hoge herstelkost heeft.”

Die redenering is belangrijk buiten het specifieke component. Het helpt toekomstige ontwerpers, ontwikkelaars en AI-tools om het principe correct toe te passen in nieuwe situaties. Zonder de DDR kan een AI-agent een snellere interactie genereren die bevestiging overslaat omdat het efficiënter lijkt. Met de DDR kan de agent herkennen dat het behouden van de eigenschap veiligheid intentioneel en niet-onderhandelbaar is.

Hoe beslissingenregistraties spec-gedreven ontwikkeling ondersteunen

Spec-gedreven ontwikkeling verklaart wat het systeem moet doen. Beslissingenregistraties verklaren waarom het team die richting koos, en het onderscheid is significant voor AI-gestuurde werk.

Een featurespecificatie kan zeggen dat AI-gegenereerde e-mails als concepten moeten worden opgeslagen. Een Productbeslissingenregistratie verklaart waarom automatisch verzenden werd afgewezen, welke risico’s werden overwogen, en welke toekomstige wijzigingen een nieuwe beslissing vereisen. Een ontwerpspecificatie kan een zijpaneelinteractie beschrijven, terwijl de bijbehorende DDR uitlegt waarom inline AI-bewerkingen expliciet werden afgewezen en waarom het behouden van gebruikerscontrole zwaarder werd gewogen dan workflowsnelheid. Een architectuurspecificatie kan een servicelengte definiëren, en zijn ADR verklaart waarom het team die grens koos boven een eenvoudigere of meer gedistribueerde alternatief.

De spec leidt implementatie. De beslissingenregistratie behoudt oordeel. Samen geven ze AI-programmagelezen zowel instructies als context — het “wat” en het “waarom” — wat de combinatie zo effectief maakt voor complexe, langlevende systemen.

Beslissingenregistraties zijn geen specificaties

Beslissingenregistraties zijn gerelateerd aan specificaties, maar ze dienen een ander doel. Een specificatie zegt “het systeem moet X doen”, terwijl een beslissingenregistratie zegt “we kozen X in plaats van Y vanwege deze beperkingen en afwegingen.” Dat “in plaats van Y” is het waardevolle deel. AI-tools genereren vaak oplossingen door een plausibele weg te vinden naar het gevraagde resultaat, maar beslissingenregistraties vertellen ze welke plausibele wegen al zijn verkend, geëvalueerd en afgekeerd — vermindert churn en verbetert de kwaliteit van AI-gestuurde werk.

Beslissingenregistraties zijn geen vervanging voor tests

Tests verifiëren gedrag; beslissingenregistraties verklaren intentie. Beide zijn noodzakelijk en ze werken samen. Een test kan afdwingen dat AI-gegenereerde e-mails als concepten moeten worden opgeslagen, terwijl een Productbeslissingenregistratie verklaart dat dit vereist is omdat gebruikers AI-gegenereerde communicatie moeten reviewen voordat het het systeem verlaat. De test beschermt gedrag. De beslissingenregistratie beschermt betekenis. Samen maken ze toekomstige wijzigingen veiliger en voorspelbaarder.

Beslissingenregistraties zijn geen vervanging voor codecommentaren

Codecommentaren verklaren lokale implementatiedetails, terwijl beslissingenregistraties bredere beslissingen verklaren. Gebruik commentaren voor verrassende regels, edge cases, workarounds en functies die niet kunnen worden vereenvoudigd. Gebruik beslissingenregistraties voor waarom een architectuur bestaat, waarom een productgedrag bestaat, waarom een interactiepatroon bestaat, en waarom het team één richting koos boven een andere. Als de uitleg alleen een paar regels beïnvloedt, is een commentaar het juiste hulpmiddel. Als het de richting van het systeem beïnvloedt, is een beslissingenregistratie het juiste hulpmiddel.

Veelgemaakte fouten

Registraties te laat schrijven

Een beslissingenregistratie moet worden geschreven wanneer de beslissing wordt genomen, niet maanden later wanneer iedereen de afwegingen is vergeten. Het is prima om er een op te stellen tijdens een pull request. Het is nog beter om het op te stellen voordat implementatie, terwijl de beslissing nog actief wordt besproken en de alternatieven vers zijn.

Registraties te lang maken

Een beslissingenregistratie is geen essay. Het moet gedetailleerd genoeg zijn om oordeel te behouden maar kort genoeg dat mensen het daadwerkelijk lezen. Kies voor duidelijkheid boven volledigheid — een beknopte registratie die wordt gelezen is veel waardevoller dan een uitgebreide die wordt overgeslagen.

Beslissingen vastleggen zonder consequenties

De consequentiessectie is het hart van de registratie. Een beslissing zonder genoemde consequenties is vaak slechts een voorkeur in plaats van een echte beslissing. Goede registraties geven eerlijk toe aan afwegingen, inclusief wat moeilijker of riskanter wordt als gevolg van de keuze.

Oude registraties bewerken alsof de geschiedenis veranderde

Wanneer een beslissing verandert, creëer dan een nieuwe registratie en markeer de oude als vervangen. Stil herschrijven van een oude beslissing om overeen te komen met de huidige staat vernietigt de historische context die beslissingenregistraties waardevol maakt. Geschiedenis is nuttig precies omdat het toont hoe denken evolueerde.

AI-gegenereerde registraties laten samenvoegen zonder review

AI kan een gepolijste, goed gestructureerde registratie produceren die subtiel verkeerd is. Behandel AI-gegenereerde beslissingenregistraties exact als AI-gegenereerde code — review ze zorgvuldig, verifieer dat de redenering nauwkeurig is, en zorg ervoor dat de consequentiessectie weerspiegelt wat het team daadwerkelijk aanvaardde.

Registraties verbergen buiten de repository

Als beslissingenregistraties leven in een aparte wiki of documentatiesysteem, zijn ze minder waarschijnlijk bijgewerkt naast code wijzigingen en veel minder waarschijnlijk gelezen door AI-programmatools die context laden voor een taak. Ze in de repository houden is niet zomaar een gemak — het is wat de praktijk werkt voor AI-gestuurde ontwikkeling.

Een lichtgewicht operationeel model

Een praktisch teamproces dat minimale overhead toevoegt ziet er zo uit:

1. Tijdens planning of implementatie, identificeren of een betekenisvolle beslissing wordt genomen.
2. Vraag een AI-assistent om een ADR, PDR of DDR op te stellen op basis van de discussie.
3. Review het concept als team, het verifiëren van context, alternatieven en consequenties.
4. Commit de registratie als Markdown in de repository.
5. Link het van het gerelateerde issue of pull request.
6. Instructeer AI-programmatools om relevante registraties te lezen voordat ze toekomstige wijzigingen in het gebied maken.
7. Vervang registraties wanneer beslissingen veranderen, het behouden van de oude registratie voor de geschiedenis.

Dit vereist geen nieuwe bureaucratie of een gedocumenteerde documentatierol. Het vereist een kleine gewoonte: het behouden van belangrijk oordeel op het moment dat het wordt gecreëerd, dicht bij de code waar het nodig zal zijn.

Voorbeeld ADR

# Beslissing: Gebruik PostgreSQL voor primaire applicatieopslag

Status: Geaccepteerd
Datum: 2026-06-25
Type: Architectuur
Eigenaren: Platformteam

## Context

De applicatie heeft duurzame relationele opslag nodig voor accounts, projecten,
permissies en audit events. Het team verwacht frequente rapportagequeries
en sterke consistentievereisten voor permissiecontroles.

## Beslissing

We zullen PostgreSQL gebruiken als primaire applicatiedatabase.

## Overwogen alternatieven

### DynamoDB

Voordelen:
- Operationeel schaalbaar
- Goede fit voor voorspelbare key-value toegangs patronen

Nadeelen:
- Complexe voor relationele queries
- Moeilijker voor ad hoc rapportage
- Minder bekend bij het huidige team

### MySQL

Voordelen:
- Rijp relationele database
- Bekend operationeel model

Nadeelen:
- PostgreSQL komt beter overeen met de behoeften van het team voor JSON-ondersteuning,
  indexeringsopties en bestaande expertise

## Consequenties

PostgreSQL wordt een kern operationele afhankelijkheid. Het team moet
migraties zorgvuldig beheren en queryprestaties monitoren. In ruil daarvoor
krijgt de applicatie sterke relationele modellering, rijpe indexering en
flexibele rapportageondersteuning.

## AI-richtlijn

Wanneer persistentiecode aanpast, geef voorkeur aan relationele modellering in PostgreSQL.
Voer geen tweede primaire database in zonder een vervangende ADR.

Voorbeeld PDR

# Beslissing: AI-gegenereerde e-mails moeten concepten blijven

Status: Geaccepteerd
Datum: 2026-06-25
Type: Product
Eigenaren: Productteam

## Context

Het product kan e-mailantwoorden genereren met behulp van AI. Het verzenden van e-mail is een
hoge-vertrouwingsactie omdat fouten klanten, partners of
interne teams kunnen bereiken.

## Beslissing

AI-gegenereerde e-mails moeten als concepten worden gemaakt. Een menselijke gebruiker moet
ze reviewen en verzenden.

## Overwogen alternatieven

### Automatisch verzenden

Voordelen:
- Snellere workflow
- Minder gebruikersinspanning

Nadeelen:
- Hoger risico op onjuiste of ongepaste berichten
- Lager gebruikersvertrouwen
- Moeilijker om te herstellen van fouten

### Vragen om bevestiging pas na generatie

Voordelen:
- Houdt de workflow eenvoudig
- Biedt enige gebruikerscontrole

Nadeelen:
- Bemoedigt nog steeds oppervlakkige review
- Past niet zo goed bij bestaande e-mailclientgedrag als concepten

## Consequenties

De workflow is iets langzamer, maar veiliger en meer betrouwbaar.
Toekomstige automatisering kan de reviewsnelheid verbeteren, maar mag niet omzeilen
menselijke goedkeuring zonder een vervangende PDR.

## AI-richtlijn

Wanneer e-mailgeneratiefuncties bouwt, maak concepten standaard.
Voeg geen automatisch verzenden toe tenzij een nieuwe geaccepteerde PDR het expliciet toestaat.

Voorbeeld DDR

# Beslissing: Toon AI-schrijfsuggesties in een zijpaneel

Status: Geaccepteerd
Datum: 2026-06-25
Type: Ontwerp
Eigenaren: Ontwerpteam

## Context

Gebruikers hebben hulp nodig bij het verbeteren van geschreven content, maar ze moeten ook
in controle blijven van de eindtekst. Inline AI-bewerkingen kunnen het moeilijk maken
om gebruikersgeschreven content te onderscheiden van gegenereerde suggesties.

## Beslissing

AI-schrijfsuggesties verschijnen in een zijpaneel. Gebruikers kunnen suggesties accepteren,
afwijzen of kopiëren naar de hoofdeditor.

## Overwogen alternatieven

### Suggesties inline toepassen

Voordelen:
- Snel
- Voelt geïntegreerd

Nadeelen:
- Vervagt auteurschap
- Maakt review moeilijker
- Kan gebruikers verrassen

### Suggesties tonen in een modaal

Voordelen:
- Gecombineerde ervaring
- Makkelijk te implementeren

Nadeelen:
- Onderbreekt schrijf flow
- Moeilijker om suggestie en originele tekst te vergelijken

## Consequenties

Het zijpaneel neemt meer schermruimte in, vooral op kleine schermen.
Echter, het behoudt gebruikerscontrole en maakt review duidelijker.

## AI-richtlijn

Wanneer schrijfassistentiefuncties toevoegt, behoud scheiding tussen
gebruikerstekst en AI-suggesties. Pas gegenereerde tekst niet direct
in het document toe zonder expliciete gebruikersactie.

Suggestie promptbibliotheek

Gebruik deze prompts om beslissingenregistraties onderdeel te maken van dagelijkse AI-gestuurde ontwikkeling.

Vind relevante registraties voordat je aan een feature werkt:

Lees docs/decisions en identificeer alle geaccepteerde beslissingenregistraties die van toepassing
zijn op deze taak. Samenvatten de beperkingen voordat je code wijzigingen voorstelt.

Stel een nieuwe ADR op:

Stel een Architectuurbeslissingenregistratie op voor deze technische beslissing.
Inclusief context, beslissing, alternatieven, consequenties en AI-richtlijn.
Houd het beknopt en specifiek.

Stel een nieuwe PDR op:

Stel een Productbeslissingenregistratie op voor dit productgedrag.
Inclusief gebruikersimpact, scope, alternatieven, consequenties en AI-richtlijn.

Stel een nieuwe DDR op:

Stel een Ontwerpbepalingenregistratie op voor dit interactiepatroon.
Inclusief gebruikersprobleem, alternatieven, afwegingen, consequenties en AI-richtlijn.

Review een pull request tegen bestaande beslissingen:

Review deze pull request tegen de geaccepteerde beslissingenregistraties in docs/decisions.
Identificeer conflicten, ontbrekende beslissingenregistraties of beslissingen die
moeten worden vervangen.

Vervang een beslissing:

Maak een nieuwe beslissingenregistratie die de bestaande vervangt.
Behoud de historische redenering, leg uit wat veranderde, en link beide registraties.

Gerelateerde lectuur

• Michael Nygard’s oorspronkelijke ADR-formaat — het grondleggende post dat de ADR-beweging startte
• ADR GitHub organisatie — tooling, sjablonen en communitybronnen voor het beheren van beslissingenregistraties
• Wat is Spec-Gedreven Ontwikkeling? De Spec als Bron van Waarheid — de canonieke SDD-definitie die uitlegt hoe featurespecificaties beslissingenregistraties aanvullen: beide maken intentie duurzaam, op verschillende niveaus van het systeem
• Spec-Gedreven Ontwikkeling vs Vibe Coding: Waterfall? — wanneer je SDD moet gebruiken en wanneer je met snellere, losser workflows moet blijven
• Applicatiearchitectuur in Productie: Integratiepatronen, Codeontwerp en Datatoegang — de clusterhome die integratie, testen, datatoegang en software-documentatiepatronen dekt
• AI voor Kennisbeheer: Werkelijke Workflows die Stand Houden — praktische AI-augmented kennisworkflows die de beslissingenregistratiepraktijk aanvullen