01 / UNDERSTAND
What is an architecture decision record?
An architecture decision record, or ADR, preserves a significant technical decision and the context that made it reasonable. It usually names the decision’s status, describes the choice and records its consequences. It explains why the team chose, not just what it built.
Michael Nygard’s original description emphasises small records of consequential decisions. For product and service designers, an ADR can make a technical constraint and its experience implications visible without turning the document into a full specification.
Why use ADR (Architecture Decision Record)?
A later team can see an interface constraint without knowing the tradeoff behind it. It may repeat an earlier debate or preserve a choice whose assumptions no longer hold. An ADR keeps that reasoning accessible. Its value is strongest when it records meaningful alternatives and consequences, including those borne by users or operators, rather than presenting the accepted choice as inevitable.
When to use it
USE IT WHEN
A technical choice has a lasting effect on experience or delivery.
Several plausible options have meaningful tradeoffs.
Future contributors will need to understand why the choice was made.
When to choose another method
Use Design Principles for recurring experience guidance.
Use RACI Matrix when decision authority is unclear.
Use Product Roadmap to sequence work rather than document a decision’s rationale.
What you’ll need
Identify the decision, owner and affected people. Gather the context and constraints that distinguish the options. Agree a concise record format and where the team can find it. Use a status such as proposed, accepted or superseded. Distinguish observed conditions from assumptions, and name a review trigger for constraints likely to change.
What a useful decision record contains
Keep the elements that help answer your question and support a decision.
One meaningful architectural decision.
Conditions and constraints at the time of the choice.
Alternatives considered and relevant tradeoffs.
The accepted choice and its current standing.
Benefits, costs and experience implications.
Evidence or change that could justify a new decision.
02 / PUT IT INTO PRACTICE
How to write an ADR with a product team
Keep evidence and assumptions distinct. Revisit your work when new information changes your understanding.
01
Choose one decision
Bound the record to a consequential choice.
Decide when an appointment change may be presented as confirmed.
02
Describe the context
Record constraints and separate evidence from assumptions.
Scheduling and contractor systems can acknowledge updates at different times.
03
Compare options
Make realistic alternatives and their consequences visible.
Show immediate confirmation or wait for authoritative acceptance.
04
Record the choice
State the selected option, owner and status concisely.
Accepted: show a pending state until the scheduling service confirms.
05
Explain consequences
Include what people experience and what operations must handle.
Pending changes need understandable status and a recovery route.
06
Name a revisit trigger
Record a condition that could change the rationale.
Review if dependable end to end acknowledgement becomes available.
07
Maintain the history
Link a new decision when the old one is superseded rather than rewriting the original reasoning.
Preserve why the pending state was reasonable at the time.
Example: deciding when an appointment change is confirmed
Fictional scenario: booking and contractor systems do not always acknowledge a change together. The team compares immediate interface confirmation with a pending state that waits for authoritative scheduling acceptance. It accepts the latter and records the experience cost: the resident needs a clear explanation, current status and a route for unresolved changes.
The record states what was known, which integration assumptions remain unverified and who owns the decision. Its review trigger is dependable acknowledgement across the delivery boundary, rather than an arbitrary date alone.
The visual shows context, two options, the accepted choice and a revisit condition. The record keeps the rejected option understandable. It documents a hypothetical decision; it is not an implementation prescription for every booking architecture.
03 / BELOW THE SURFACE
Below the surface: preserve the decision’s past without defending it forever
A record should explain an earlier choice and still allow the team to change it.
CONTEXT
Which condition made this choice reasonable?
Separate fact from assumption.
CONSEQUENCE
Who bears the cost of this option?
Include experience and operational effects.
REVISIT
What change would justify a superseding record?
Keep history without freezing the decision.
Once a system improves, the old rationale can sound unreasonable. Rewriting the record to make today’s choice seem obvious destroys useful context. Leaving it accepted indefinitely can be equally misleading when its assumptions have expired.
Keep the original context and status history, then link a superseding record that explains the changed conditions. A good past decision can become the wrong current decision. Review the assumption behind the constraint, not whether its original author still supports it.
This is an editorial maintenance check, not a new ADR format. It also makes reversibility concrete: identify what would need migration, which experience changes would follow and who must be involved before superseding the choice. The record should make reconsideration easier, not turn historical reasoning into permanent policy.
ADR (Architecture Decision Record) companion worksheet
The original two page companion records one decision, options, rationale and consequences. Its review page examines assumptions, reversibility and supersession. It draws on ADR practice and the MADR project without reproducing their templates as proprietary Design Iceberg work.
Practical tips
Keep each record focused on one decision.
Explain a realistic rejected option.
Link superseding decisions and preserve the history.
Common mistakes
Documenting only the chosen implementation.
Presenting assumptions as permanent facts.
Rewriting an earlier record to erase a changed rationale.
What you’ll get
An accessible account of the choice and its consequences. Use it when explaining constraints, onboarding contributors or reviewing changed assumptions, and create a linked successor when the decision is superseded.