Architecture Decision Records (ADR’s)
ADR’s leggen architectuurkeuzes vast: wat is besloten, waarom, welke alternatieven afgewezen, welke gevolgen verwacht. Eén ADR per beslissing, onveranderlijk na acceptatie. Wordt een keuze later vervangen, schrijf dan een nieuwe ADR die naar de oude verwijst en zet de status van de oude op “vervangen door ADR-XXXX”.
Wanneer een ADR schrijven
- Bibliotheek-, framework- of platformkeuzes met impact op meerdere modules.
- Datamodel- of API-contract beslissingen die moeilijk terug te draaien zijn.
- Cross-cutting concerns: auth, logging, observability, deploy-strategie.
- Bewust afwijken van een conventie in deze codebase.
Niet voor: bug-fixes, refactors zonder design-impact, dependency-bumps.
Een nieuwe ADR maken
npm run docs:adr -- "korte-titel-met-streepjes"
Het script kopieert 0000-template.md naar <volgnummer>-<titel>.md en print het pad. Vul daarna in en commit.