Why Write an Architecture Decision Record
An Architecture Decision Record (ADR) is a short document that captures a single decision relevant to a product or ecosystem. An ADR is typically a couple of pages long and contains the decision itself, the context that led to it, and its significant ramifications.
ADRs serve two distinct purposes. They provide a record that allows people months or years later to understand why a system is constructed the way it is. More valuable, though, is the act of writing: the discipline of documenting a consequential choice often surfaces differing points of view, forcing discussion and resolution within a team.
Structure and Content
Records should follow an "inverted pyramid" style, common in news writing, putting the most important material first and pushing details toward the end. Each ADR should address:
- The decision made
- A brief rationale, summarizing the problem and trade-offs considered
- The ramifications of the decision
- A confidence level, useful since decisions are often made under uncertainty
It is valuable to explicitly list all serious alternatives that were considered, with their pros and cons, similar to the notion of "forces" in pattern writing. The confidence section is also a good place to mention changes in product context that should trigger a reevaluation of the decision.
Status and Lifecycle
Each ADR has a status. It remains "proposed" while under discussion, becomes "accepted" once the team agrees and it is active, and is marked "superseded" when replaced, with a link to the superseding ADR. An accepted ADR should never be reopened or edited; instead it should be superseded. This approach gives a clear log of how long each decision governed the work.
Storage and Tooling
The common advice is to keep decision records in the source repository of the code base they apply to, often in doc/adr. This keeps them available to developers and allows them to be diffed and worked with like code. Writing them in a lightweight markup language such as markdown supports this. A build task can publish them to a product team's website.
This storage model breaks down for ADRs covering a broader ecosystem than a single code base, and some find that git-based storage makes it difficult for non-developers to contribute. Each record should be its own file, numbered in a monotonic sequence with a descriptive name, such as 0001-HTMX-for-active-web-pages, so directory listings are readable.
Collaboration and the Advice Process
ADRs play a central role in the Advice Process, where they are used not only to document decisions but also to elicit expertise and alignment. In this context, ADRs should include the advice gathered during their formation. To keep records brief, the advice may be summarized in the ADR with a full record maintained separately.
Brevity First
The most important guideline is brevity. Keep an ADR short, typically a single page, and link to any supporting material rather than embedding it. While ADRs are a software architecture form, the broader practice of writing short decision records can create a valuable historical log in other contexts, explaining why things turned out the way they did.
Further Reading
Michael Nygard coined the term "Architecture Decision Record" in an article in 2011. He was inspired by Phillipe Kruchten's work on decision registers and by software patterns writing style, and he made the case for a lightweight document focused on the decision itself. His original article remains the primary reference on the topic.
Brief examples of ADR formats are available in articles by Harmel-Law and by Rowse and Shepherd. The adr-tools command line utility manages ADRs and includes a set of ADRs for itself that serve as a good example of the form.
