Lesson 05 · Architecture & System Design
Your output is decisions — here's how to write one down in a page, and how to review one without wrecking the room.
Back in Lesson 01 we landed on the sentence that defines this level: your output becomes decisions, documents, and direction. Here's the problem — a decision that lives in a meeting, a Slack thread, or one engineer's head evaporates. Six months later nobody remembers why, the debate reopens, and the org pays for the same decision twice. This lesson gives you the two tools that stop the leak: the Architecture Decision Record, which makes a decision durable, and the design review, which makes it good before it's durable.
In 2011, Michael Nygard proposed something almost embarrassingly simple: for each architecturally significant decision, write a short text file — one or two pages, numbered, stored in the repo next to the code it governs.1 That post became the canonical format, and an entire ecosystem of templates and tooling grew around it.2 Nygard's format has just four working parts:
| Section | What it answers | The trap to avoid |
|---|---|---|
| Context | What forces are at play — technical, political, project-local. Why is a decision needed now? | Assuming tribal knowledge a new hire won't have |
| Decision | "We will…" — the response to those forces, in active voice, full sentences | Hedging. An ADR records a decision, not a discussion |
| Status | Proposed → accepted → later, possibly deprecated or superseded by a newer ADR | Editing old ADRs. Supersede them; never rewrite history |
| Consequences | The resulting context — all of it: positive, negative, and neutral | Listing only the upsides (more on this below) |
Why bother writing it down? Three payoffs, and each one maps to your mission. Onboarding: a new engineer reads the decision log and absorbs in an afternoon what took the team years of arguments — Nygard's original motivation.1 Un-relitigating: when someone asks "why don't we just use X?", the answer is a link, not a week-long debate that ends where it started. Promotion evidence: an ADR has your name on it, a date, and a decision that shaped the system — it's the most legible artifact in your evidence trail, and interviewers at Principal loops increasingly ask "walk me through a decision you documented."
A bad ADR is a press release: three benefits, zero costs, alternatives dismissed in a sentence. A good ADR is an honest trade-off record — Lesson 02 in miniature. Two tests separate them. First, the consequences section names at least one genuine downside of the chosen option — because after Lesson 02 you know there is always one; a consequences list with no negatives means the author stopped thinking or started selling. Second, the alternatives section would satisfy an advocate of the rejected option: each alternative is written with its real strengths, so the person who argued for it reads the ADR and says "yes, that's a fair account of why we didn't." Software Architecture: The Hard Parts models this discipline at book length — every significant decision in it lands as an ADR with trade-offs attached.3
An ADR records the decision; a design review is where the decision gets stress-tested — and it's where Principals are most visible, for better or worse. Google runs on this loop: design docs circulated and reviewed before code, with the explicit goal of surfacing trade-offs early, when changing course is still cheap.4 Most design reviews fail the same four ways — and each failure has a precise fix:
| The failure | The fix |
|---|---|
| Everyone reads the doc live, in the meeting | Circulate it days before. The meeting is for discussion, not first contact — written proposals gather better feedback asynchronously5 |
| Debate jumps straight to the solution | Review the problem first. Ask "is this the right problem, correctly framed?" before touching the design — a beautiful solution to the wrong problem is worthless |
| Reviewers issue verdicts ("you should have used Kafka") | Ask questions instead. "What happens when the queue backs up?" teaches, keeps authors owning their design, and might reveal you're missing context |
| Review becomes a rubber stamp | Adopt the reviewer stance: "what would have to be true for this to fail?" — hunt for the load-bearing assumptions, then ask about those |
Not a toy — a real ADR, for a decision your team made in the last few months (or is making right now): a library choice, a service boundary, a datastore, a build-vs-buy call. Open the template and:
Feedback loop: bring the ADR back to me in chat. I'll review it against a Principal-level rubric — does the consequences section name at least one genuine downside of the chosen option, would a rejected-option advocate feel fairly represented by the alternatives, and could a new hire understand the context cold. This artifact goes straight into your evidence trail; Lesson 12 will slot it into the promotion packet, and it's a ready-made answer to the interview question "tell me about a significant technical decision."
Three scenarios. Diagnose from the mental model — honest records, questioning reviews. Wrong picks stay live.
Scenario A
A teammate drafts an ADR adopting a new message queue. The consequences section lists three benefits and zero costs; the alternatives section dismisses "Postgres as a queue" in one line: "doesn't scale." You're reviewing the ADR. What's the highest-value feedback?
Scenario B
You're the senior reviewer in a design review for splitting a service in two. Ten minutes in, you're fairly sure the proposed split is wrong — it cuts across the hottest data path. The room defers to you. What's the Principal move?
Scenario C
A new hire asks why the team self-hosts Kafka instead of using the cloud provider's managed service. Nobody quite remembers. A week-long debate reopens — and lands on the same conclusion as two years ago. What does this actually reveal?
Hand-picked follow-ups. None are required — the primary source above comes first.