Development
Architecture decision record (ADR) template
Six months from now, someone will ask why the system works the way it does. An architecture decision record answers that in one or two pages. This template covers the context, the options you weighed, the decision, its consequences, the follow-up work and the conditions for a review.
Open this template in the editor- Category
- Development
- Default style
- Technical
When to use it
Write an ADR when a technical choice is expensive to reverse: a database, a framework, a hosting model, an API style. Future maintainers, new team members and reviewers read it to understand the constraints you faced at the time. Write it while the discussion is fresh, and keep the status line current as the proposal moves.
What is inside
- A numbered ADR title with fill-in fields for project, author and date, and a status line.
- An options table comparing benefits and costs, including a row for keeping the current approach.
- Decision, positive and negative consequences, an implementation checklist and a review trigger.
Tips for a better document
- State the decision in one sentence and give the single strongest reason. If you need five reasons, the context section probably needs more work.
- Be honest in the negative consequences. If a diagram explains the change better than prose, add a Mermaid block and it will render in the PDF.
Template preview
ADR-001: Project or topic
Author: Your name · Date: Date
Status: Proposed
Context
Describe the problem, constraints, and forces shaping this decision.
Options considered
| Option | Benefits | Costs |
|---|---|---|
| Option A | Main advantage | Main tradeoff |
| Option B | Main advantage | Main tradeoff |
| Keep current approach | No migration | Existing limitation |
Decision
State the chosen approach and the most important reason for choosing it.
Consequences
Positive: What becomes easier.
Negative: What becomes harder or more expensive.
Implementation
- Assign an owner
- Plan migration and rollback
- Update documentation
Review trigger
Specify what evidence or change would cause this decision to be revisited.
Fill-in fields such as your name and the date are replaced when you open the template in the editor.