RFCs & Design Docs

At the senior IC level, your output stops being code. The leverage moves to the documents that decide what gets built, by whom, and why. A design doc is the primary artifact of a Staff+ engineer the way a PR is the primary artifact of a mid-level one.

This is not bureaucracy. A doc scales to readers you will never meet — the engineer who joins next quarter, the team two floors away who depends on your interface, the version of you debugging this in eighteen months. A meeting reaches the people in the room once. A doc reaches everyone, repeatedly, asynchronously.

Why Writing Is the Superpower

Three things a document does that nothing else does:

• It scales past the room. Alignment built in a meeting decays the moment people leave. Alignment written down survives the meeting, the quarter, and the reorg. You can point at it.
• It forces your thinking to be precise. You cannot write a vague design. The act of writing surfaces the decision you were hand-waving past, the edge case you hadn't considered, the "obvious" trade-off that isn't. Most design bugs are caught by the author, mid-sentence.
• It creates durable, reviewable alignment. A doc can be commented on, disagreed with, amended, and approved by people in three time zones who never share a calendar slot. That is how an IC leads at scale — not by being in every conversation, but by writing the thing every conversation refers back to.

Writing is how an individual contributor leads without managing. If you want influence beyond your keyboard, get good at this. See influence without authority.

When to Write One

A design doc has a cost — yours to write, your reviewers' to read. Spend it where the decision is expensive. Write one when:

• The change crosses team boundaries. Anything another team has to integrate with, depend on, or change their plans around.
• The decision is irreversible or expensive to undo. A data model, a public API, a storage choice, a wire format. One-way doors get docs.
• The problem is novel. No established pattern in the codebase, no obvious right answer, genuine alternatives in play.
• Multiple people need to agree before work starts. If three engineers will build against this, align first, not after.

And do not write one when:

• The decision is local, reversible, and obvious. A new CRUD endpoint that follows the existing six does not need a design doc — it needs a PR.
• You already know the answer and nobody disagrees. Writing to perform diligence is theater.
• The doc would take longer than the spike that would answer the question. Sometimes the right design doc is a prototype.

The threshold question: if I get this wrong, how hard is it to fix? High cost of being wrong, or high cost of disagreement discovered late — write the doc.

RFC vs Design Doc vs ADR vs PRD

These get used interchangeably and shouldn't be. They answer different questions and live at different stages.

• PRD comes from product: the problem, the users, the success metrics. It is the what and why, not the how. Your design doc should reference it, not restate it.
• RFC is a proposal seeking feedback before building. The emphasis is on the request for comment — you are genuinely asking, not announcing. RFCs can be rejected. That is the point.
• Design Doc is how we'll build it once the direction is agreed. More implementation detail, less "should we." In practice many orgs fold the RFC and design doc into one document that evolves from "proposal" to "plan."
• ADR is the recorded decision plus its context — short, immutable, append-only. It captures why a choice was made so the next person doesn't relitigate it. The design doc explores; the ADR records. See ADRs.

Rule of thumb: RFC and design doc are forward-looking and negotiable. The ADR is backward-looking and final. When the dust settles, distill the design doc's decision into an ADR.

Anatomy of a Good Design Doc

Sections, in order, and what each is for:

• Title & metadata. Title, author, reviewers, status (draft / in review / approved / superseded), date, links to PRD and related docs. Status is load-bearing — a reader must know in five seconds whether this is a proposal or a record.
• Context & problem. What is true today, and what is broken or missing. Written for someone two teams away with no background. If a reader can't understand the problem, they can't evaluate the solution.
• Goals. What this design must achieve, specifically and ideally measurably. "Reduce p99 checkout latency below 200ms," not "make it faster."
• Non-goals. Explicit. This is the most-skipped and most-valuable section. Stating what you are not solving prevents scope creep, preempts half the review comments, and shows you've thought about the boundary.
• Proposed design. The how. Diagrams, data models, interfaces, sequence of operations. Enough detail that someone could build it; not so much that it's the code.
• Alternatives considered. Each real option you weighed, and — critically — why not. A design doc with no alternatives looks unconsidered. Alternatives with no "why-not" looks like you're hiding the comparison.
• Trade-offs & risks. What this design is bad at. Every design is bad at something; name it before a reviewer does. What could go wrong, and how likely.
• Security, privacy & cost. New data collected? New attack surface? New trust boundary? What does this cost to run at scale? Often skipped, often where the real objections live.
• Rollout & migration plan. How it ships — flags, phases, backfills, the path for existing data and clients. A design that can't be rolled out safely isn't done.
• Open questions. What you don't know yet, stated honestly. This invites the review to do real work instead of rubber-stamping.

A skeleton to start from:

# [Title]

| | |
|---|---|
| **Author** | you |
| **Reviewers** | names |
| **Status** | Draft / In Review / Approved / Superseded |
| **Last updated** | YYYY-MM-DD |
| **Related** | PRD link, prior docs, tracking issue |

## Context & Problem
What's true today. What's broken. Why now.

## Goals
- Specific, measurable where possible.

## Non-Goals
- Explicitly out of scope.

## Proposed Design
The how. Diagrams, data models, interfaces, flows.

## Alternatives Considered
### Option A — <name>
Summary. **Why not:** ...
### Option B — <name>
Summary. **Why not:** ...

## Trade-offs & Risks
What this is bad at. What could go wrong. Likelihood and mitigation.

## Security / Privacy / Cost
New data, new surface, new trust boundaries, cost at scale.

## Rollout & Migration
Flags, phases, backfills, the path for existing data and clients.

## Open Questions
- The things you don't know yet.

Writing for the Reader

The doc is for the reader, not the author. Optimize for their time, not yours.

• BLUF — bottom line up front. Lead with the decision and the why. The recommendation goes in the first paragraph, not the conclusion. A busy reviewer should be able to read the top and the headers and know what you're asking.
• Make it skimmable. Headers, bullets, tables, a diagram. Walls of prose get skimmed badly; structure gets skimmed well.
• Write for someone two teams away. Define the acronyms. State the context they don't have. If only your own team can read it, you've written a meeting agenda, not a design doc.
• Recommend. A doc that lists options and won't pick one pushes the decision onto the reader. Have a position. You can be wrong and corrected — that's better than abdicating.

Running the Review

The goal of a review is signal, not approval. A doc that sails through with three thumbs-up and no comments was probably not read, or not contentious enough to need a doc.

• Pre-reads, always. Send the doc ahead. Never present a design cold in a meeting — you'll spend the meeting reading aloud instead of deciding.
• Async first, meeting if needed. Let reviewers comment async on their own time; that surfaces the careful objections. Hold a meeting only for the disagreements async couldn't resolve — and timebox it to those.
• Timebox the whole thing. Reviews left open forever rot. "Comments by Thursday, decisions Friday" beats an indefinite open doc.
• Capture decisions back into the doc. A resolution that lives only in a comment thread is lost. When a thread concludes, fold the outcome into the body. The doc should read correctly without the comments.
• Comment-resolution discipline. Every thread ends in resolved, won't-fix, or follow-up — never just trails off. The author drives this. An unresolved thread is an unmade decision.

For the harder cases — getting a doc approved across teams that don't report to you — this overlaps heavily with technical decisions.

Common Failure Modes

• The doc written after the code merged. A "design doc" that documents what already shipped is not a design doc; it's a changelog with extra steps. The point is to think before building.
• The 40-page doc nobody reads. Length is not rigor. If it doesn't fit in a reviewer's attention budget, it won't get reviewed — it'll get skimmed and approved, which is worse than not writing it.
• No non-goals. A doc with unbounded scope invites unbounded review. Without stated non-goals, every reviewer adds their pet concern.
• Options without a recommendation. Listing three approaches and refusing to pick one isn't neutrality; it's pushing your job onto the reader.
• Design-by-committee. Trying to satisfy every comment produces an incoherent design with no spine. The author owns the design. Listen to everyone; decide yourself. Consensus is not the goal — a sound, owned decision is.

Self-Check

Before you hit send:

If a thoughtful engineer two teams away read only the title, the goals, the non-goals, and the recommendation — would they know what you're proposing and why, and have everything they need to push back?

If not, you haven't written it for the reader yet. Fix that before you ask for the review.