Architecture Decision Records (ADR) · Architecture as Code: the course

All courses / Architecture as Code / Module 1 / Chapter 4

Learning objectives

After the lesson the participant can:

Describe the four core sections of an ADR and the purpose of each.
Explain the status lifecycle and why a changed decision is superseded by a new record.
Draft an ADR for a real decision, with consequences and mitigation.
Outline how discovery, review and supersession of ADRs can be automated in a Git workflow.

Key concepts

Architecture Decision Record: A short text document that captures an important architecture decision together with its context and consequences. The method was introduced by Michael Nygard in 2011, and the chapter calls ADRs the commit messages of the architecture.
Status lifecycle: An ADR is proposed, accepted, deprecated or superseded. A deprecated decision is no longer recommended but may remain in the system; a superseded one is replaced by a newer ADR and references its successor.
Permanent numbering and supersession: ADRs are numbered sequentially and keep their number even when deprecated or replaced. Versioning lives in the Git history: when a decision changes, a new ADR supersedes the original, preserving the historical context.
Code-managed discovery, review and supersession: A bot scaffolds a draft ADR when a backlog item carries a label such as architecture-impact, continuous integration lints the front matter and fails on missing metadata, and a scheduled pipeline posts reminders when the next review date passes.
Review debt tracker: A dashboard widget derived from ADR metadata that flags records whose next review date has passed, so that leadership can prioritise refresh work in sprint planning.

Interactive exercises

Do them here and get feedback at once. Choose a card and then where it belongs, or drag it.

Interactive exercise 1 · Match

ADR status and required action

Match each status in the lifecycle of an Architecture Decision Record to the action the chapter says it requires.

Interactive exercise 2 · Scenario

Inheriting a service after a rotation

Read the situation and choose what the chapter's reasoning leads to. Each choice gives feedback.

Teaching plan

10 min	Teacher introduces the ADR, its four sections and the status lifecycle, and why numbering is permanent.
15 min	Participants read ADR-0003 on Terraform and ADR-0007 on PostgreSQL and mark where context, decision, consequences and mitigation are each done well.
10 min	Teacher explains ADRs as code: discovery, review and supersession automation, the three dashboard widgets and the handover checklist.
30 min	Exercise: each participant drafts an ADR, then swaps with a neighbour for a review against the template.
10 min	Plenary on what the reviews found, closing with the summary point that an ADR takes minutes to write while the decision is fresh.

Discussion

Why does the chapter prefer a new superseding ADR to editing the original, and what would be lost by editing in place?
Which architecture decisions in your organisation would be impossible to reconstruct today because the people involved have moved on?
What makes a negative consequence worth writing down in a record that is meant to justify the decision?

Written exercise

Exercise · 30 minutes

Write and review an Architecture Decision Record

Choose a significant architecture decision that your own organisation has recently made or is about to make. Write it as an ADR following the chapter's structure: a sequential identifier and short title, status, context (problem statement, constraints, driving forces, affected stakeholders), decision (clear statement of choice and rationale), consequences split into positive and negative, and mitigation. Add the review metadata the chapter mentions, including the date of the last review and the date the next review is due, and note where the decision was discussed. Swap with a neighbour and review each other's record: is the negative side honest, and could a newcomer understand why the choice was made?

Deliverable: One complete ADR of about a page with front matter, the four core sections and mitigation, plus the neighbour's written review comments.

Your work

Self-test

Choose an answer to see whether it is right, or open the answer below each question.

What happens to the number of an ADR when the decision it records is replaced?
Show the answer
D. The original keeps its number and a new ADR supersedes it
Numbering is permanent: even a deprecated or replaced ADR retains its number, and a new ADR is created to supersede it so the historical context is preserved.
Where does the chapter, following the Lightweight Architecture Decision Records technique, recommend storing decision records?
Show the answer
B. In source control, so that they stay in sync with the code
The chapter cites the Thoughtworks Technology Radar technique, which recommends storing decision records in source control rather than a wiki so that they remain in sync with the code itself.
In the worked example ADR-0003, which negative consequence of choosing Terraform is recorded?
Show the answer
A. Complexity in state file management
The negative consequences listed are the learning curve, complexity in state file management, cost of commercial features and the licence change. Multi-cloud support, a declarative syntax and a large community are listed as positives.