99agile
Kristoffer Bohmann's articles on agile product management

Architecture decision record (ADR)

An Architecture Decision Record (ADR) is a document that captures important architectural decisions made during the development of a software system, along with their context and consequences. ADRs serve as a valuable tool for documenting, communicating, and preserving the reasoning behind significant design choices.

In this article

Core Concepts

  • Architecture Decision (AD): A software design choice that addresses a significant requirement
  • Architecture Decision Log (ADL): The collection of all ADRs created for a specific project or organization
  • Architecturally-Significant Requirement (ASR): A requirement with measurable impact on a system's architecture
  • Architecture Knowledge Management (AKM): The broader discipline of managing architectural knowledge

Purpose of ADRs

ADRs provide several benefits:
  1. Knowledge preservation: They document the reasoning behind decisions that might otherwise be forgotten
  2. Onboarding: They help new team members understand past decisions
  3. Future decision-making: They provide context for future architectural choices
  4. Communication: They facilitate clear communication about architecture across teams

Implementing ADRs

Decision Identification
  • Assess urgency and importance of each architectural decision
  • Determine if decisions must be made immediately or can wait for more information
  • Use personal and collective experience, along with established design methods
  • Maintain a decision todo list alongside your product todo list
Decision Making Process
  • Utilize various decision-making techniques (general and software-specific)
  • Consider group decision-making approaches where appropriate
  • Document the process used to reach the decision
Decision Documentation Consider including these elements in your ADRs:
  1. Title: A descriptive name for the decision
  2. Status: Proposed, accepted, rejected, deprecated, superseded, etc.
  3. Context: The situation that necessitates the decision
  4. Decision: The actual choice made
  5. Consequences: The results of implementing the decision (both positive and negative)
  6. Compliance: How adherence will be verified
  7. Notes: Additional relevant information
Decision Enactment and Enforcement
  • Communicate decisions to all stakeholders who develop, fund, or operate the system
  • Implement architecturally-evident coding styles
  • Conduct architecture-focused code reviews
  • Revisit decisions during system modernization and evolution
Decision Sharing
  • Recognize that many architectural decisions recur across projects
  • Share experiences (both positive and negative) as reusable assets
  • Implement explicit knowledge management strategies

Tools and Templates for ADRs

You can implement ADRs using various tools:
  • Version Control: Create markdown files in source code repositories
  • Document Management: Use Google Docs or other collaborative editing tools
  • Project Management: Integrate into tools like Jira or Azure DevOps
  • Wikis: Implement using MediaWiki or other wiki platforms
  • Specialized Tools: Use purpose-built ADR management software

Sample ADR Structure 

# Title: [Decision title]

## Status
[Proposed/Accepted/Rejected/Deprecated/Superseded]

## Context
[Description of the problem and relevant constraints]

## Decision
[Description of the decision made]

## Consequences
[Description of the consequences, both positive and negative]

## Compliance
[How will compliance with this decision be verified?]

## Notes
[Additional relevant information]
ADRs are lightweight yet powerful tools that help teams make better architectural decisions while preserving knowledge for future reference. By systematically documenting significant design choices, organizations can build more resilient, maintainable software systems.