Architecture Decision method

Architecture Decision Record

An Architecture Decision Record keeps an architecture decision and its rationale discoverable.

An Architecture Decision Record documents the relevant context, chosen solution, and consequences in a short, discoverable record. Current and future contributors can understand the decision and reassess it when context changes.

Core question

Which architecture decision are we making in this context, why choose it and which consequences does it carry?

Plan decision work Method guide

Start comparison

Give feedbackIs this method useful to you?

Participants: 1-3
Time: 15–45 min for a draft; investigation and review are additional

An ADR records a decision. Investigation and review may require multiple sessions; their scope follows the question’s significance and uncertainty.

Paper illustration of two considered options leading to a decision record with a marked status and visible consequences.

Frame
Clarify decision and context
Focus the architectural question.
Compare
Compare relevant options
Expose decisive differences and uncertainties.
Decide
Review and record the decision
Explicitly agree on choice, rationale and consequences.
Maintain
Follow consequences and preserve history
Keep the decision discoverable and review changed context.

Review status and consequences when new evidence arrives. Explain a changed decision in a new linked ADR and mark its predecessor as superseded.

A good fit when

An architecturally significant decision needs a discoverable rationale, for example about structure, interfaces, dependencies or quality requirements.

Ideal for

Architecture governance
Team memory
High-change codebases

Not good for

Trivial decisions
Long specifications

Outputs

Decision record
Context, decision, status and consequences in a short reference.
Reasoned trade-offs
Relevant options and the differences that matter.
Preserved history
Linked decisions and traceable status changes.

ADR structure

Fictional teaching example

Fictional draft about shared tool reservations. It demonstrates the document structure and has not been accepted.

ID, title and status

Record a stable ID, decision question, date, contributors, owner and current status.

Fictional: ADR-007 · Shared reservation management · proposed · date open · Alex coordinates review.

Context and decision drivers

Why is this decision needed? Which requirements and constraints shape it?

Fictional: Online access and the collection point allocate the same tools. Both channels must consider available inventory.

Considered options

Briefly compare relevant options, decisive differences, sources and uncertainties.

Fictional: A uses a central reservation service. B keeps separate lists with periodic reconciliation. To investigate: conflicts between simultaneous requests.

Decision and rationale

Record the chosen option and its decisive rationale. Label a draft as a proposal.

Fictional proposal: A, so allocation has a shared decision point. Technical conflict prevention will be checked separately.

Consequences and follow-up

Describe relevant favorable and unfavorable consequences, uncertainties and concrete follow-up work.

Fictional: Shared validation rules; also a dependency on service availability and operation. Open: outage procedure and evidence of conflict-free allocation.

Review, status changes and links

Document review, explicit decision and date. Link sources and any predecessor or successor.

Fictional: Product and operations review the proposal. Status remains proposed until the agreed decision is recorded.

This template combines Nygard’s short core structure with useful fields for trade-offs and review. Detail and process follow the decision need.

Based on Michael Nygard, with options and review added

First step

Formulate a concrete decision question and the context that makes it necessary. Name contributors and decision ownership.

Open the method guide

Good to do first

Architecture

Quality Attribute Workshop

Supplies prioritized quality scenarios that require a decision.

Where to go next?

Architecture

arc42

Anchors the recorded decision in the living architecture documentation.

Architecture

C4 Model

Reflects the decision in the affected architecture views.

Deep dive

Purpose

An ADR permanently records an architecture decision with context, trade-offs, and consequence. It creates continuity for later changes because the decision path stays traceable.

How it works

First the problem, goals, and constraints are described precisely. Then the team documents the options, the chosen solution, and the main trade-offs. Finally the entry is versioned with date, status, and a reference to follow-up work.

In detail

An ADR works because architecture decisions are not just recorded but remain readable later together with their context and consequences. Good use documents the actual tension between options and openly names the weight of the chosen direction. This stops teams from knowing, months later, only the outcome while losing track of the reason and the deliberate trade-offs.

Facilitation

Before writing, gather the real decision question, the main alternatives, and the quality goals under tension. The format shows its value exactly where the chosen option has a clear consequence for operations, development, or coupling. Close with a precise status, a clear rationale, and a note on when a revision would be due.

The method guide walks execution through 4 phases, timing, 4 pitfalls, and clear stop criteria.

Open method guide

Your perspective

Does this method help with your work?

Your feedback helps shape the next improvements to methodatlas.

Sources and topics

Topics

Architecture Rationale Documentation Governance

Sources

Documenting Architecture Decisions · Michael Nygardcognitect.comOriginal reference for short records with context, status, decision and consequences, preserving their history.Markdown Architectural Decision Records · MADRadr.github.ioAdditional template variant for decision drivers and considered options. The working approach and example provided here are editorial guidance.

In playbooks

Prepare Architecture DecisionMove from a fuzzy technical problem to a documented, traceable architecture decision.

Artifact templates

Architecture Decision Record: WorksheetPlan work on an ADR from context through trade-offs to the agreed review.

markdown

adr-markdown.md

Plan work on an ADR from context through trade-offs to the agreed review.

Architecture Decision Record: Worksheet

Question

To be confirmed

Desired outcome

To be confirmed

Scope

Prepare and review an ADR Time: Arrange drafting and review separately

Complete this worksheet on paper or in your own document during the work.

Preparation for this scope

Method setup

Materials: A short text template, relevant architecture context, sources for considered options and a versioned location accessible to contributors.
Roles: An owner writes the draft. Relevant engineering, architecture, product or operations contributors review its consequences. The agreed decision owner explicitly accepts the decision.
Advance information: Gather the question, current architecture, affected quality requirements and known constraints. Link relevant earlier ADRs and sources.
Overall time needed: Allow roughly 15 to 45 minutes for a focused draft. Investigation, discussion and review are additional and may be asynchronous. Agree on a suitable review point together.
Setup: Assign a stable ID and short title, set status to proposed and create the record in the shared location. Agree on the decision and review process with contributors.

Prepare for the work steps

Frame: Clarify decision and context

Architecture question and current system context

Compare: Compare relevant options

Decision context and realistic options

Decide: Review and record the decision

Draft, trade-offs and affected perspectives

Maintain: Follow consequences and preserve history

ADR with explicit status and follow-up tasks