Architecture decisions and ADRs

Architecture is a series of decisions, and most of their value is lost if only the outcome survives. Six months later someone asks "why didn't we use Kafka here?", nobody remembers, and the debate starts again, or worse, the decision is reversed by someone who doesn't know what it protected. An architecture decision record is a short document that keeps the why. This module covers how to make decisions, how to record them, and the antipatterns they prevent.

1. The idea

Which decisions deserve one?

Ones that are expensive to reverse or affect several teams (the architecture end of the spectrum from Start here): a style, a data-ownership rule, a communication pattern, a shared technology. Not every library choice. A useful test: would a new team member six months from now plausibly ask "why is it like this?"

Three decision antipatterns

• Covering your assets: avoiding or postponing decisions for fear of being wrong. Teams wait, or decide without you.
• Groundhog Day: the same decision is discussed again and again because nobody recorded why it was made.
• Email-driven architecture: decisions announced in emails and chat threads that half the people never see, and nobody can find later.

2. How it works

Groundhog Day, and the cure

An ADR's life

Decisions aren't permanent. ADRs aren't edited when things change; they're superseded, so the history stays readable.

3. Try it yourself

Write an ADR and check it

The team must decide how the Orders service stores product prices. Fill in the record by choosing what goes in each section, and see the record and its quality check update.

4. Trade-offs

5. In real projects

Adding ADRs to an existing system. Don't try to document ten years of history. Record new decisions from today, and write ADRs for old decisions only when they come up for debate: the next time someone asks "why do we use X?", the answer becomes ADR-001.

Architecture stories and narratives. Alongside user stories, some teams write architecture stories ("as an architect, I need the order data split from payments so that payments can be scaled and audited separately") to get architecture work onto the backlog with its business reason.

Avoid analysis paralysis. If a decision is reversible (Module 06), time-box it and record it as "revisit after the load test". An ADR doesn't have to be the final word to be valuable.

Review boards that don't become the bottleneck

Many organisations put a formal architecture review board (ARB) between a design and its delivery. The classic version fails in predictable ways:

• It reviews too late. Designs arrive when the team has already built half of it, so the only possible verdicts are "approve" or "start again".
• It meets too rarely. A monthly board with a two-month queue is slower than most delivery cycles, so teams route around it or present designs that are already shipped.
• Reviewers lack context. Five senior people read a document for twenty minutes and decide something the team spent three months understanding.
• It owns decisions it doesn't live with. The board approves; the team carries the pager. Accountability and authority split.

The lightweight alternative keeps the decision with the team and makes advice the obligation. Andrew Harmel-Law calls it the advice process: anyone can make an architecture decision, but first they must consult everyone meaningfully affected by it and people with expertise in the area. Four supporting elements make it work at scale: decision records (this module), a weekly, open architecture advisory forum where proposals are discussed, team-sourced architecture principles, and a technology radar of what's adopted, trialled or on hold.

Governance then lives in three cheap places instead of one expensive meeting: principles that teams apply on their own, fitness functions that check the rules automatically (Module 26), and a forum for the few decisions that genuinely need many eyes. A review checklist for the forum is on the Templates page.

Dissent and consensus

Disagreement about a significant decision is healthy; unresolved or hidden disagreement is not. Habits that turn it into better decisions:

• Name one decider. Consensus is a goal, not a requirement. Everyone knows who decides and by when, so a single holdout can't stall the decision indefinitely.
• Argue against the strongest version. Restate the other option at its best before criticising it; if its supporters agree with your summary, the debate is about the real trade-off.
• Agree what evidence would decide it. "If the load test shows p99 under 200 ms on Postgres, we don't need DynamoDB." A spike or a prototype ends many arguments that meetings can't.
• Record the dissent. The ADR names the objection, who raised it and why it was overruled. People commit more easily when their view is on record, and the next reviewer sees the risk that was accepted.
• Disagree and commit, with a review date. Once decided, everyone supports the decision; the ADR says when or on what signal it will be revisited.

Say it in the interview

6. Remember it

7. Common mistakes

8. Design exercise (30 minutes)

1. Find a Groundhog Day (5 min). Which decision does your team keep re-discussing?
2. Write its ADR (20 min). Use the seven sections. Include at least two options considered and at least one negative consequence.
3. Add compliance (5 min). Write how you'd know if the decision stopped being followed.

9. Self-check quiz

10. Go deeper