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 |