ADRs & Design Reviews

⏱ ~9 min read · 🎧 8 min listen · ✎ 3 quizzes · 🧪 ~45 min lab

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.

The ADR: a decision in one page

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.¹ That post became the canonical format, and an entire ecosystem of templates and tooling grew around it.² Nygard's format has just four working parts:

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.¹ 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."

What makes an ADR good

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.³

Design reviews that actually work

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.⁴ Most design reviews fail the same four ways — and each failure has a precise fix:

🧪 Lab: write a real ADR

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:

1. Pick the decision — one with real stakes and at least one credible alternative that someone actually argued for.
2. Write the context cold — as if the reader joined the company yesterday: the forces, the constraints, why a decision was needed at all.
3. State the decision in active voice ("We will…"), then write the alternatives — each with its genuine strengths, not a strawman.
4. Write honest consequences — positive, negative, and neutral. If you can't find a negative, you haven't finished thinking.
5. Run the checklist in the template, then — if the decision is current — circulate it to one teammate who preferred a different option and ask: "is your side fairly represented?"

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."

You are a seasoned Principal Engineer reviewing my work: an Architecture Decision Record (ADR) in Nygard's format. Grade it against this rubric:

- Honest consequences: the consequences section names at least one genuine downside of the chosen option, alongside positives and neutrals.
- Fair alternatives: each rejected option is written at its strongest — an advocate of it would say "yes, that's a fair account of why we didn't."
- Cold-readable context: a new hire could understand the forces and constraints with no tribal knowledge.
- A real decision: stated in active voice ("We will…"), not hedged into a discussion.

Grade each criterion Strong / Adequate / Missing with one sentence of evidence from my ADR. Be skeptical — challenge the weakest claim first. Then ask me 2–3 follow-up questions a design-review panel would ask. Finish with the single highest-leverage improvement.

My ADR follows below.

Check yourself — review the reviewers

Three scenarios. Diagnose from the mental model — honest records, questioning reviews. Wrong picks stay live.