Three fields: Decision, Why, Consequences. The smallest format that still captures the *why* — the field every team is tempted to skip.
Estimated size
~100–200 words
Templates · Examples · Markdown
Architecture Decision Records
An ADR is a short markdown file that captures the why of an engineering decision — committed next to the code it governs. Pick the template that matches the shape of the call you're making. Copy the markdown. Commit it. Move on.
- Templates
- 6
- Categories
- 4
- Avg. sections
- 6
- Worked examples
- 6
Lightweight
2 templatesA single sentence with seven slots. Forces you to name the option, the constraint, the consequence — in one breath.
Estimated size
~50 words
Reversible / agile
1 templateDecision + alternatives + a 'review by' date. Built for teams that revisit calls every quarter and want the ADR to remind them.
Estimated size
~200–400 words
Rich (with options)
2 templatesRich (with options)8 sections
MADR (Markdown Architectural Decision Records)
Adam Bien, Olaf Zimmermann, et al. — adr.github.io
Nygard with explicit options-considered and pros/cons per option. The format you want when there's a real comparison to make.
Estimated size
~400–800 words
The heaviest mainstream template: 12 sections, including assumptions, constraints, positions, argument, and related-decisions graph. For decisions you'll defend in front of an architecture board.
Estimated size
~1,500–3,000 words
Standard
1 templateThe original. Five sections, written in prose. The format every other ADR template is reacting to.
Estimated size
~250–500 words