Complete firstDecision candidatenot in catalog
A concrete architecture choice is pending and can be stated in one sentence.
Without: Without a real decision, the record becomes a generic note and future readers cannot tell what was actually decided.
RunsheetArchitecture
Architecture Decision Record
ComplexityLow
Time15-45 min
Participants1-3
FormatAsync
MaturityCanonical
01
Prerequisite
What needs to be finished first
02
Preparation
What needs to be ready before start
Materials
ADR template or Markdown file; decision log; architecture sketch; links to relevant tickets, diagrams, and constraints; timer.
People / roles
One decision owner and one reviewer or architect; optionally a subject-matter expert or engineer with system context.
Pre-read
Problem statement, context, candidate options, constraints, and any non-negotiables.
Time needed
15-45 min
Setup
Open the ADR in one file and add sections for status, context, decision, consequences, and links. Keep the decision visible as one sentence at the top.
03
Core question
The one question this method answers
Which architecture decision needs to be recorded, and what context, options, decision, and consequences must a future reader understand?
04
Flow
Marker: Sektion
| Step | Duration | Action | Hint |
|---|---|---|---|
1Section 1: Name the decision | 3-5 min | Write one sentence that captures the exact architecture decision. Make the boundary of the decision explicit. | If the sentence still contains two decisions, split it before continuing. One ADR should answer one question. |
2Section 2: Describe the context | 4-8 min | Capture the problem, constraints, and relevant facts that led to the decision need. | If the context starts to describe the solution, move that material to the options section. |
3Section 3: Record the options | 4-10 min | List 2-4 realistic options and write the main trade-offs for each one. | If only one option seems possible, the decision is probably already fixed or the problem is not fully framed yet. |
4Section 4: Document the decision | 3-7 min | Select the chosen option and explain why it wins in this context now. Add who decided and when. | Do not hide the decision in a sentence fragment. A future reader should be able to point to the chosen option immediately. |
5Section 5: Capture consequences | 3-8 min | Write down the consequences, follow-up actions, and links to supporting material or follow-on tickets. | Include what would make the ADR need revision so the record stays alive instead of frozen. |
05
Artifact
What comes out at the end
Form
One ADR document with status, context, decision, options, consequences, and links to supporting material.
Versioning / ownership
Store the ADR beside the code or in the team documentation home. Add date, status, and owner in the header. If the decision changes, create a new ADR or revision entry and keep the old version readable.
Tool alternatives
- Markdown file in the repo
- Confluence page in the architecture space
- Notion page with a decision template
- Plain text note in Obsidian or a shared doc
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:
- ...
06
Example output
Concrete filled scenario, fictional example
adr-beispiel.md
Concrete filled scenario, fictional example
ADR - Split billing API from checkout core, 2026-07-01
Status: Accepted
Context
The checkout service owns customer-facing order flow, but billing retries create noisy failures and increase deploy risk.
Decision
Move retry handling into a dedicated billing API behind the existing checkout boundary.
Consequences
- Checkout code gets simpler and easier to ship.
- Billing now owns retry-specific observability and alerting.
- Existing consumers keep the same external contract while the internals change behind a feature flag.
07
Pitfalls
Recognize symptoms and steer against them
Trap
The decision is too vague
Symptom
The title says something like "improve the architecture" and no one can tell what changed.
What to do
Rewrite the first section until one reader can summarize the choice in a single sentence without guessing.
Trap
Context turns into solution text
Symptom
The context section already contains the chosen implementation and the options become decorative.
What to do
Strip solution language out of the context and move it into the options section.
Trap
Options are fake or incomplete
Symptom
Only the preferred option is written down and the trade-offs stay hidden.
What to do
Add at least one credible alternative that a competent reviewer would actually consider.
Trap
Consequences are skipped
Symptom
The ADR ends with the decision, so no one knows what will happen next.
What to do
Add explicit consequences, follow-up work, and the condition that would trigger a revision.
Trap
The record is not readable later
Symptom
The ADR is stored in a place nobody can find or understand after the project moves on.
What to do
Store it where the team already looks for architecture context and keep the file title and header obvious.
08
Stop criteria
Done signals checkable in under a minute
No concrete architecture decision is pending.
The decision has already been made and only needs simple execution notes.
The context is too thin to compare options honestly.
No one present can confirm the constraints or non-negotiables.
The topic is a trivial implementation detail that does not need a long-lived record.
The team expects a broad design discussion instead of a documented decision.
Finished the runsheet?
Go to the profile for purpose, similar methods, and sources or continue to the next method in the catalog.