Architecture Decision Records (ADRs)

Helpful now, invaluable later

Architectural decision

Design decisions that address architecturally significant requirements

hard to make and/or costly to change

Consider a structural change

  • How costly will this change be in time, money, and effort?
  • Does this change add complexity to the system, or simplify it?
  • Will this change require more changes?
  • What are the security implications of this change?


Oral history

PR / issues

Limits of Oral History

  • Short reach
  • Time consuming to share
  • Changes over time

Before long, important details are forgotten



Oral history

PR / issues

Title Text

  • Bullet One
  • Bullet Two
  • Bullet Three

An ideal documentation

  • Low barrier to entry
  • Value-adding, useful
  • Small, modular documents have at least a chance at being updated

What is the least we can document
and still remain effective?

is it easy to track changes? 🤔

Why to track a decision?

Without understanding the motivation behind certain decision, a new person coming on to a project has only two choices:

Blindly accept the decision

Blindly change it



Oral history

PR / issues


“An architecture decision record is a short text file in a format similar to an Alexandrian pattern that describes a set of forces and a single decision in response to those forces.”


Architecturally significant change








How would it look?

  • Title
  • Context
  • Design decision
  • Rationale
  • Status
  • Consequences


  • Markdown
  • Direct language
  • Brief, 1-2 pages max
  • Stored with the code (peer review)
# ADR N: Brief Decision Title
Context goes here. Describe the forces at play, including technological, political,
social, and project local. These forces are likely in tension, and should be called
out as such. The language in this section is value-neutral. It is simply describing
facts. Rationale should be self-evident from the context
## Decision
This section describes our response to these forces. It is stated in full sentences,
with active voice. "We will ...“
## Status
choose one: [Proposed | Accepted | Deprecated | Superseded]
if deprecated, include a rationale. If superseded, include a link to the new ADR
## Consequences
Describe the resulting context, after applying the decision. All consequences should
be listed here, not just the "positive" ones. A particular decision may have positive,
negative, and neutral consequences, but all of them affect the team and project in the

Record any architecture design decision

  • Alters externally visible system properties
  • Modifies a public interfaces
  • Directly influences a high priority quality attribute
  • Includes or removes a dependency
  • Direct result of new information about a constraint
  • Accepts strategic technical debt
  • Changes the general structures of the system
  • Forces developers to change their development approach

Involve the whole team

  • Spread knowledge 🙂
  • Easy to delegate (opportunity for training)
  • Avoiding rework
  • Impact on quality (manage technical debt)

missed the discussion meeting? no problem

Further info

Further info

  • Related work

1997: Architecture in Practice, first edition. Len Bass, Paul Clements, Rick Kazman

2002: Documenting Software Architecture: Views and Beyond, first edition. Paul Clements et al

2005: Architecture Decisions: Demystifying Architecture. Jeff Tyree and Art Akerman

2009: The Decision View's Role in Software Architecture Practice. Phillipe Krutchten

2011: A documentation framework for architecture decisions. Uwe Van Heesch, Paris Avgerioum, and Rich Hilliard

2011: Documenting Architecture Decisions. Michael Nygard


By Juan RodrĂ­guez