Cloud Architecture
Intermediate 13 min read Cloud Architecture

Architectural Decision Records

Write the decision, so the decision survives you

ADR (When, Why, What): a lightweight, git-versioned record of every important architecture choice — Context, Decision, Consequences, Alternatives, Trigger. Teams that ADR survive turnover; teams that don't re-live the same debates.

ADRdecision recordcontextconsequencestriggergit-versionedreview
Prerequisites: Design Tradeoffs
Before we start

What you will learn

  • Write an ADR structured (Context/Decision/Consequences/Triggers)
  • Keep them reviewable in PR + versioned
  • Use them in reviews to audit past choices
In 60 seconds

ADR format: a short markdown file per decision — Status, Context (why now), Decision (what), Consequences (pros/cons), Alternatives (considered), Trigger (when to revisit). Git-history + PR review = the decision is reviewable + linked; a living archive, not dead letters.

Introduction

What is this?

Format (Michael Nygard-ish): Title, Status (Proposed/Accepted/Superseded), Context (forces, constraints, problem), Decision (the choice), Consequences (+ive/–ive), Alternatives (what else was evaluated + how rejected), Trigger-to-revisit. Lightweight: 20-100 lines, jargon-free. Practice: every non-trivial pick (store, tier, pattern, tool) gets one; a single `adr/` directory, numbered, git-history; PR-reviewed; supersede old ones (don't edit). Review usage: on incidents/delays, read the ADRs to see 'what did we trade for this' — the doc answers it. Failure modes: ADR you'll bloat (patch-vendorized), never read, or ADR that fossilize (no trigger). The review cadence that keeps them alive: quarterly ADR review against current constraints.

Motivation

Why do you need it?

  • Turnover is the biggest destroyer of architecture knowledge — the ADR is the team memory that survives.
  • A decision without a written 'why' is revisitable by everyone who regrets it (and rewrites realistically).
  • PR-reviewable decisions → the whole team participates and challenges, not just the senior's brain.
  • The trigger keeps the decision fresh: constraints change, the ADR re-opens — decisions live, not fossilize.
Think about it

Mental model

Imagine

A property deed with a written 'why this boundary' clause — decades later the reason is still discoverable

Think of

ADR

Boundaries (decisions) without deeds become he-said disputes. The ADR is the deed: recorded, versioned, and the 'why' travels with the change.

Mechanics

How it works

  • Start a lightweight template; write ADR at the moment of decision (PR with the code).
  • Keep it short: Context/Decision/Consequences/Alternatives/Trigger.
  • File under adr/NNN-title.md, git-history, reviewed in PR.
  • Supersede (new ADR) rather than edit history; keep the archive linear.
  • Review quarterly: read the triggers; re-open / supersede as constraints shift.

ADR lifecycle.

Decision moment
Write ADR
PR review
Use in reviews
Trigger/revisit
Hands-on

Examples

Minimal ADR

Minimal ADR
# ADR-014: Use Aurora Serverless for spiky write tier
# Status: Accepted
# Context: checkout peaks 50x off-hour; fixed fleet = idle cost;
#          RDS baseline too high for the average.
# Decision: Aurora Serverless v2 (auto-scale) as write store for peak-driven path.
# Consequences +: zero-idle, elasticity; –: scale ramp latency on cold start-ish,
#          monitoring learning curve.
# Alternatives: fixed cluster (simpler, over-pay), Lambda+nosql (fast but schema 0).
# Trigger: if p50 scale-ramp exceeds 500ms OR bill prediction breaks, re-evaluate.

A decision readable at review time, with an honest cost-side and a trigger — that's an ADR that earns its place.

Real world

In production

  • adr/NNN-title.md in the repo, PR'd + reviewed like code.
  • Quarterly ADR review: triggers read, superseding stale ones.
  • Link ADRs in docs/code comments ('see ADR-014') so the memory travels.
Guidelines

Best practices

  • Keep each ADR under ~100 lines; the template beats the author's essay self.
  • Write ADRs at decision-time with PR; don't backfill after months.
  • Review in PR — challenge is the point; 'approved but challenged' is the culture.
  • Supersede rather than edit: history is the archive, new decisions ride the archive.
  • Add a quarterly ADR-health check (triggers + coverage) to your review calendar.
Watch out

Common mistakes

  • ADRs in a private brain → turnover voids the memory.
  • Bloat-ADR paragraphs that nobody reads → a deed nobody cites is wallpaper.
  • Never-reviewing → decisions fossilize past their constraint shelf-life.
  • Editing old ADRs to 'update the answer' → the archive becomes fiction.
When things break

Debugging tips

  • An old decision bites (store choice painful now) → read the ADR's Consequences + Trigger; it's designed for this moment.
  • Debate recurs on the same topic → the ADR wasn't written/shared; write one and end the replay.
  • A decision made without PR review got regretted → the review gate was skipped; enforce review on anything in adr/.
  • ADR directory full of corpses → quarterly trigger read; supersede with the current constraint set.
Interviews

Interview checkpoint

Test yourself

Quick quiz

0/2
1

The ADR section that keeps decisions from fossilizing:

2

The discipline that makes the archive trustworthy:

Go deeper

Official documentation

adr.github.io
docs
Michael Nygard format
docs
Azure ADR guidance
docs