Watch
Lesson 55 - Architecture Decision Records
A ten-minute walkthrough of the ADR sections (context, decision, consequences, status) and why the justification is the part later readers need most.
Design Documents and Decision Records
Mistakes to catch in review
A public API field named and shipped during a small bug fix, making the name permanent for every client.
An agent-written design document that lists options with pros for each but never states what was chosen or what was given up.
A deliberate earlier choice, such as avoiding a message queue, undone by an agent because nobody recorded why it was made.
Writing down the options, the decision and what it costs, so the reasoning outlives the conversation and later readers can follow it.
Topics
- Writing Design Documents
- A short document covering context, goals, options considered, the choice and its risks, written before the expensive work starts.
- Architecture Decision Records
- Small, dated records of individual decisions kept next to the code, so later readers know why things are the way they are.
- Reversible and One-Way Decisions
- Moving fast on choices that are cheap to undo and slowing down on the few that are expensive to reverse.
- Tradeoff Analysis
- Making the cost of every option explicit (complexity, speed, money, risk) alongside its benefits.
- Estimating Work Under Uncertainty
- Giving ranges instead of single numbers, and tackling the riskiest unknown first.
You understand it when you can
- Write a one-page design document with context, options, the decision and its consequences.
- Classify the decisions in a project as reversible or one-way, and explain how that changes how carefully each is made.
- Read an existing design document and name the assumption most likely to be wrong.
Drill
An agent wrote a design document for a billing system that compares three databases and ends with 'any of these would work well'. Find what the document never decides, which part of the choice is a one-way door, and what a reader six months from now would be unable to learn from it.
Start here
Watch
Software Architecture: The Hard Parts • Neal Ford & Mark Richards • GOTO 2023
The authors argue that every architecture choice is a tradeoff to be made explicit, and discuss how to analyze and record those tradeoffs instead of looking for a best answer.
Facilitating Software Architecture • Andrew Harmel-Law & Sonya Natanzon • GOTO 2024
Covers the advice process and decision records as the way teams make and document decisions, including recording the options considered and what was given up.
Read
Facilitating Software Architecture: Empowering Teams to Make Architectural Decisions
Detailed guidance on writing ADRs, taking advice from affected parties and keeping a decision log that later readers, human or agent, can follow.
Fundamentals of Software Architecture: A Modern Engineering Approach
Its chapters on architecture decisions and characteristics teach how to justify a choice against named quality attributes and document it.
Software Estimation: Demystifying the Black Art
The standard text on the cone of uncertainty, estimating in ranges and separating estimates from targets and commitments.
Primary sources
Reference
Documenting Architecture Decisions (Michael Nygard, 2011)
The original ADR proposal: short numbered records with context, decision, status and consequences, kept in the repository so later changes do not undo choices blindly.
Reference
Design Docs at Google (Malte Ubl)
Describes the sections of a real design doc, including goals and non-goals and alternatives considered, and when a design doc is and is not worth writing.