Architecture Decision Record
An Architecture Decision Record captures a formative technical decision with its context and consequences. He later makes it clear which options were examined and for which reasons were chosen.
- ContextWhy a decision is needed now.
- OptionsCompare at least two variants.
- ConsequencesWhat the choice entails.
Context
Why this is important
Without any established reasons, no one asks why the shop was built this way, and decisions are revised unnoticed or double-checked. An ADR makes context, options and consequences readable. How you come to a decision shows architectural decision.
This building block documents an architectural decision. The selection process lies in the architectural decision and trade-off analysis; an ADR records the decision and the reasoning.
At a glance · Decision with context
ADR: Shop as a modular monolith
The shop must develop and operate order, payment and shipping logic. The team decides between modular application and independently provided services.
This is how you read the picture
- Context Context section: small team, no separate call readiness, no independent scale.
- Options Options section: A modular monolith, B services for ordering, payment and shipping.
- Consequences Section “Follow”: joint release process, re-evaluate service variant in case of proven autonomy requirements.
- Status
- Suppose – decision applies to the next product phase.
- Context
- A small team operates shop, order management, payment and shipping. Separate call readiness and independent scaling are currently not required.
- Options
- A: Modular monolith with module contracts. B: Services for ordering, payment and shipping with network contracts.
- Decision
- The shop is implemented as a modular monolith; payment provider remains an external service.
- Justification
- An artifact and local module calls match the team design. Clear data sovereignty makes later extraction possible in a targeted manner.
- Consequences
- A joint release process remains necessary. Modules receive their own tests and writing responsibility; if there is a proven need for autonomy, a targeted service variant is re-evaluated.
Benefits & limitations
Helps if:
- Consequential decisions affecting components, goals or teams require a comprehensible context later on.
- Versioned rationales and statuses help interpret recurring discussions and superseded options.
Boundaries
- An ADR proves neither implementation nor operational state; link it to contracts, code and runbooks.
- Trivial decisions overload the register; document choices with long-term consequences or open assumptions.
- The ADR records the rationale; Trade-offs covers the preceding analysis, and Fitness Functions checks whether the rule holds.
In practice
- Capture the decision context. Use the clarified requirements, constraints and assumptions as the ADR’s starting point. Identify open issues and refer to Architecture decision and Trade-off analysis for selection and evaluation. This provides a reliable documentation context.
- Document alternatives and rationale. Bring the considered options and recorded reason for the choice into the ADR from the decision process. Refer to Architecture decision and Trade-off analysis for selection and evaluation. This keeps documentation distinct from decision-making.
- Maintain status and links. Mark records as proposed, accepted or superseded, and link implementation, views and operational information. Add a new record when direction changes. This creates a readable decision history with a clear current position.
Read the detailed explanation
An Architecture Decision Record (ADR) describes a concrete design question, its relevant context and the chosen answer. Alternatives show which options were assessed; consequences identify benefits and obligations. An ADR documents an Architecture decision and can link to relevant Architecture views.
Status and references to superseded decisions make the current position clear. When a key assumption changes, a new ADR extends the history; earlier reasons and their scope at the time remain traceable. ADRs are versioned close to code and architecture. They do not replace current operating instructions, interface documentation or implementation; links connect the decision to these sources.
Michael Nygard proposed the format in 2011 in “Documenting Architecture Decisions”.
Check your understanding
Test yourself in three stages
ReadingCheck in the picture
What decision does the ADR make in the “Decision” section?
View the solution with justification
The shop is implemented as a modular monolith; the payment provider remains an external service.
ApplyingTransferred to a new situation
The team later introduces a service variant for shipping. What do you add to the ADR?
View the solution with justification
A new ADR records the decision and refers to it. The old one receives an updated status so that the history remains traceable.
EvaluateWeighing an alternative
Is a short note “We take the monolith” enough instead of an ADR? Weigh in.
View the solution with justification
The note is quickly written. Without context, discarded option and consequences, however, the choice can no longer be checked later, for example if autonomy is needed.
Explore further
These building blocks continue the thoughts of this page.
References
- Michael Nygard – Documenting Architecture Decisions (opens in new tab)Original contribution to short decision protocols with context and consequences.
- MADR – Markdown Architectural Decision Records (opens in new tab)Provides a concrete template for options, decisions and consequences.
- AWS - Architectural decision records (opens in new tab)Explains introduction, life cycle and collaboration with ADRs.