Writing Design Docs, RFCs and ADRs
On this page
Learning Objective
Write design documents and architecture decision records that let others understand, challenge and later remember your decisions, include security, privacy, operations and cost as standard sections, and run a lightweight review process.
Concept Explanation
A senior engineer's influence is mostly written. A design document is written before building a significant change, to think clearly, to let others find problems while they are cheap to fix, and to record the reasoning. It is not a specification of every detail. A useful structure is short and consistent: the context and problem, goals and, just as important, non-goals, the proposed design with a diagram, the alternatives considered and why they were rejected, and the cross-cutting concerns. Those concerns are where teams skip the hard parts, so make them mandatory sections: security and privacy, including data classification, authentication and authorization model, and a summary of the threat model from Day 41; reliability and failure modes; observability and the SLOs from Day 141; migration and rollout; cost; and open questions. Writing the security section forces the questions that reviewing code later cannot answer.
Write for the reader. Put the conclusion first, since many readers will stop after a page. Use plain words, define terms, show concrete examples, and use diagrams that stay in the repository as text, using tools such as Mermaid so that they are reviewed and updated with code. The C4 model by Simon Brown gives a helpful way to layer diagrams from system context to containers to components, so each diagram has one audience and level of detail. Amazon replaced slide presentations in senior meetings with written narratives of several pages, read silently at the start of the meeting, on the belief that prose forces complete thinking that bullet points allow you to hide from.
An architecture decision record captures a single decision in a page. Michael Nygard proposed the format in 2011: a title, a status such as proposed, accepted, or superseded, the context in which the decision was made, the decision itself, and its consequences, good and bad. They live in the repository, numbered, next to the code, and are never edited to change history: a new record supersedes an old one. Their value appears a year later when someone asks why the team chose a backend-for-frontend, rather than storing tokens in the browser, and the answer, with the alternatives and the constraints of that time, is one file away. Use them also to record exceptions, such as a deliberate deviation from a security standard, with the reason and an expiry date for revisiting.
Review is a social process and needs light structure. Circulate the document to the people affected and to at least one person with security and one with operations knowledge, set a deadline for comments, and discuss disagreements in a meeting instead of a long comment thread. Decide who has the final say, since consensus is not always possible. Distinguish reversible decisions, which Jeff Bezos called two-way doors and which should be made quickly, from irreversible ones, one-way doors, which deserve more care. Open source projects show the process at scale: Python's enhancement proposals and Rust's RFC process both require a written proposal, public discussion, and a recorded outcome. Also keep other documents alive: a README that gets a newcomer running in minutes, runbooks tested by using them, API documentation generated from the contract, and a changelog. Documentation kept in the repository and updated in the same pull request as the code has the best chance of staying true.
| Document | Purpose | Key sections |
|---|---|---|
| Design doc | Think through a significant change and get review | Context, goals and non-goals, design, alternatives, security, operations, rollout |
| ADR | Record one decision and why | Status, context, decision, consequences |
| RFC | Propose a change to shared standards or platforms | Motivation, detailed design, drawbacks, alternatives, unresolved questions |
| Runbook | Steps for operating and recovering | Symptoms, checks, mitigations, escalation |
| README | Get a newcomer productive | What it is, how to run, how to test, how to contribute |
| Diagrams as code | Keep pictures reviewable and current | Mermaid or similar, one level of detail each |
Worked Example: A Design Doc Skeleton, an ADR and a Diagram as Code
The template lists sections, including the ones teams tend to skip, followed by a filled-in ADR and a diagram.
# Design: Passkey sign-in for the Task Board
Status: In review Author: A. Rivera Reviewers: security, platform, support Decide by: 2026-10-16
## Summary (read this if nothing else)
Add passkeys as a sign-in method alongside passwords, with recovery codes, so that phishing can no longer take over accounts. Rollout is opt-in for 4 weeks, then default for new users.
## Context and problem
Account takeover through phishing accounts for most support escalations this quarter. Passwords and SMS codes cannot resist it.
## Goals / Non-goals
Goals: passkey registration and sign-in on web, recovery without support tickets, no regression in sign-in success rate.
Non-goals: removing passwords in this phase, native mobile apps, enterprise SSO (see Day 133 design).
## Proposed design
(diagram) API endpoints, data model (Passkeys table), session handling, step-up for sensitive actions.
## Alternatives considered
1. TOTP only: cheaper, but still phishable. 2. Hardware keys only: strong, poor reach. 3. Buy an identity vendor: faster, ongoing cost and data residency questions.
## Security and privacy
Data: credential ids and public keys only, classification internal. Threats: challenge replay (single-use challenges), recovery abuse (delay and notify), credential enumeration (uniform responses).
Authorization: registration requires recent authentication. Threat model summary linked, review by security scheduled.
## Reliability, observability, cost
Failure modes: library outage, browser support gaps (password fallback). SLI: sign-in success rate, alert on burn rate. Cost: none beyond engineering time.
## Rollout and rollback
Feature flag by cohort. Rollback: flag off, existing passwords unchanged. Migration: none required.
## Open questions
How long should recovery delay be for accounts with billing admin rights?# ADR 0014: Keep tokens on the server with a backend-for-frontend
Status: Accepted (2026-03-04)
## Context
The React app calls the Tasks API. Storing access and refresh tokens in the browser exposes them to any script that runs on the page,
including a compromised dependency. Our threat model (Day 41 analysis, linked) rates token theft through cross-site scripting as high impact.
We have one web client, an ASP.NET Core API, and a team already operating a server component.
## Decision
The ASP.NET Core BFF performs the OpenID Connect flow, holds tokens server side, and gives the browser only an HttpOnly, SameSite cookie.
The SPA calls same-origin endpoints. We do not store tokens in localStorage or sessionStorage.
## Consequences
+ A script injected into the page cannot read tokens. CSRF is handled with SameSite cookies and a custom header.
+ Token refresh and revocation are centralized.
- Session state lives on the server, so it needs a shared store when scaled out (Redis, Day 67).
- The BFF is one more component to deploy and monitor.
Revisit if we add native mobile clients (they will use the authorization code flow with PKCE against the same identity provider).
Supersedes: ADR 0009 (tokens in memory). Related: ADR 0011 (cookie policy).flowchart LR
user([Person]) --> spa[React SPA]
spa -- same-origin cookie --> bff[ASP.NET Core BFF]
bff -- bearer token --> api[Tasks API]
bff -- OIDC code + PKCE --> idp[(Identity provider)]
api --> sql[(SQL Server)]Notice that the ADR states the negative consequences honestly. A record that lists only benefits is advocacy, and the reader a year later needs to know what was traded away.
Real-World Examples
- Amazon's practice of six-page narrative memos, introduced by Jeff Bezos in 2004 to replace slide presentations in executive meetings, has each meeting begin with silent reading. His reasoning was that writing in full sentences requires clearer thinking, and the practice has been widely copied for decision documents.
- Python's enhancement proposals, PEPs, and Rust's RFC process are public examples of design review at scale: a written proposal with motivation and alternatives, open discussion, and a recorded decision. The archives are valued because they explain why the languages work as they do, which is what an ADR aims to do for a single system.
Review Questions & Answers
They set the boundaries of the work, prevent reviewers from asking for unrelated features, and make explicit what the team decided not to do. This avoids scope creep and shows what was deliberately left for later.
They record what was decided and why at that time, which is valuable history. When circumstances change, a new record supersedes the old one, so the reasoning for both remains available.
Teams tend to skip them because they are hard, and gaps found after building are expensive to fix. Writing them early forces questions about data, authorization, failure, monitoring, and rollback while the design can still change.
Two-way door decisions are easily reversed and should be made quickly by a small group, while one-way door decisions are costly or impossible to reverse and deserve deeper analysis and wider review. Matching the process to reversibility avoids both recklessness and delay.