Summary

Martin Fowler explains Architecture Decision Records (ADRs) as short documents that capture individual architectural decisions along with their context and consequences. He emphasizes that ADRs serve dual purposes: creating a historical record for future reference and clarifying thinking during the decision-making process. The post outlines practical conventions including storing ADRs in source repositories, using lightweight markup, maintaining immutable records with status tracking, and keeping documents brief. Fowler traces the concept back to Michael Nygard's 2011 article and notes ADRs' central role in the Advice Process for eliciting expertise and alignment.

Key Insight

The greatest value of Architecture Decision Records lies not in the document itself but in the act of writing them, which forces teams to surface disagreements, clarify thinking, and reach genuine alignment.

Spicy Quotes (click to share)

• 3

  Perhaps even more valuable, the act of writing them helps to clarify thinking, particularly with groups of people.

• 4

  Writing a document of consequence often surfaces different points of view - forcing those differences to be discussed, and hopefully resolved.

• 4

  Once an ADR is accepted, it should never be reopened or changed - instead it should be superseded.

• 2

  That way we have a clear log of decisions and how long they governed the work.

• 3

  Decisions are usually made under some degree of uncertainty, so it's handy to record the confidence level of the decision.

• 2

  This kind of decision log creates a valuable historic record that can do much to explain why things are the way they turned out.

• 3

  The most important thing to bear in mind here is brevity. Keep the ADR short and to the point - typically a single page.

Tone

authoritative, practical