Architecture Decision Records¶
An ADR records a decision that reaches beyond a single capability and is hard to reverse. A decision that concerns one capability belongs in that Capability Specification's Decisions section instead.
Name each ADR ADR-NNN-short-title.md, numbered in order. An ADR is frozen once a release tag
contains it; a later decision supersedes it with a new ADR instead of changing it.
This file is written by repo update; keep notes in another file.
With documentation: lean:
Template¶
# ADR-NNN: Title
**Status**: Proposed | Accepted | Superseded by ADR-NNN
**Date**: YYYY-MM-DD
## Context
The forces at play and the requirement that makes a decision necessary.
## Decision
The decision, in one or two sentences.
## Alternatives
Each considered alternative with the reason it was not chosen.
## Consequences
What becomes easier and what becomes harder.
With documentation: extended:
Template¶
The MADR template (Markdown Architectural Decision Records), for readers who expect the considered options and their pros and cons.
# ADR-NNN: Title
**Status**: Proposed | Accepted | Rejected | Deprecated | Superseded by ADR-NNN
**Date**: YYYY-MM-DD
**Decision-makers**: Everyone who took the decision
**Consulted**: Experts whose opinion was asked before the decision
**Informed**: Everyone kept up to date about the decision
## Context and Problem Statement
The situation and the problem the decision solves, in two or three sentences.
## Decision Drivers
- A force, a concern, or a requirement the decision has to satisfy
## Considered Options
1. Option A
2. Option B
## Decision Outcome
Chosen option: Option A, because it satisfies the decision drivers best.
### Consequences
- Good, because …
- Bad, because …
### Confirmation
How compliance with the decision is checked, e.g. a review or an architecture test.
## Pros and Cons of the Options
### Option A
- Good, because …
- Bad, because …
### Option B
- Good, because …
- Bad, because …
## More Information
Links to related decisions, capabilities, and issues.