Engineering RFC and Design Doc Template

Write one when the right design isn't obvious. Malte Ubl, formerly an engineering director at Google and now Vercel's CTO, says the central question is whether the solution is ambiguous¹. If a doc would only say how you'll build something, with no trade-offs or alternatives, he suggests writing the code instead.

An RFC earns its keep when a change:

• is hard or expensive to reverse
• changes an interface, data format or service other teams rely on
• has two or more serious options and no obvious winner
• adds work for another team, such as on-call duty or a migration

Whatever your team calls the sections, cover these. Write the problem before the solution, and give it a number. "Adding a tenant takes 40 minutes of manual broker work" can be checked; "per-tenant topics don't scale" can only be argued with.

Leave estimates and task lists for planning, after the decision. If nobody has written down what users need yet, start with a product requirements document.

Show the options you turned down, and give each a real reason. "More complex" is a preference; "needs a second consumer group per tenant, so it keeps the cost we're removing" is a reason. Python's PEP 1 asks authors to record rejected ideas with their reasoning, partly to stop people bringing up the same rejected idea again².

Always include doing nothing and what it costs; if the answer is "not much," you may not need the change. The Rust project warns that RFCs which are disingenuous about the drawbacks or alternatives³ tend to be poorly received.

Write migration and rollback before the formal review. A rollback section added late invites the costliest objection, one that arrives after reviewers have signed off. Name the point of no return, and leave the detailed cutover to a technical migration plan.

Share a rough draft with the people closest to the problem before it feels finished. In 1969, Steve Crocker's conventions for the first RFCs encouraged notes to be timely rather than polished⁴. Squarespace saw what happens otherwise: facing review by most of its infrastructure organization, engineers held RFCs back until they were very polished. By then the authors were invested, and major changes weren't welcome⁵.

Put one decider and a decision date in the header. Tanya Reilly, describing Squarespace's process, writes that naming approvers makes clear where the decision lies⁵. Make the decider one person, not a committee, so a missed date has an owner. Allow about 2 weeks for a change inside one team and 6 when it crosses several.

Ask reviewers to label each comment blocking, non-blocking or a question. Squarespace found that authors flooded with comments struggled to tell blockers from "interesting asides"⁵. Conventional Comments, a labeling standard for reviews including RFCs, defines a blocking comment⁶ as one that should prevent acceptance until resolved.

A blocking comment should also say what would resolve it. Squarespace approvers answer "yes" or "not yet" rather than "no," and in its architecture reviews the most common answer is "Yes, if you make sure that…"⁵

Close every comment, and record how: accepted and the design changed, declined with a reason, answered, or deferred to a numbered follow-up. While any blocking comment is open, don't move the RFC toward a decision.

End with a last call. Rust's process requires every subteam member to sign off before its final comment period begins, often the point when many first review the RFC in full depth³. The period runs 10 calendar days, so it's open for at least 5 business days.

Draft, in review and approved can't tell a decided no from a parked maybe, or an accepted RFC from a built one. Kubernetes' proposal template allows seven statuses: provisional, implementable, implemented, deferred, rejected, withdrawn and replaced⁷. The distinctions worth keeping:

• Accepted: decided yes, not yet built.
• Implemented: shipped and in service.
• Rejected: decided no, with the reasoning kept.
• Withdrawn: pulled by its author.
• Superseded: replaced by a later RFC, linked both ways.
• Deferred: nobody is working on it.
• Postponed: the team chose to wait, and named what will reopen it.

PEP 1 lets an author or editor mark a proposal Deferred when no progress is being made², which says nothing against the idea. Accepted isn't done either. Rust's RFC process says acceptance implies nothing about priority or about who will build it. Every accepted RFC there gets an issue tracking its implementation³, and its author isn't obliged to build it, so name an owner.

Then write the decision down: what was decided, who decided it, where, and which objections were overruled. PEP 1 makes authors responsible for documenting dissenting opinions², and says a decided proposal should show its new status and link to the post that made the decision. File the outcome as an architecture decision record.

Once a month, sweep for RFCs past their decision date, silent for 60 days or accepted with no owner.

If the agreed design needs a security review, take it through a STRIDE threat model next. To start faster, open this template in River, which builds the register from the RFCs you already have.