methodatlas
Architecture

Architecture Decision Record

Turns architecture context, options, and consequences into a tangible result by naming the decision, describing context, and capturing consequences.

Core question
Which architecture decision needs to be recorded, and what context, options, decision, and consequences must a future reader understand?
LowAsync15-45 min
Open runsheetPlan sessionStart comparison
Purpose

The method helps clarify architecture context, options, and consequences concretely. It organizes technical context, alternatives, and consequences. The result is captured as an ADR file, decision log, and rationale.

How it works

The team follows the steps: name the decision, describe context, capture options, document the decision, and capture consequences. Each step is captured visibly. At the end, an ADR file, decision log, and rationale are available so decisions, tests, or actions can follow directly.

Visual orientation

Method sketch for a quick mental model.

Architecture Decision Record · EntscheidungsrationaleKontext, Optionen, Entscheidung, Konsequenzen und Status versioniert festhalten
Architecture Decision RecordDie Skizze zeigt, wie Entscheidungskontext, Optionen, Entscheidung, Konsequenzen und Status in einem Architecture Decision Record nachvollziehbar dokumentiert werden.Architekturentscheidung als nachvollziehbaren Record sichernKontext, Optionen, Entscheidung und Konsequenzen bleiben versioniert auffindbar.EntscheidungsraumEntscheidungsbedarfADR RecordKurzes versioniertes EntscheidungsdokumentDecision LogStatus und NachvollziehbarkeitProblemWas wird entschieden?KontextConstraints und TreiberStatusProposed/AcceptedContextWarum ist das relevant?OptionsWelche Wege gab es?DecisionWas gilt jetzt?ConsequencesFolgen, Risiken, Trade-offsAcceptedgültige EntscheidungLinked to Codenah am RepositorySupersededdurch neue ADR ersetzt1Proposed2Accepted3Superseded

Flow

  1. 1Name the decision
  2. 2Describe context
  3. 3Capture options
  4. 4Document the decision
  5. 5Capture consequences

The runsheet guides execution with 5 phases, timeboxes, 5 pitfalls, and clear stop criteria.

Open runsheet

Ideal for

  • Architecture governance
  • Team memory
  • High-change codebases

Not good for

  • Trivial decisions
  • Long specifications

Deep dive

In detail

Architecture Decision Record follows a clear working logic: name the decision, describe context, capture options, document the decision, and capture consequences. This turns the method into a visible thinking process rather than only a conversation. Participants move step by step from raw material, observations, or options toward a shared structure. The result is an ADR file, decision log, and rationale that make decisions, learning, or further planning actionable.

Facilitation

Prepare a clear guiding question, the right information, and a visible workspace. Plan about 15-45 min with 1-3 people and use the format asynchronously. The facilitation stays lightweight; short timeboxes, visible intermediate results, and a parking lot for open questions help.

Output artifacts
ADR FileDecision LogRationale
Tags
architecturerationaledocumentationgovernance

Sources

Documenting Architecture Decisionscognitect.comArchitectural Decision Records (ADRs) | Architectural Decision Recordsadr.github.io
Artifact templates
ADR Markdown TemplateCompact template for architecture decision records in a repository or wiki.
markdown

adr-markdown.md

Compact template for architecture decision records in a repository or wiki.

ADR-0001: Decision Title

Status: proposed Date: YYYY-MM-DD Decider: First Last Trigger: Ticket, incident, or RFC

Context

What situation makes the decision necessary? Which constraints, quality attributes, or earlier decisions matter?

Options

Option 1: ...

  • Pros:
  • Cons:

Option 2: ...

  • Pros:
  • Cons:

Decision

We decide to ...

Consequences

Positive consequences:

  • ...

Negative consequences and risks:

  • ...

Follow-up ADRs or tickets:

  • ...

When to choose differently

Short decision aid for existing alternatives.

Architecture Inception Canvas

Statt Architecture Decision Record, wenn du die ersten Architekturfragen in einer knappen Startfolie bündeln willst.

Similar methods

All methods
Architecture
Views and Beyond

Turns architecture context, options, and outcomes into a tangible result by identifying stakeholders, selecting views, and validating completeness.

Architecture
arc42

Turns architecture context, options, and consequences into a tangible result by capturing goals and stakeholders, scoping context, and linking risks and decisions.

Architecture
Request for Comments

Uses a structured proposal and review process to make non-trivial technical or product changes discussable and decidable.

Architecture
Architecture Inception Canvas

Turns architecture context, options, and consequences into a tangible result by defining the problem, collecting goals and constraints, and determining next investigations.

Statt Architecture Decision Record, wenn du die ersten Architekturfragen in einer knappen Startfolie bündeln willst.

Architecture
C4 Model

Turns architecture context, options, and consequences into a tangible result by drawing system context, identifying containers, and adding code-level detail only when needed.

Architecture
Risk Storming

Moves architecture context, options, and consequences toward a concrete result through "place the architecture diagram or plan in the center", "set risk categories such as technical, organizational, and external", and "assign an owner and next steps for each top risk".