Platform Engineering · Lesson 171

Design Docs, ADRs, and Design Reviews: Writing the Decision Down

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

Run it as:

When it breaks, I check

One thing to remember

Where the time goes

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.

Try it: meetings versus a written review

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.

14days, meeting-driven
3days, written review
10person-hours in meetings
10person-hours, written

A written review decides 11 days sooner

Check yourself

Three questions. No score is saved anywhere — this is just you against the material.

Basic to master

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.

Basic — A design doc a reviewer can say yes or no to

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:

  • Problem statement: what is wrong, the evidence, and why now.
  • Goals and non-goals: what this design will and will not do.
  • Proposal: the design, with one diagram and the key flows.
  • Open questions: what is not yet decided, stated honestly.

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.

Intermediate — Alternatives, trade-offs, and ADRs

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:

  • Trade-off table: options as rows, criteria such as latency, cost, risk, and effort as columns.
  • ADR sections: title, status, context, decision, consequences, alternatives.
  • ADR lifecycle: proposed, accepted, deprecated, superseded by another number.
  • C4 diagrams: context and container level for the doc, component level only where it helps.

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.

Advanced — Reviews that improve the design

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:

  • Risk-based reviewer selection: security for personal data, SRE for new critical paths, finance for large cost.
  • Review checklists: the questions this organisation has learned to ask, one line each.
  • Decision roles: a decider, people consulted, people informed, named at the top of the doc.
  • Disagree and commit: dissent written into the record, then full commitment to the decision.

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.

Master — A decision culture across an organisation

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:

  • RFC process: a threshold for what needs one, a template, a timebox, and a decider.
  • Decision log: every ADR across every repository, searchable by topic and status.
  • Revisit triggers: "if peak reads fall below 1,000 a second, remove the cache".
  • Architecture guidance: paved roads and principles that make most decisions unnecessary.

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.

Go deeper

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.

Lint a folder of decision records

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.

One time it broke

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

Timeline

  • JuneA cleanup project lists the cache as "unclear value, adds staleness". Load tests at June traffic show the database coping without it. It is removed.
  • July to OctoberNo problems. Traffic is seasonal; nobody checks the December numbers, because nobody knows they matter.
  • November 28Peak week begins. Replicas saturate at 3,000 reads a second; status reads take seconds; support calls triple.
  • November 29The cache is restored from git history under incident pressure, with a TTL guessed on the spot. It works; the TTL is wrong for another month.

What changed after

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?

If you remember nothing else

Design exercise

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.

Clarifying questions to ask

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?

Rough sizing

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.

Shape of the answer

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.

Trade-offs to name

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.

Saved on this device, in this browser.
Next in this series · Lesson 172
Design a URL Shortener

This is the first lesson where I stop designing one piece and put the whole system together. A URL shortener looks small. A user pastes a long link and gets a short one back. Then someone clicks it.

Go to Lesson 172 →

Or browse the full course from the Lessons index.