A technical design doc template for staff engineers, and when an ADR is enough

The names vary by company. The jobs do not. Three documents carry a technical decision through its life, and most confusion comes from asking one of them to do the work of another.

Many organizations use "design doc" and "RFC" for the same file, and that is fine as long as everyone knows which stage it is in. The ADR is different in kind: it is short, it is written once the call is made, and it outlives the design doc. My book Controlled Change separates them for a reason: an ADR answers "why this choice?", a decision journal tracks uncertainty that is still open, and an architecture map shows the current boundaries. Merging all three into one giant architecture document, the book argues, makes all three harder to maintain.

Which one you need depends on the decision, not on the team's habit. The book classifies decisions by reversibility and blast radius, and the discipline follows the class:

The sentence under that table is the rule I would put on the wall of any team that argues about documentation: "Documenting everything creates paperwork. Documenting nothing creates folklore. The boundary is consequence."

Before the full doc, write one page. Controlled Change lists what goes on it before a long RFC: the current outcome and its evidence, who pays the cost, why now, the constraint that cannot be ignored, two or three plausible options, the decision needed and its date, and the first reversible step.

The page exists to test whether the problem is understood. "Move to a new architecture" is not a problem. A statement with a measured cost, a team that pays it and a date is. If you cannot fill the page, the long doc will be a solution looking for a reason, and reviewers will spend the meeting finding that out for you.

The one-page framing is also what you take into the first conversations with the people who will pay. It is short enough to change, which is the point.

Copy the block below into whatever your team writes docs in. The header is the part most templates skip, and it is the part that decides whether the doc can be approved at all. Section 8 is the part generic templates skip on mobile.

# Design doc: <the decision, phrased as a choice>

Status:             draft | in review | approved | rejected | superseded
Author:
Date:
Decision owner:     <one name: their yes holds, their no is final>
Decision needed by: <date, and what slips if it is missed>
Pays for it:        <teams carrying build, on-call, migration, roadmap>
Executes:           <teams doing the work>
Can reopen:         <who has standing over the question; consulted?>
Reviewers:          <one per boundary or consequence touched>

## 1. The decision and why now
The choice being made, the fact that forces it now, and what
deciding nothing costs.

## 2. Context and evidence
What happens today, with numbers and dates, and who feels it.
Link the incident, dashboard or support data.

## 3. Goals and non-goals
Goals as observable outcomes. Non-goals that keep the review
from expanding.

## 4. Constraints, ranked
The characteristics that decide this (offline, latency, privacy,
build time, release risk), in order. The top one breaks ties.

## 5. Options
A. Keep the current design, and what that costs each quarter.
B.
C.
For each: what it buys, what it costs, what it makes hard later.
Describe each so the people who prefer it would sign it.

## 6. Recommendation
The option, the trade-off accepted on purpose, and why it fits
the ranked constraints better than the others.

## 7. Design
State and data: who creates, changes and owns each piece of truth.
Failure: timeout, duplicate, process death, partial commit,
provider outage, and what the user sees in each.
Diagrams only where they answer a question.

## 8. Clients in the wild
Oldest supported app version, and what it does after this ships.
Compatibility window for the API and the local schema.
Safe defaults when remote config is unreachable.
Whether rollback still works once new data has been written.

## 9. Rollout, migration and deletion
Stages, flags, and the metric that halts each stage.
How old and new paths coexist, and the evidence that deletes
the old one.

## 10. Security, privacy, accessibility, performance
Only what changes. "No change" is an answer if it is true.

## 11. Ownership after approval
Who owns the code, the data, the on-call page, the migration
and each follow-up. Names, not "the team".

## 12. Evidence and revisit triggers
How you will know it worked, and the date you will check.
The facts that would reopen this decision.

## 13. Open questions and dissent
What is unresolved. Who disagrees, and why, in their words.

## Appendix: pre-alignment log
Person | Why their objection counts | Objection | What changed

## Decision record (filled in at approval)
Outcome:      accepted | accepted with follow-ups | experiment |
              revise and return | rejected | deferred
Decided by:                 Date:
Follow-ups:   <action / owner / deadline / how it is verified>
Residual risk owner:
ADR:          <link to the record this doc produced>

If your organization calls this document an RFC and wants a shorter field checklist with review questions and the usual smells, the mobile architecture RFC template on this site is that checklist. This page is the full doc around it: the decision rights, the pre-alignment log, the mobile section and the record that closes it.

Every section earns its place by preventing a specific failure in the review or after it. When a section is weak, it shows in a predictable way.

Two of those rows deserve more than a cell. On the design section, Controlled Change is blunt about diagrams: "A component diagram without data authority or a failure path is decorative." And on length, the book's target is a reader who can "understand the decision in ten minutes and inspect depth when needed." Link the detail; do not inline it.

Its chapter on reviews also has a habit worth stealing for section 7 and 12: label each claim as a fact, an assumption or a decision, and give the assumption its revisit condition. Reviewers can then attack the assumption without attacking the author.

A server design doc can say "roll back if the error rate rises". A mobile doc cannot say that in the same way. You can halt a staged rollout, but the builds already installed stay on devices you do not control, and they keep calling your API until their owners update. That changes what sections 8 and 9 have to say.

The delivery and compatibility part of Controlled Change's review rubric gives the questions. Is the compatibility window drawn for the old, current and next client? Are embedded defaults safe when remote configuration is unreachable? Are flags typed, owned and expiring? Are rollout stages and halt thresholds declared in advance? Do the data changes say whether rollback is still possible? Is there deletion evidence for the bridge and the old path? Its failure walk-through adds two cases a server template never asks about: an old client with an old local schema, and rollback after new data was written.

Put the answers in the doc, not in the reviewer's head. The oldest supported app version, the schema it expects, and what it does on the day the new path ships are the three lines that most often turn an approved mobile design into an incident.

The most common reason a good design doc stalls is not the design. Nobody wrote down who decides. A review meeting then produces what my book Before the Room calls a snapshot of sentiment: people appearing to agree, reopenable by anyone with standing who was not there.

Before the Room breaks a decision into five roles: someone proposes it, someone decides it, someone pays for it in budget, on-call load, roadmap or migration work, someone executes it, and someone can reopen it, because they hold standing over the question even if nobody asked them. The author of the design doc is usually the proposer, not the decider. Writing that down is not a demotion; it tells you where to spend your credibility. Those roles are the header of the template above.

The row people leave blank is the reopener, and it is the one that produces the reversal a week later. The book gives one sentence to say as a review ends, and it works just as well written at the top of the doc before the review starts: "Before we call this closed, who actually owns this decision, and who could reopen it who is not in this room?"

Controlled Change adds the review roles around the doc: the author owns the proposal, a facilitator keeps the review on criteria, domain and platform reviewers bring what they know, a decision owner resolves trade-offs, and a recorder captures outcomes and follow-ups. The invitation rule is the one most review lists break: "Invite people because they own a boundary or a consequence, not because they are senior." And the line that ends most stalled reviews: "Consensus is not a substitute for a decision."

A design review is the hardest place to persuade anyone. People hear the costs live, in front of peers, and the person who could approve looks at a room full of fresh objections and defers. Before the Room's answer is pre-alignment, and it draws the line engineers worry about precisely: "Pre-alignment changes the proposal. Rigging changes the room." The test is whether you could describe the private conversation in the meeting without embarrassment.

In practice, for a design doc:

• Send the draft early, to everyone whose objection could change the decision. In written and RFC-driven organizations, the book notes, pre-alignment happens in pre-reads and comment threads, and fairness means those people get the same early access to the draft, not only the decider's allies.
• Start with the person most likely to change the proposal. Pre-aligning only with people who already agree makes the meeting friendlier but not safer.
• Ask for the objection, not for agreement. The question the book gives is "What fact, risk, or constraint would make this unsafe to approve?" People asked "are you aligned?" tend to say yes.
• Change the doc, or carry the objection in by name. The book's rule is that every objection you hear in private "either changes the proposal or walks into the meeting by name." Section 13 and the pre-alignment log are where that happens on paper.
• Relabel the meeting if the doc is not ready. If several real objections are still open, the honest meeting is a review or a discovery session, not an approval. Ask the decision owner to call it that.

The pre-alignment log in the template is a reduced version of the book's pre-alignment plan, and its most important column is the last one, what changed. A row with an expected objection and nothing in that column means you predicted someone's unhappiness, not that you pre-aligned them. Controlled Change says the same thing from the architecture side: surprising stakeholders with a finished proposal invites political rejection and technical blind spots, so interview the affected teams before circulation, while keeping the decision owner clear.

And sometimes the meeting is unnecessary. If written feedback resolves the trade-offs, Controlled Change says to record the decision and proceed: meetings are for disagreement, ambiguity or collaborative discovery, not for reading the doc aloud.

A design doc is not done when the meeting ends. It is done when the decision record at the bottom is filled in. Controlled Change uses a small outcome vocabulary for that: accepted, accepted with required follow-ups, time-boxed experiment, revise and return, rejected with rationale, and deferred because the pressure is not yet real. The point of a fixed list is that "looks good, let us keep talking" is not on it.

Two more fields make the outcome hold. The first is the dissent and who owns the residual risk. The book's rule: "Consensus is not required; ambiguity is unacceptable." The second is the revisit triggers, and this is where most docs fall back to a calendar. The book is direct about that: "Time alone is a weak trigger." A trigger should observe an assumption: build time over its agreed budget for four weeks, three teams needing the same domain capability, the share of unsupported clients falling below a threshold, an incident that shows the current authority policy is ambiguous.

Before the Room calls the same field reopen criteria, and names the failure mode: criteria so vague that any new opinion qualifies. Its correction: "Name evidence, not discomfort." Written before the disagreement, reopen criteria give the person who still thinks you are wrong a legitimate path: bring evidence that meets them and the decision reopens on its merits. What they lose is the option to relitigate in pull requests. The book also names the opposite failure: set the bar so high that real evidence never clears it, and the record stops protecting the decision and starts freezing a mistake.

Finally, the doc produces an ADR, and the ADR is what lives next to the code. When a trigger fires, Controlled Change's rule is that "A new ADR should supersede the old one rather than rewrite history." The chain of records is how the next engineer learns why the system looks the way it does.

Not every decision deserves thirteen sections and a pre-alignment log. Controlled Change's chapter on influence and RFCs has a short section on when not to write one, and its first line is the advice to follow: "Use a small ADR or team decision for local, reversible choices." Heavy documents impose cost; match the artifact to the blast radius and the uncertainty.

The book's review rubric turns that into entry criteria. A full design doc and formal review are warranted when the decision touches one of these:

• a new cross-team or public contract, or a module many others depend on;
• data authority, retention or a durable schema;
• offline mutation, synchronization or conflict policy;
• a security or privacy boundary, or a sensitive third-party SDK;
• an irreversible provider, framework or cross-platform commitment;
• a high-impact financial, legal, safety or agentic action;
• a release or minimum-version strategy that affects old clients;
• a multi-quarter migration or a broad build or platform change;
• reliability or performance risk above an established budget.

If none apply, the rubric says to use a local decision or a short ADR. The smallest ADR that still works, from Before the Room's template, is three things: the decision, the option rejected, and one line naming the evidence that would reopen it. Below that line there is a further one: for a reversible decision that costs less to redo than to record, code review is the record.

One warning from Controlled Change's chapter on ADRs. An old ADR written for a large feature, copied into every new feature without checking its assumptions, is what the book calls architecture by precedent. A short ADR is enough only when it is about this decision.

From the hiring side, "tell me about a design you drove" is rarely scored on the design. Most candidates at this level can describe a sensible architecture. The answers that read as staff carry the parts of this template that are not about code: who owned the decision and how they knew, the objection that changed the doc before the review, the option they rejected and why, the revisit trigger, and whether it fired. The answers that read as senior stop at the diagram.

Before the Room uses one lens for that difference: a senior engineer solves the problem, a staff engineer changes the decision around the problem. A design doc is where the second half becomes visible, and it is also durable evidence for a promotion case; the article on what to keep for a staff promotion packet covers how to save it while the work is alive. For the persuasion that happens around the doc, see influence without authority.

If you are on the other side of the table, reading someone else's doc, how to review a mobile architecture proposal is the reviewer's version of this page: name the decision, find the constraint doing the work, and raise the standard with irreversibility.

The short version fits on a card. Pick the document by consequence. Put the decision owner and the reopener in the header. Send the draft to the likeliest dissenter first. Close with an outcome, a risk owner and triggers that name evidence. Then let the ADR do the remembering.

What is the difference between a design doc, an RFC and an ADR?

They do different jobs at different moments. A design doc explores a problem and proposes a decision before it is made. An RFC is that proposal circulated for objections; many companies use the two names for the same document. An ADR records the decision after it is made: the options rejected, the consequences accepted and the facts that would reopen it. A good design doc ends by producing an ADR.

How long should a technical design doc be?

Long enough that a reader understands the decision in about ten minutes and can open the depth when they need it. Controlled Change puts a useful review packet at two to six pages. Push the detail into linked appendices and keep the main path to the decision, the options, the recommendation and what it costs.

Who should approve a design doc?

One named decision owner, whose yes holds and whose no is final. Reviewers are invited because they own a boundary or a consequence the decision touches, not because they are senior. Consensus is not the bar: record dissent and the owner of the residual risk, then decide.

When is an ADR enough instead of a full design doc?

When the decision is local or cross-feature, reversible at a cost the team can carry, and does not touch a cross-team contract, data authority, a privacy boundary, old clients, an irreversible vendor commitment or a multi-quarter migration. Then a short ADR with an owner, the rejected option and one revisit trigger does the job. If the decision costs less to redo than to record, code review is enough.

What makes a staff engineer's design doc different from a senior engineer's?

The senior doc solves the problem well. The staff doc also changes the decision around the problem: it names who decides, who pays and who can reopen, it was shaped by the people whose objections would have killed it, and it says in advance which facts would justify changing course. The difference shows less in the design section than in the header and the last three sections.