Framework library · Technology management
Architecture decision record
An architecture decision record captures one decision that shapes a system, written when the decision is made: the forces at play, the options, the decision and every consequence, good and bad. Records are numbered, kept with the code and never rewritten, only superseded, so someone who joins later can accept or reverse a decision knowing why it was made.
Use it when
- A decision will shape the structure, interfaces or running cost of a system for years, and the people who made it will not always be there.
- A past decision keeps being reopened because nobody can remember why it was made.
- Several teams or suppliers have to work to the same architecture and need the reasons as well as the rules.
Avoid it when
- The decision is easy to reverse and affects one team. A note in the code or the ticket is enough.
- The options have not yet been compared. Score them first with a build, buy or partner comparison or a weighted decision matrix, then record the outcome here.
- The question is who decides future changes. That is about decision rights; use a RACI matrix.
How to run it
Give the record a number and a short title
Number records in sequence and never reuse a number. The title is a noun phrase: "ADR 7: Cross-connect ordering through the existing order system".
Write the context as facts
The technical, commercial and organisational forces at play, including those in tension. Keep the language neutral; the argument comes later.
List the options you considered
Include the ones you set aside quickly, with the reason. A record with one option reads like a justification written afterwards.
State the decision in full sentences
In the active voice, starting "We will". One decision per record.
Write every consequence
Good, bad and neutral: what becomes easier, what becomes harder and what now has to be done. The bad consequences are what later teams most need to know.
Set the status and the review trigger
Proposed, accepted, deprecated, or superseded by a named later record. Write the event or date that should send someone back to it.
Work through it
Answer the questions below, or load the worked example to see a finished one. The drawing updates as you type. Export the result as a PowerPoint deck, a Word document, an Excel workbook, a PDF or plain text.
What you type stays in this browser, so you can close the page and come back to it. It is not sent to Blue Prysm or anyone else, and the exports are made here, on your device. Privacy policy.
Mistakes to avoid
- Editing an accepted record when circumstances change. Write a new record that supersedes it, so the history stays readable.
- Writing records after the fact to satisfy a process. The context is then reconstructed from memory and is usually wrong.
- Leaving out the negative consequences. A record that lists only benefits reads as a sales document, and the next team will not trust it.
- Storing records where engineers do not look. Keep them with the code or the system documentation they describe.
Where it comes from
Michael Nygard, "Documenting Architecture Decisions", Cognitect blog, 15 November 2011, which proposed short, numbered records with a title, context, decision, status and consequences, kept in the project repository and marked as superseded rather than edited when a decision changes. Later templates add the options considered, among them MADR (Markdown Architectural Decision Records), which reached version 4.0 in 2024. Source.
Use it with
Work through it with us
The frameworks here are free to use as they stand. If you would rather work through the question behind this one with us, these are the ways an engagement starts.