Every design in this stage ends the same way: someone has to agree to it, someone has to build it, and someone, months or years later, has to understand why it is the way it is. That is what design documents, architecture decision records, and design reviews are for. Done well they make decisions faster, not slower: arguments happen in writing where everyone can see them, reviewers comment on their own time, and the reason behind a choice survives the people who made it. This lesson follows one decision, adding a status cache to the tracking service, from problem statement to production and its six-month review, measured in days. By the end you can write a design doc that gets a clear yes or no, record decisions so they outlive you, and run a review that improves a design instead of just approving it.
Difficulty: Master · Know this first: Lesson 170, Lesson 163, Lesson 49
This bar is calendar days from problem to production, plus the first time someone asks why. It is a worked example, not a measurement. Writing things down costs a few days at the start; not writing them down shows up as weeks of meetings, rework, and rediscovery later.
Move the sliders. Meeting-driven reviews wait for calendars; written reviews wait for comments. The review hop above follows the written version with your numbers.
meeting-driven days = rounds × days per slot · written-review days = rounds × 1.5 days (comments within a working day and a half)
meeting person-hours = rounds × reviewers × 1 h · written-review person-hours = reviewers × 1.5 h, plus one 30-minute decision meeting.
A written review decides 11 days sooner
Three questions. No score is saved anywhere — this is just you against the material.
Writing designs down grows in four levels: first a clear doc for one decision, then decision records and trade-off tables, then reviews that improve designs, and finally a decision culture that works across an organisation.
At the basic level you write a short design doc for one decision: the problem with numbers, goals and non-goals, the proposal with a diagram, and the questions still open. You write for a reader who knows the system a little and has twenty minutes. The doc is good when a reviewer can say a clear yes, no, or "yes if".
Types:
Uses: any change that touches more than one team, costs real money, or will be hard to undo.
Where it breaks: a doc that starts with the solution. Reviewers spend their time questioning the problem through the proposal, and the review drags.
Try it: Basic
What should a design doc start with?
Now do it: Rewrite the first paragraph of your last design doc as a problem statement with one number in it.
At the intermediate level the doc shows the choice, not just the answer. Three or more options, including doing nothing, scored in a table on the same criteria. The chosen option's consequences, good and bad, are stated plainly. And each significant decision becomes an architecture decision record: a one-page file in the repository that is never edited, only superseded.
Types:
Uses: every decision someone will later ask "why?" about: datastore choices, caches, protocols, boundaries.
Scale and failure: ADRs scale because they are small and append-only; design docs drift because they are long and edited. Keep the doc for the discussion and the ADR for the verdict. The failure at this level is an ADR written months later from memory, without the numbers that justified it.
Try it: Intermediate
A team wants to change a decision recorded in ADR 0017. What do they do with the ADR?
Now do it: Write an ADR for one decision in your system that people keep asking about. Include what would make it wrong.
At the advanced level you run reviews. Reviewers are chosen by the design's risks, not by seniority. Review happens asynchronously first, with a checklist covering reliability, security, privacy, data, cost, and operability. One short meeting resolves what writing could not, and a named decider decides, with dissent recorded.
Types:
Uses: designs with cross-team impact, risk, or cost.
Scale and failure: meeting-driven reviews scale with calendars: five reviewers and weekly slots turn two rounds into two weeks. Written reviews scale with attention: the same two rounds take about three days. The failure is a review nobody read closely, so nothing changed, which a reviewer's checklist and named concerns help prevent.
Try it: Advanced
A design caches customer data. Who must be on the review, whatever the doc's size?
Now do it: Use the review simulator above with your team's numbers, then write a five-line review checklist from your last three incidents.
At the master level the practice scales beyond one team. Designs and ADRs are searchable in one place. Significant cross-team decisions go through a lightweight RFC process with a clear threshold. Decisions carry revisit triggers, and the organisation actually revisits them. Writing is the default way architecture happens, and senior engineers influence through reviews and written guidance rather than approval gates.
Types:
Uses: engineering organisations past a few teams, where nobody can know every decision.
Trade-off: process is a tax on every change. The master-level skill is setting thresholds so that the decisions that matter get written review and the rest move fast, and pruning any step that has stopped catching problems.
Try it: Master
An RFC process has become a two-month approval queue, and teams route around it. What does a master-level fix look like?
Now do it: List the last ten decisions your team made. Mark which needed written review and which a paved road could have answered.
An ADR is short enough to read in two minutes and specific enough to be useful in two years. This is the record for the decision in this lesson.
# ADR 0017: Read-through cache for parcel status
Status: accepted (2026-03-11); decider: tracking tech lead; consulted: platform architect
Context: Status reads reach 5,800/s at the holiday peak (plan: docs/brief-tracking-v1.md).
Replicas saturate near 3,000/s; Dec 2025 p99 reached 2.1 s for 4 hours.
Freshness requirement: a scan visible within 60 s.
Decision: Read-through cache in front of replicas, 30 s TTL, delete on write.
Cache parcel status only; never addresses or names (security review, 2026-03-08).
Consequences:
+ replica load at peak ~1,000/s; p99 well under 300 ms
- one more component to run; statuses up to 30 s stale (inside the 60 s budget)
Alternatives rejected:
more replicas - cost x2 at peak, still saturates at next year's growth
CDN status pages - personal data at the edge; invalidation per parcel too slow
do nothing - repeats Dec 2025
Revisit if: peak reads < 1,000/s, or freshness requirement drops below 30 s.
Dissent: data engineering preferred the CDN option for cost; committed.
Results: 2026-04-02 replica CPU 34% at peak, p99 120 ms, hit ratio 86%.Context with numbers, the decision, both kinds of consequences, the rejected paths, what would change the decision, the dissent, and the verified result. Nothing else.
Decision records rot quietly: a status left "proposed" forever, a superseded record with no pointer forward, a record with no "revisit if". This script checks a set of records for those three things.
# python3 adr_lint.py
adrs = {
"0012": {"status": "superseded by 0017", "revisit": "if reads < 500/s"},
"0015": {"status": "proposed", "revisit": ""},
"0017": {"status": "accepted", "revisit": "if peak reads < 1,000/s"},
"0019": {"status": "superseded", "revisit": "if a second region launches"},
}
for n, a in sorted(adrs.items()):
problems = []
if a["status"] == "proposed":
problems.append("still proposed: decide it or withdraw it")
if a["status"].startswith("superseded") and " by " not in a["status"]:
problems.append("superseded, but by what?")
if not a["revisit"]:
problems.append("no 'revisit if' line")
print(n, "OK" if not problems else "; ".join(problems))
Expected: 0012 OK; 0015 still proposed and missing a revisit line; 0017 OK; 0019 superseded with no pointer. In a real repository, parse the Status and Revisit lines from the markdown files under docs/adr.
A tracking platform I joined had a read cache that a previous team had added after a bad holiday season. Nobody on the current team had been there. The cache had no decision record, only a two-line commit message: "add cache for perf".
The team wrote ADRs for the twelve components whose reasons were least obvious, with "revisit if" lines, and made an ADR part of the definition of done for any change that adds a component. The cleanup project's checklist gained one question before removing anything: what was the context when this was added, and has it changed?
Your team wants to move the tracking service's scan history from PostgreSQL to a wide-column database. Write the outline of the design doc and the ADR, and say who should review it and why.
What problem does the move solve, with numbers: storage growth, write rate, cost? What does doing nothing cost over the next two years? What breaks during the migration, and how long does dual-writing last? Which teams read scan history today, and through what?
Say 480 million new rows a month and 1.4 billion online; storage growing 40 percent a year; write peaks of 30,000 a second during the holiday surge. The doc needs these to make the case, and the ADR needs them to stay meaningful.
Doc: problem with growth and cost curves; goals and non-goals (no change to the read API); options (partition and tune PostgreSQL, wide-column store, object storage for cold history, do nothing) in a trade-off table; migration plan by expand and contract; reliability and cost sections; open questions. Reviewers: data platform, SRE, the two consuming teams, finance for cost. ADR with context, decision, consequences, rejected options, revisit triggers.
A new datastore buys write scale and costs a second system to run, new skills, and loss of joins and transactions. Tuning PostgreSQL with partitions and cold storage may buy two years for a fraction of the effort. The doc's job is to make that comparison honest, and the ADR's job is to remember it.