Architecture Decision Records

Architecture Decision Records

No more, i have no idea why we use this, lets understand really why we made that decision.

Software solutions will be made of multiple decisions, as we progress we will need to understand when a decision is obsoleted.

We use Architecture Decision Records (ADR) to keep this context.


Architecture Decision Record (ADR)

  • An ADR is driven by a change in context (aka we found a problem)
  • Captures a decision for something we think is Architecturally signficant
  • ADR’s a immutable, where existing ADRs can be obsoleted/replced by new ones
  • they are meant to be simple
  • there are many templates, find one which suits you


As we build solutions we will make a number of decisions. for example why a database pattern was choosen or an integration technology.

Over time, some projects/products have struggled to recall why they did something. which makes it hard to understand if they should keep a certain technology or pattern.

You may hear the sentance “we have always done this”

Enter in the Decision

An Architecture Decision Record (ADR), is meant to capture the reason for a choice agsinst a problem (aka a descision).

As we record the context of why a decision was made. This allows us to review past decisions and make new informed decisions to retain or obsolete them as the context changes.

Effectively we are removing the “why do we do this?” “cos its what we have always does it.” scenario

Structure of a Decision

ADR’s in essence need to capture the context/problem and the decision/solution.

There are a number of templates out there that people use (which annotate the infromation being capture at the point in time) here is one - Simple ADR Template

I like to capture the following

  Description Simple ADR Template
Title Meaningful title for the decision ✔️
Context/Problem Description of the issue, what is the context ✔️
Status What the status is: ✔️ approved, ❌ rejected, ⭕️ obsoleted ✔️
Obsoletes List of decisions this decision obsoletes  
Obsoleted By A decision this decision obsoleted by  
Considered Options what was considered while deciding  
Spikes links to spikes you may have carried out to validate this decision  
Decision what is the change being proposed ✔️
Consequenses what are the impacts (what is made easier and harder) due to the change/decision ✔️

What you capture depends one what you find to be important.

When to capture a Decision?

Decisions are made when there is a change in context, and we what to capture the information for future reference.

as they are are events, we treat them as immutable. We can obsolete a decision by creating a new ADR, normally this would mean there is a change in context (i.e. a constraint has change like resource, money, knowledge, technology, timing etc).

© 2022 All rights reserved.