View on GitHub

Homepage of the ADR GitHub organization

Architectural Decision Records

An Architectural Decision (AD) is a software 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 a software system’s architecture and quality. An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; 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). Note: This short intro to ADRs is based on information in Joel Parkerhenderson’s GitHub repo.

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 software engineering processes
  3. Provide pointers to public knowledge in the context of AKM and ADRs (for instance, this website)

Note: The term “architecture decision record” can be used interchangeably.

Lightweight Architectural Decision Records Should be Adopted

ThoughtWorks lists architectural decision records as “adopt” at their technology radar.

We offer MADR - The Markdown Architecture Decision Records (MADR: [ˈmæɾɚ]) to do so.

Offered Projects

Relation of ADRs, MADR, and others


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

In short, that 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:

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>.

Existing ADR templates