Architecture Decision Record Template
A one-page ADR you will actually fill in, the decision, the forces behind it, the options rejected and why, the consequences accepted, and the conditions that would make you revisit it.
Markdown. No sign-up, no email.
One decision per record. One page. Written when the decision is made, not reconstructed afterwards: the reasoning is the point, and reasoning evaporates within about two weeks.
File as
docs/adr/NNNN-short-title.mdin the repository the decision affects.
ADR: _____ Title: _______________ Date: _______ Status: proposed / accepted / superseded by ADR ____ Deciders: _______________
Context#
What is true that forces a decision now? Facts and constraints only, no options yet.
- Current state: _______________
- What changed, or what is about to: _______________
- Constraints that are real (deadline, budget, skills present, systems that cannot move): _______________
- Constraints that are assumed but unverified: _______________
Separating those last two lines is the highest-value part of this document. Half of all architecture is built around constraints nobody has checked in three years.
Decision#
We will: _______________
State it in the active voice, in one or two sentences, specific enough that someone could disagree with it.
Options considered#
| Option | Why it was attractive | Why it was rejected |
|---|---|---|
| Do nothing / defer |
The "do nothing" row is mandatory. If it was never genuinely considered, this is a justification, not a decision record.
Consequences accepted#
What gets better: _______________
What gets worse: _______________
What we can no longer do easily: _______________
Who has to change how they work: _______________
A decision with no negative consequences has not been thought about. Write the cost down while you are still willing to admit it.
Cost and reversibility#
| One-way or two-way door? | one-way / two-way |
| Estimated effort to implement | |
| Estimated effort to reverse in 12 months | |
| Ongoing run cost |
If it is a two-way door, decide quickly and move on. If it is one-way, the rest of this page deserves an hour of somebody's full attention.
What would make us revisit this#
| Trigger | Who watches it |
|---|---|
| Scale beyond ___ | |
| Cost above ___ | |
| Latency above ___ | |
| A dependency changing | |
| Date to review |
An ADR without revisit conditions becomes permanent by accident. Most bad architecture is a good decision that outlived its context.
Compliance and data#
| Personal data involved | yes / no |
| Data residency implications | |
| New third party introduced | |
| Security review needed | yes / no, date |
| Accessibility impact |
References#
- Related ADRs: _______________
- Prototype / spike results: _______________
- Measurements this was based on: _______________
If the "measurements" line is empty, mark the decision as reversible and set a review date. A decision made on intuition is not necessarily wrong, but it should be labelled as such so a future reader knows how much weight to give it.
Sign-off#
| Name | Date | |
|---|---|---|
| Author | ||
| Reviewer | ||
| Accepted by |