AR3: Decisions and risks: ADRs, weighted scoring, risk registers and fitness functions
Architecture decision records
🎯You'll be able to
Write an architecture decision record (ADR) with its status, context, options, decision and consequences, and keep an index of them.
🏠The everyday picture
A family keeps a note of why they chose the school they did: the fees, the distance, the teachers. Years later, when a younger child starts, the note saves them from repeating the whole search, or shows what has changed since.
📘What it really is
-
An ADR is a short document recording one decision. Michael Nygard's widely used format has a title, status, context, decision and consequences; many teams add decision drivers, options and risks.
-
Status: Proposed, Accepted, Deprecated or Superseded by a later record. Accepted records aren't edited; a new record replaces them.
- Context explains the situation with evidence, so a reader can see why the decision was needed then.
- Consequences list what becomes easier and what becomes harder. Every real decision has both.
- Numbered files in the repository (
docs/adr/0001-...md) with an index, so decisions live beside the code they shape.
📝A worked example
Input: the RasoiRoute starter's draft, "Everyone is moving to microservices… This will make everything faster and more reliable."
Steps:
- No status or date: add "Proposed, 2026-10-01".
- No context: add the figures from
data/(14 engineers, 1.5 deploys a week, 42.3% of incidents in notifications). - One option only: add the alternatives (AR2 Lesson 5).
- Only benefits: add Negative consequences, such as more to run and new failure modes.
Expected output: a draft that a colleague could disagree with on specific points, rather than a slogan.
🌍Where it's used
- Government and banking teams publish ADRs internally so auditors can see why systems were built a certain way.
- Open-source projects keep ADRs in the repository so new contributors understand past choices.
- Product companies link ADRs from pull requests that implement them.
📝Case scenario
A payments team chose to store amounts as whole paise rather than decimals, after a rounding bug. Three years later a new engineer proposed decimals "for readability". The ADR explained the bug and the choice in half a page, and the discussion took ten minutes instead of repeating the mistake.
🖱️Try it
Write a one-page ADR for a decision you've made in any project (a framework, a hosting choice). Include at least one negative consequence. Success: a reader who wasn't there understands why.
⚠️Common mistakes
- Writing ADRs after the fact, from memory. Sign: no figures, vague context. Fix: write it while deciding, with the evidence.
- Editing accepted records. Sign: history quietly rewritten. Fix: supersede with a new record.
- Only good news. Sign: no Negative consequences. Fix: name the costs; they're what future readers most need.
🛠️For your project
Project 1's tests 1 and 8 check the ADR's sections, status and date, and the index in docs/adr/README.md.
✅Quick check
What happens to an accepted ADR when the decision changes?
Show the answer
It isn't edited; a new ADR supersedes it, and its status says "Superseded by" the new one.
Why include negative consequences?
Show the answer
Every decision costs something, and future readers need to know what was accepted knowingly.