| name | architecture-decision-record |
| description | Capture significant architectural decisions as immutable, versioned MADR 4.0 records. Use when a choice is hard to reverse, affects multiple teams, or sets a long-lived constraint. |
Architecture Decision Records (ADR)
ADRs make architectural intent legible. They convert tribal knowledge into a durable, searchable log of context, options, and consequences so future contributors understand why, not just what. Adopt MADR 4.0 (2025) as the canonical schema and keep records co-located with the code they govern.
Stack Baseline (2026)
| Concern | Recommended |
|---|
| Schema | MADR 4.0 (adr.github.io) |
| Storage | docs/adr/NNNN-title.md in the owning repo |
| Tooling | adr-tools v4, log4brains, or Backstage TechDocs |
| Lifecycle states | Proposed, Accepted, Deprecated, Superseded |
| Review | PR-based, CODEOWNERS-gated, async RFC channel |
| Index | Auto-generated README.md rolled up in Backstage |
When to Use
- Choosing a runtime, datastore, message bus, or auth model.
- Defining cross-cutting conventions (multi-tenancy, error contracts, eventing schema).
- Deprecating or replacing a previously accepted ADR.
- Recording a deliberate non-decision ("we will defer this until...").
Prerequisites
- Repo with
docs/adr/ directory and CODEOWNERS entry.
- Markdown linter and PR template referencing an ADR checklist.
- Agreed numbering scheme (zero-padded, monotonic).
- Stakeholder list (consulted vs. informed) per Team Topologies.
Instructions
flowchart LR
A[Trigger: significant decision] --> B[Draft ADR Proposed]
B --> C[Async review on PR]
C --> D{Consensus?}
D -- yes --> E[Merge as Accepted]
D -- no --> B
E --> F[Implement + link from code]
F --> G{Context changed?}
G -- yes --> H[New ADR Supersedes prior]
G -- no --> E
- Detect a decision. If the choice is reversible within a sprint and local to one module, skip the ADR. Otherwise open a draft.
- Scaffold from MADR 4.0. Use the template below; assign the next number; set status
Proposed.
- Frame the problem. State context, drivers (quality attributes), constraints. Link a Wardley Map or Cynefin domain when relevant.
- Enumerate options. Minimum two viable alternatives plus "do nothing". Cite evidence (benchmarks, vendor docs, ThoughtWorks Radar Vol 31+).
- Decide and record consequences. Capture positive, negative, and neutral consequences. Name owners and a review date.
- Open PR for async review. Require approvals from CODEOWNERS and one consulted stakeholder. Resolve threads in-line.
- Merge as Accepted. Reference the ADR id from affected READMEs and source files (
// see ADR-0042).
- Maintain lifecycle. Never edit accepted ADRs except to flip status. Supersede via a new ADR that links back:
Supersedes: ADR-0042.
MADR 4.0 Template
# ADR-NNNN: <Short title of decision>
- Status: Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
- Date: YYYY-MM-DD
- Deciders: @handle1, @handle2
- Consulted: @teamA
- Informed: #channel
## Context and Problem Statement
<2-4 sentences. What forces are at play? Link tickets, metrics, ADRs.>
## Decision Drivers
- <Quality attribute or constraint>
- <Cost / time-to-market>
## Considered Options
1. <Option A>
2. <Option B>
3. Do nothing
## Decision Outcome
Chosen option: "<Option B>", because <justification>.
### Consequences
- Positive: <…>
- Negative: <…>
- Neutral: <…>
## Pros and Cons of the Options
### <Option A>
- Good, because …
- Bad, because …
## More Information
Links, benchmarks, prototypes, related ADRs.
Common Pitfalls
| Pitfall | Symptom | Mitigation |
|---|
| Retrofitting ADRs months later | Vague context, no alternatives | Write at decision time; allow short ADRs |
| Editing accepted ADRs | Audit trail lost | Supersede via new ADR; keep originals immutable |
| One-option ADRs | Rubber-stamp culture | Require >=2 alternatives + "do nothing" |
| ADRs in a wiki | Drifts from code | Co-locate in repo under docs/adr/ |
| No index | Discoverability collapses | Auto-generate index in CI |
Output Format
- One Markdown file per decision:
docs/adr/NNNN-kebab-title.md.
- Auto-generated
docs/adr/README.md index grouped by status.
- Cross-links from affected source files and service READMEs.
Authoritative References
- MADR 4.0 specification - https://adr.github.io
- Michael Nygard, "Documenting Architecture Decisions" (2011, canonical)
- ThoughtWorks Technology Radar Vol 31 (2026) - Lightweight ADRs (Adopt)
- Team Topologies, Skelton & Pais - stakeholder modes
adr-tools v4 - https://github.com/npryce/adr-tools
