20 — Architecture Decision Records
ADRs leggen besluiten vast die alternatieven afsluiten. Eenmaal geaccepteerd is een ADR onveranderlijk — als het besluit verandert, schrijf je een nieuwe ADR die de oude vervangt.
Reikwijdte in Documentatie
ADRs hier gaan over cross-repo besluiten — keuzes die meer dan één app raken of die de werking van het portfolio als geheel bepalen. Besluiten binnen één app blijven in die product-repo.
Voorbeelden van besluiten die hier horen:
- Het overlay-versus-mirror-besluit voor deze repo ([[PORTFOLIO-001-overlay-geen-mirror]])
- Welk authenticatieschema apps onderling gebruiken
- Welke MCP-tool-namespace-conventie geldt voor alle servers
- Hoe gedeelde schema's worden versioneerd
Wanneer wel
- Een keuze is gemaakt tussen meerdere haalbare opties
- De keuze raakt meer dan één feature of PR — meer dan één repo
- Een toekomstige lezer zou redelijkerwijs vragen "waarom hebben we het zo gedaan?"
Wanneer niet
- Besluiten binnen één PRD of feature — die horen in die PRD
- Omkeerbare defaults waar niemand over zes maanden om geeft
- Persoonlijke voorkeuren zonder portfolio-impact
Statuswaarden
| Status | Betekenis |
|---|---|
| Voorgesteld | Ter discussie |
| Geaccepteerd | Besloten; zo doen we het |
| Vervangen | Vervangen door een nieuwere ADR (link erheen) |
| Uitgefaseerd | Niet meer van kracht; niet vervangen |
Bestandspatroon
<GEBIED>-<NNN>-<slug>.md — GEBIED is hoofdletters (PORTFOLIO, AUTH, MCP), NNN is een nul-opgevulde teller per gebied.
Voorbeeld: PORTFOLIO-001-overlay-geen-mirror.md.
Sjabloon
# <GEBIED>-<NNN>: <Korte titel>
**Status:** Voorgesteld | Geaccepteerd | Vervangen | Uitgefaseerd
**Datum:** YYYY-MM-DD
## Context
(Welke krachten spelen er. Welk probleem lossen we op. Wees eerlijk over de randvoorwaarden.)
## Besluit
(Wat we hebben besloten. Helder geformuleerd.)
## Gevolgen
### Wat de standaard wordt
-
### Wat expliciet niet de standaard is
-
### Geaccepteerde trade-offs
-
## Overwogen alternatieven
(Eén alinea per alternatief en waarom het het niet werd.)