View on GitHub

Architectural Decision Records

Homepage of the ADR GitHub organization

Architectural Decision Records (ADRs)

An Architectural Decision (AD) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. An Architectural Decision Record (ADR) captures a single AD and its rationale; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM), but ADR usage can be extended to design and other decisions (“any decision record”).

The aim of the GitHub adr organization is to:

  1. Motivate the need for and benefits of AD capturing and establish a common vocabulary.
  2. Strengthen the tooling around ADRs, in support of agile practices as well as iterative and incremental engineering processes.
  3. Provide pointers to public knowledge in the context of AKM and ADRs.

The repository for the Website of the ADR organization is https://github.com/adr/adr.github.io.

ADRs in the Media

Lightweight ADRs Should be Adopted

A “lightweight” ADR consists of title, status, context, decision, and consequences (according to @mtnygard). ThoughtWorks listed architectural decision records as “adopt” at their technology radar vol. 18: https://www.thoughtworks.com/en-us/radar/techniques/lightweight-architecture-decision-records

We think that the considered options with their pros and cons are crucial to understand the reason of a chosen option. MADR — The Markdown Any/Architecture Decision Records (MADR: [ˈmæɾɚ]) in this ADR organization includes such tradeoff analysis information.

Relation of ADRs, MADR, and Others

ADR

Sustainable Architectural Decisions

We base our work on the guidelines and principles in Sustainable Architectural Decisions by Zdun et al., for instance the Y-statement format suggested in that article. However, we are open to other formats of ADRs as shown at @joelparkerhenderson’s repository.

In short, the Y-statement is as follows:

In the context of <use case/user story u>, facing <concern c> we decided for <option o> to achieve <quality q>, accepting <downside d>.

The long form of it is as follows (extra section “because”):

In the context of <use case/user story u>, facing <concern c> we decided for <option o> and neglected <other options>, to achieve <system qualities/desired consequences>, accepting <downside d/undesired consequences>, because <additional rationale>.

You can find more explanations and examples on Medium Y-Statements - A Light Template for Architectural Decision Capturing.

A Definition of Done for Architectural Decision Making proposes five criteria and a checklist to decide when it is time to set the status of a single decision to “done”: evidence, criteria and alternatives, agreement, documentation, and realization/review plan. Here, we focus on the ‘D’ in ecADR.

Existing ADR Templates

Good ADRs (and how to get to them)

Decision Capturing Tools

Disclaimer: The following list is rather inclusive. Please find out about the status and the maturity of the list entries for yourself by following the links. We are happy to include more candidate assets here.

Interesting, but unmaintained tooling

More Information

Contribute

To improve this page, head to https://github.com/adr/adr.github.io, edit index.md, and submit a pull request.