Architecture Decision Record Template
Lay out what drove a decision, the options weighed, what was decided and what follows, and keep the full reasoning behind every tile.
Free forever on the Personal plan
Architecture decision records: an example
The trade-off at a glance
Drivers, options and consequences side by side, with the choice in green.
Status and deciders on record
Proposed, accepted or superseded, with who decided and when.
A decision log
One blueprint per decision, filed in a portfolio as the team's log.
The basics
What is an architecture decision record?
An architecture decision record (ADR) captures one significant architecture decision: the context, the drivers, the options considered, the decision made and its consequences, with a status such as proposed, accepted or superseded, and the date and deciders. ADRs build up into a log that explains why a system is the way it is.
Most ADRs are short markdown files, easy to write and easy to lose. A decision map makes the trade-off visible to people who will never read the text, and keeps the full record one click behind each part of it.
In Blueprintr an ADR is a blueprint whose diagram is the decision map: each driver, option and consequence opens a stratum, and the standard ADR sections sit beside it as text.
Why Blueprintr
Decisions people can find and follow
The trade-off on one diagram, the record behind every tile.
Decision maps
Draw drivers, options, the decision and its consequences as columns of tiles, with the chosen option in green and the rejected ones dashed.
VellumReasoning behind every tile
Give each driver, option and consequence a stratum with its evidence and a table of what is for and against it.
StratumAn ADR template to start from
The Compendium's ADR template has the decision map, the standard sections, an options matrix, an ADR index and a writing guide.
A decision log
File each ADR in a portfolio with notes and links beside it, so the team's decisions are kept in one place, in order.
BlueprintsSuperseded, not rewritten
Each publish keeps a snapshot, so the accepted text is preserved. On the Team plan you can browse and compare earlier versions.
Objections beside the decision
Questions and objections go in the ADR's Discussion tab, in threads, where the next reader will find them.
How to
How to write an ADR in Blueprintr
Create a blueprint
Sign up free and create a blueprint, or start from the ADR template in the Compendium.
Write the context and drivers
Add a tile for each driver and a stratum with the evidence behind it.
Lay out the options
Add a tile for each option with a stratum of what is for and against it.
Record the decision
Add the decision and its consequences, and set the status, date and deciders.
Publish and file it
Publish the ADR and file it in the portfolio that holds your decision log.
Start from a template
Architecture decision record (ADR)
A decision map of drivers, options, decision and consequences, the standard ADR sections, an options comparison matrix, an ADR index and a writing guide.
FAQ
Questions about architecture decision records
Is this ADR template free?
Yes. The Vellum editor, strata, portfolios and the Compendium's ADR template are available on the free Personal plan. Browsing and comparing versions is part of the Team plan.
What should an architecture decision record include?
A number and title, the status, date and deciders, the context and drivers, the options with their pros and cons, the decision itself, its consequences, and any ADR it supersedes.
What format should an ADR use?
Most teams use the short format of title, status, context, decision and consequences, often extended with drivers and options. The Compendium template follows that structure, with a decision map in front.
Can I keep ADRs in Git?
On the Team plan, a folium can sync markdown pages with GitHub.com or GitLab.com: it pulls pages in, and pushes changes to a new branch for review. Any blueprint can also be exported as markdown.
Should I edit an accepted ADR or write a new one?
Write a new one. An accepted ADR records what was decided and why at the time; when the decision changes, a new ADR supersedes it and both stay in the log.
Who should approve an architecture decision?
Usually a design authority or architecture board. On team-owned blueprints, Blueprintr can require named approvers to sign off before a change to the ADR is merged and published.