Pro-Owner perspective: This document frames your systems as a technical estate — an asset to be stewarded, documented, and bequeathed. Treat these steps as craftsmanship: protect the continuity, auditability, and transferability of your digital legacy.

What it is

Lightweight Markdown documents capturing significant architecture decisions: what was decided, why, what alternatives were considered, what consequences (good and bad) are expected, and when to revisit the decision. ADRs are stored in version control (Git), making them searchable, diffable, and historically auditable.

ADRs follow the MADR (Markdown Any Decision Records) format: Context (what problem are we solving?), Options (what alternatives were considered?), Decision (what we chose), Consequences (trade-offs accepted), Reversal policy (when to reconsider).

Why it matters

Architecture decisions are rarely documented. Teams rely on tribal knowledge ("we chose X because... well, I think it was Y?"). ADRs create institutional memory: future teams understand WHY decisions were made, not just WHAT decisions exist. This prevents:

1. Cargo-cult architecture: Copying patterns without understanding constraints that justified them.
2. Forgotten trade-offs: Revisiting old decisions without remembering what alternatives were ruled out and why.
3. Decision churn: Relitigating resolved questions because context was lost.

ADRs also accelerate onboarding: new engineers read ADRs to understand system design philosophy.

How we do it

1. Trigger: When a decision has long-term consequences (e.g., database choice, communication protocol, deployment model), create an ADR.
2. Draft ADR (30 min):
   • Title: "ADR-NNN: [Decision]" (e.g., "ADR-023: Use PostgreSQL for user data store")
   • Status: Proposed, Accepted, Deprecated, Superseded
   • Context: What problem are we solving? What constraints exist?
   • Options: List alternatives (minimum 2). For each: pros, cons, rough cost.
   • Decision: What we chose and why (explicit criteria that broke ties).
   • Consequences: Trade-offs accepted (e.g., "PostgreSQL gives strong consistency but limits horizontal scaling beyond 10TB").
   • Reversal policy: Conditions for reconsidering (e.g., "Revisit if data exceeds 5TB or read latency > 100ms").
3. Review: Circulate ADR to technical team. Gather feedback. Update alternatives/consequences if new info surfaces.
4. Accept: Mark status as "Accepted." Commit to Git. ADR is now canonical.
5. Maintenance:
   • If decision is superseded, create new ADR and link to old one.
   • If decision is deprecated, update status and document why.
   • Never delete ADRs (historical context valuable even for bad decisions).

What you receive

• ADR repository: All ADRs in Git, organized by number (ADR-001, ADR-002...), searchable by keywords.
• Decision dossier: Each ADR contains full context, alternatives, decision rationale, consequences, reversal triggers.
• Decision trends: Analysis of decision frequency (how often we make significant choices), domains (auth, data, infra), reversals (how often we change our minds).

All ADRs written in Markdown, stored in /docs/architecture/decisions/ (or similar), version-controlled.

Evidence

Interactive ADR museum:

• Dossier cards: Each ADR displayed as expandable card sorted by date (newest first).
• Card preview: Shows title, status, decision summary, date.
• Expanded view: Shows full context, alternatives table (pro/con/cost), decision rationale, consequences, reversal policy.
• Search: Filter by keyword (e.g., "database," "auth," "cloud").
• Trends dashboard: Decision velocity (ADRs per quarter), reversal rate (% of ADRs superseded within 1 year).

Download ADR starter pack (template + sample ADRs + Git workflow guide): [Link]

Failure modes & guardrails

Failure mode: ADRs too detailed (novel-length)
Guardrail: Max 2 pages per ADR. If decision requires more, split into multiple ADRs or create separate architecture document.

Failure mode: ADRs never written
Guardrail: Significant decisions (affects multiple systems, irreversible < 1 year) require ADR before implementation. No PR merge without ADR link.

Failure mode: ADRs ignored after writing
Guardrail: Link ADRs from implementation code comments. Reference ADRs in design reviews. ADRs are living documents, not write-once artifacts.

Failure mode: Alternatives not seriously considered
Guardrail: Require minimum 2 alternatives per decision. "Only one option" means problem not understood well enough for ADR.