Practice : Architecture Decision Records (ADRs)

Purpose and Strategic Importance

Architecture Decision Records (ADRs) are lightweight documents that capture important decisions made during software design. They document context, trade-offs, and rationale so that future engineers understand why something was chosen - even if it later changes.

By using ADRs, teams make technical decision-making transparent, traceable, and shareable. They reduce knowledge loss, accelerate onboarding, and support alignment across teams working on complex systems.

Description of the Practice

  • Each ADR describes a single architectural or technical decision.
  • Follows a consistent structure: context, decision, status, consequences.
  • Stored in version control alongside the codebase for easy access and review.
  • ADRs evolve - new ones can supersede outdated decisions.
  • Can be authored collaboratively by engineers, architects, and stakeholders.

How to Practise It (Playbook)

1. Getting Started

  • Create an adr/ directory in your repo and agree on a template format.
  • Write ADRs for key decisions like technology choices, service boundaries, data contracts.
  • Keep ADRs focused and concise - they are not formal specs or design docs.
  • Review ADRs during retrospectives or architecture forums to ensure visibility.

2. Scaling and Maturing

  • Tag ADRs by domain, team, or architectural theme.
  • Link ADRs to RFCs, tickets, or epic documentation for traceability.
  • Use automation to flag stale or superseded ADRs for review.
  • Create a knowledge base or index to help teams discover decisions across the organisation.
  • Include ADR review in onboarding to ramp up new engineers quickly.

3. Team Behaviours to Encourage

  • Write down decisions while they’re fresh - don’t wait for perfection.
  • Make ADRs inclusive - engineers of all levels should contribute.
  • Use ADRs to promote healthy debate and decision rigour.
  • Revisit ADRs after major incidents, replatforming, or technical pivots.

4. Watch Out For…

  • Writing ADRs too late or with insufficient context.
  • Using ADRs as justification rather than exploration.
  • Creating ADRs that are never updated or referenced.
  • Rigidly enforcing ADRs that no longer make sense.

5. Signals of Success

  • Engineers understand why past decisions were made - even if they disagree.
  • Teams align on changes through shared context and rationality.
  • Architecture evolves responsibly - not reactively.
  • New joiners ramp up faster by reading ADRs.
  • Decisions feel inclusive, documented, and explainable.