Wanneer moet je een ADR schrijven?

Schrijf een ADR wanneer je een technisch besluit neemt dat moeilijk terug te draaien is, meerdere alternatieven heeft of invloed heeft op de algehele architectuur. Denk aan keuzes voor frameworks, databases, communicatiepatronen of deployment-strategieën.

Hoe bewaar je ADR's het beste?

Bewaar ADR's als Markdown-bestanden in je coderepository, bij voorkeur in een /docs/adr map. Zo doorlopen ze hetzelfde versiebeheer als je code en zijn ze makkelijk doorzoekbaar en te reviewen via pull requests.

Kan een ADR achteraf worden aangepast?

Een geaccepteerde ADR wordt in principe niet meer gewijzigd. Als een besluit wordt herzien, maak je een nieuwe ADR die de vorige vervangt. Op die manier blijft de historische context behouden en is de besluitgeschiedenis altijd traceerbaar.

Technical Decision Record (ADR) Template - Gratis Download & Voorbeeld

Download ons gratis ADR template voor het vastleggen van architectuurbesluiten. Bevat context, besluitvorming, consequenties en alternatieven. Direct bruikbaar voor technische teams.

Een Architecture Decision Record (ADR) is een gestructureerd document dat de context, motivatie en consequenties van een belangrijk technisch besluit vastlegt. Dit template helpt teams om consistente, doorzoekbare besluitlogs bij te houden, zodat toekomstige teamleden begrijpen waarom bepaalde keuzes zijn gemaakt. Het bevat secties voor de probleemstelling, overwogen alternatieven, de uiteindelijke beslissing en de verwachte gevolgen. Door ADR's structureel bij te houden voorkom je dat dezelfde discussies steeds opnieuw gevoerd worden en creëer je een kennisbasis die meegroeit met je architectuur.

Variaties

Lightweight ADR

Beknopte variant van maximaal één pagina die zich richt op de kernbeslissing, de directe context en de belangrijkste consequenties. Gebruikt een platte Markdown-structuur zonder uitgebreide analyse.

Geschikt voor: Geschikt voor kleine teams of dagelijkse technische keuzes die snel vastgelegd moeten worden zonder uitgebreide documentatie-overhead.

Detailed Architecture ADR

Uitgebreide variant met diagrammen, stakeholder-analyse, risicobeoordeling en een gedetailleerde vergelijking van alternatieven. Bevat secties voor compliance-eisen en performance-impact.

Geschikt voor: Bedoeld voor ingrijpende architectuurkeuzes zoals het kiezen van een database-engine, migratie naar een nieuw framework of het ontwerpen van een microservices-architectuur.

Security Decision Record

Beveiligingsgerichte variant die extra secties bevat voor threat modelling, compliance-vereisten (GDPR, ISO 27001), risicoclassificatie en mitigerende maatregelen.

Geschikt voor: Onmisbaar bij besluiten rondom authenticatie, dataversleuteling, netwerkarchitectuur of andere security-gerelateerde technische keuzes.

Hoe te gebruiken

Stap 1: Kopieer het ADR-template naar je projectrepository in een /docs/adr map en geef het bestand een volgnummer, bijvoorbeeld 0001-keuze-database-engine.md. Stap 2: Vul de titel en datum in, samen met de status (voorgesteld, geaccepteerd, vervangen of verworpen). Stap 3: Beschrijf de context en het probleem dat tot dit besluit leidt, inclusief technische beperkingen, teamcapaciteit en businessvereisten. Stap 4: Documenteer minimaal twee alternatieven die zijn overwogen, met voor- en nadelen van elke optie. Stap 5: Noteer de uiteindelijke beslissing en motiveer waarom dit alternatief is gekozen boven de anderen. Stap 6: Beschrijf de verwachte consequenties, zowel positief (verbeterde schaalbaarheid, betere developer experience) als negatief (hogere kosten, leercurve). Stap 7: Laat relevante teamleden de ADR reviewen en voeg hun feedback toe. Stap 8: Markeer de status als geaccepteerd en voeg de ADR toe aan je inhoudsopgave.

Veelgestelde vragen

Dit template direct laten implementeren?

Wij zetten het voor u op, klaar voor productie.

Neem contact op

Gerelateerde artikelen

System Design Document Template - Gratis Download & Voorbeeld

Download ons gratis system design document template. Bevat architectuuroverzicht, componentdiagrammen, datastromen en schaalbaarheidsplannen. Direct bruikbaar voor ontwikkelteams.

Functioneel Ontwerp Template - Gratis Download & Handleiding

Download ons gratis functioneel ontwerp template. Inclusief structuur, voorbeelden en stapsgewijze handleiding voor het opstellen van een professioneel FO-document.

Software Requirements Specification (SRS) Template - Gratis Download

Download ons SRS template voor het vastleggen van software-eisen. Bevat functionele en niet-functionele requirements, use cases en traceability matrix.

Wat zijn Microservices? - Uitleg & Betekenis

Leer wat microservices zijn, hoe deze architectuurstijl werkt en wanneer je microservices kiest boven een monoliet. Ontdek de voor- en nadelen.