About ADR (Architecture Decision Record)

bmf-san Architecture ja
#ADR

Overview

Explored ADR (Architecture Decision Record).

What is ADR?

ADR refers to a document that records decisions related to architecture, introduced by Michael Nygard in 2011. cf. cognitect.com - DOCUMENTING ARCHITECTURE DECISIONS

Format

Michael Nygard proposed the following format: cf. cognitect.com - DOCUMENTING ARCHITECTURE DECISIONS

  • Title
  • Context
    • The context or scenario in which the decision is made.
  • Decision
    • It is recommended to record one decision per ADR.
  • Status
    • Proposal, Approved, Deprecated, etc.
  • Consequences
    • Explanation of the context and state after applying the decision.

The document should be concise, about 1-2 pages long for readability.

Benefits of Adopting ADR

  • Easier to catch up on design decisions related to architecture.
  • Reduced frequency of discussions about clearly stated decisions.
  • Contributes to transparency of architecture within and outside the team.

Deciding Whether to Adopt ADR

  • Is it a topic repeatedly discussed within the team?
  • Is it a design decision made by the team?
  • Does it impact the overall software?

ADR can be written whenever there is a need to make architectural judgments or decisions.

Thoughts

  • In Fundamentals of Software Architecture:
  • When considering introducing ADR, it might be good to first write an ADR about introducing ADR.
  • Unlike Design Docs, ADRs seem to be preferably managed in repositories along with source code.
  • Simplifying the criteria for writing ADRs seems beneficial.
    • For example, writing ADRs for all decisions made after team discussions.
  • Searchability of ADRs:
    • Operationally, it might be helpful to ensure ADRs are searchable (especially if the number grows).
    • Categorization, tags, etc., might be useful.

References