ADR pointer-pattern
Definitie
Een architectuurpatroon voor het documenteren van beslissingen die in meerdere projecten doorwerken, waarbij de canonieke ADR in het eigenaar-project staat en consumer-projecten een pointer-ADR schrijven die ernaar verwijst.
Context
ADRs (Architecture Decision Records) documenteren het WAAROM achter bouwkeuzes die langdurige impact hebben. Wanneer project A een technisch onderdeel bezit en project B dat consumeert, rijst de vraag: waar staat de ADR? Dupliceren leidt tot drift zodra één van beide bijgewerkt wordt. Alleen in A documenteren maakt het onvindbaar voor iemand die in B werkt.
Aanleiding in deze vault: de vault-applicatie woont in Atelier/vault/ (eigenaar), maar kennisbank-web consumeert het via sync-vault.ts. Toen de vault werd verhuisd, wees geen van beide consumenten naar het nieuwe pad en de beslissing was nergens vastgelegd.
Kernpunten
Structuur
Canonieke ADR in het eigenaar-project (Atelier/docs/adr/ADR-001-*.md):
- Volledig uitgewerkt: probleemstelling, alternatieven, waarom gekozen, consequenties, verificatie
- Bevat implementatiereferenties (bestandspaden, code-voorbeelden)
- Is het levende document dat bijgewerkt wordt bij wijziging
Pointer-ADR in elk consumer-project (kennisbank-web/docs/adr/ADR-001-*.md):
- Compact: verwijst uitsluitend naar canoniek bestand
- Legt uit waarom het een pointer is (eigenaarschap duidelijk)
- Bevat lokale verificatiestap zodat de consumer zelfstandig kan testen
# ADR-001: [onderwerp] (pointer)
**Status:** Accepted (pointer)
## Context
[consumer] consumeert [eigenaar] via [welk component]. Zie canoniek:
`~/Claude/projects/[eigenaar]/docs/adr/ADR-001-*.md`
## Decision
Volg canonieke ADR. Korte samenvatting: [essentieel in 2-3 zinnen]
## Verification
[lokale testcommand voor de consumer]Wanneer dit patroon gebruiken
Toepassen wanneer:
- Een library, service of data-store in project A ook door project B gebruikt wordt
- De beslissing over A door A gemaakt is (niet gezamenlijk)
- Consumers buiten A moeten kunnen uitleggen WAáraan ze gebonden zijn zonder elke keer A’s docs te openen
Niet toepassen wanneer:
- De beslissing gezamenlijk eigendom is (dan: één gedeeld doc-repo, of beide volwaardige ADRs)
- Er slechts één project is dat de beslissing raakt
ADR-index bijhouden
Zowel het eigenaar-project als elk consumer-project onderhoudt een docs/adr/README.md met:
- Tabel van alle ADRs (Nr, Status, Categorie, Titel)
- Korte uitleg wat ADRs zijn (voor nieuwe bijdragers)
- Uitleg wanneer een nieuw ADR nodig is
- Cross-project verwijzingen als de structuur buiten één repo reikt
Drift-preventie
Het pointer-pattern vervangt geen periodieke audit. Risico blijft: een nieuwe consumer copypastet een oud pad zonder de ADR te lezen. Mitigation:
- Grepping op het oude pad als onderdeel van een opruim-taak
- Bij herstructurering van eigenaar-project: pointer-ADRs bijwerken als verplichte stap
Verbanden
-
Zie ook: wiki-atelier-architectuur (eigenaar-project)
-
Zie ook: wiki-vault-mcp-architectuur (eerste toepassing van dit patroon)
-
ADR-skill voor Claude Code:
~/.claude/skills/adr/SKILL.md -
Bestaande ADRs in deze setup:
~/Claude/projects/Atelier/docs/adr/,~/Claude/projects/kennisbank-web/docs/adr/ -
Zie ook: wiki-quartz-custom-plugins — applied_to
Bronnen
- Nygard, M. (2011). Documenting Architecture Decisions. Cognitect Blog. https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- ADR GitHub: https://adr.github.io/