ArchitecturalDecisionRecords
title: Architectural Decision Records (ADR) type: technique created: 2026-05-16 last_updated: 2026-05-16 related: ["Playradar", "ADR", "radar/techniques/RequestForDiscussion"] sources: ["https://adr.github.io/"] radar_quadrant: Techniques radar_ring: Trial radar_position: inner
A technique for capturing individual architectural decisions as structured documents stored alongside the codebase. Each ADR records a single decision: the problem, the options considered, the outcome chosen, and the consequences — both positive and negative.
An Architecturally Significant Requirement (ASR) is the trigger. A requirement qualifies as architecturally significant if it has high business value or risk, involves key stakeholders, has runtime quality implications (performance, reliability), introduces external dependencies with unpredictable behaviour, has cross-cutting effects across multiple system parts, is a first-of-its-kind problem for the team, or has caused critical failures on prior projects.
Not every decision warrants an ADR. The selection filter is significance, not volume.
A complete ADR contains: title, status, date, decision owners, problem statement, context (forces at play), decision drivers, at least two considered options ranked by recommendation, decision outcome in active voice ("We decided..."), consequences (good and bad), and further information.
The Definition of Done requires five confirmations: evidence the design will work, comparison of at least two options, peer agreement, documentation shared, and a review plan in place.
| Status | Meaning |
|---|---|
| proposed | Under consideration |
| accepted | Decision made and in effect |
| rejected | Considered and declined |
| deprecated | No longer applicable |
| superseded | Replaced by a later ADR |
The adr.github.io site names several failure modes: shallow justification with no cons (fairy tale), fabricated alternatives that don't actually work (dummy alternative), a single option with no long-term discussion (sprint or rush), and ADRs used as general documentation rather than decision records (mega-ADR).
RFDs (radar/techniques/RequestForDiscussion) are broader in scope — any topic, not only architecture — and heavier in process (bot enforcement, numbered branches, six states). ADRs are lighter and architecture-specific. ADRs suit teams wanting decision traceability without adopting a full discussion process. See ADR for the operational format used in this repository.
The joelparkerhenderson/architecture-decision-record repository (10,000+ stars) collects example ADRs across multiple formats:
- MADR (Markdown Architectural Decision Records): lightweight, structured, git-friendly.
- Y-statements: "In the context of X, facing Y, we decided Z, to achieve Q, accepting D."
- RFC-style: heavier, suitable for large teams with formal review processes.
Each format includes real examples and a comparison of trade-offs. Use this as the canonical starting point when choosing a template or onboarding a team to ADR practice.
Architectural Decision Records sit in the Trial ring of the Techniques quadrant, at inner position. Production use with a real team is confirmed as of 2026-05-16; an operational format is in place in this repository (see ADR). Thoughtworks places ADR in Adopt industry-wide, indicating the technique is mature and widely validated. The inner Trial position reflects strong personal confidence and an established practice. The remaining gap before Adopt is a deliberate review of whether the technique warrants unconditional recommendation in all team contexts.
