Architecture Decision Record
Purpose
Write a concise, durable record of a material technical decision so future contributors can understand the context, trade-offs, and consequences without reconstructing the discussion.
Workflow
- Confirm that a real architecture or technology decision is being made; do not create an ADR for routine implementation detail.
- Assign a stable identifier and a short active-voice title.
- Describe the context, constraints, decision drivers, and relevant stakeholders.
- Record the chosen decision precisely, including the intended scope and status: proposed, accepted, deprecated, or superseded.
- Compare meaningful alternatives and explain the evidence or trade-offs behind the choice.
- State positive, negative, and neutral consequences, including migration or operational effects.
- Link related decisions or supporting evidence when available, then deliver the ADR for review.
Output template
Use these headings: Status, Context, Decision, Alternatives considered, Consequences, and References. Keep the record self-contained and concise.
Quality boundaries
Do not fabricate consensus, benchmarks, approvals, or cost estimates. Preserve uncertainty where it remains. An ADR documents a decision; it does not replace a design review, security review, or implementation plan.
Error handling
| Situation |
Response |
| Decision is still exploratory |
Recommend a time-boxed spike or options analysis before creating an ADR. |
| No clear decision owner |
Mark ownership as unresolved and request the needed governance context. |
| Prior decision exists |
Cross-reference it and use the correct supersession status. |
| Alternatives lack evidence |
State the limitation and identify the next validation step. |
1---2name: architecture-decision-record3description: Document a significant technical decision with its context, alternatives, consequences, and status. Use for: architecture decision record, ADR, technical decision log, technology choice.4license: Apache-2.05---67# Architecture Decision Record89## Purpose1011Write a concise, durable record of a material technical decision so future contributors can understand the context, trade-offs, and consequences without reconstructing the discussion.1213## Workflow14151. Confirm that a real architecture or technology decision is being made; do not create an ADR for routine implementation detail.162. Assign a stable identifier and a short active-voice title.173. Describe the context, constraints, decision drivers, and relevant stakeholders.184. Record the chosen decision precisely, including the intended scope and status: proposed, accepted, deprecated, or superseded.195. Compare meaningful alternatives and explain the evidence or trade-offs behind the choice.206. State positive, negative, and neutral consequences, including migration or operational effects.217. Link related decisions or supporting evidence when available, then deliver the ADR for review.2223## Output template2425Use these headings: **Status**, **Context**, **Decision**, **Alternatives considered**, **Consequences**, and **References**. Keep the record self-contained and concise.2627## Quality boundaries2829Do not fabricate consensus, benchmarks, approvals, or cost estimates. Preserve uncertainty where it remains. An ADR documents a decision; it does not replace a design review, security review, or implementation plan.3031## Error handling3233| Situation | Response |34|---|---|35| Decision is still exploratory | Recommend a time-boxed spike or options analysis before creating an ADR. |36| No clear decision owner | Mark ownership as unresolved and request the needed governance context. |37| Prior decision exists | Cross-reference it and use the correct supersession status. |38| Alternatives lack evidence | State the limitation and identify the next validation step. |
Stijnman