Writing Effective RFCs
⏱️ ~3-minute bite · solve the sandbox to master
5-Year-Old Metaphor
— The physical, real-world picture. No jargon.📝 An RFC is a design document that thinks out loud — so others can critique your assumptions before you write code.
Why RFCs exist
Arguing about text is cheap. Rewriting code after a design flaw is found in review is expensive. An RFC surfaces disagreements at the design stage, when changing direction costs hours — not weeks.
The RFC is not about getting approval to work. It's about building shared understanding so that when you do write code, the team is aligned on what and why — not discovering disagreements in code review comments.
When to write an RFC
- • Affects multiple teams or services
- • Hard to reverse (data schema, API contract)
- • Non-obvious tradeoffs worth capturing
- • Security or privacy implications
When NOT to write an RFC
- • Bug fixes with obvious solutions
- • Single-team changes with no external impact
- • Small features behind a flag
- • Reversible experiments
ADR as a lighter alternative
Architecture Decision Records (ADRs) are one-page records of a decision made: context, decision, consequences. Simpler than a full RFC. Good for capturing decisions after they're made, not for pre-decision alignment.
Interactive Sandbox
— Move something, see it react instantly.RFC Section / Process
The five sections every RFC needs and why each exists
Context
Give reviewers the background they need without assuming prior knowledge
Good
Our checkout service currently processes payments synchronously. This means a slow payment gateway blocks the entire request thread for 3–8 seconds, affecting 12% of checkout conversions.
Bad
As we all know, the payment situation has been causing problems lately.
Anti-pattern: Assume everyone knows the history — skip context
Problem
State the user/system problem clearly — NOT the solution
Good
Users experience a 3–8s UI freeze during payment processing because synchronous calls block rendering. 8% of users abandon during this wait.
Bad
We need to refactor the payment service to use async processing.
Anti-pattern: Frame the problem as 'We should add X' rather than what breaks without X
Proposal
One concrete solution with enough specificity to implement
Good
Move payment processing to a background queue (BullMQ + Redis). Show optimistic 'Payment submitted' UI immediately. Poll for status via /api/payment-status/:id every 2s.
Bad
We could use queues, or maybe webhooks, or perhaps just increase the timeout. Any of these might work.
Anti-pattern: List multiple options in the proposal (save those for Alternatives)
Alternatives
Show you considered other approaches and explain why you rejected them
Good
Alt 1: Webhooks from payment gateway — rejected because Stripe's webhook delivery can take 30s+, creating a worse UX. Alt 2: WebSockets — over-engineered for a one-time payment status.
Bad
We considered other options but this one is the best.
Anti-pattern: Skip alternatives entirely — looks like you didn't think it through
Open Questions
Call out unresolved decisions explicitly — invite input on them
Good
Q1: What is the acceptable timeout before we show an error? Suggested: 30s. Q2: Should we support partial payments if the queue is down? Leaning no — fail fast.
Bad
(no open questions listed — the RFC is 'done')
Anti-pattern: Hide uncertainties — pretend everything is solved
Challenge
Visit all 5 RFC patterns. Understand what makes each section effective.
Why Should I Care?
— The exact interview question + the bug it kills.Interview questions
Q: When is an RFC overkill vs necessary?
RFC is overkill for: single-team changes, bug fixes, reversible experiments, features behind a flag. RFC is necessary for: cross-team API contracts, data schema changes (hard to reverse), security decisions, architectural patterns you expect to replicate. The test: if the decision were made wrong and you discovered it 6 months later, how expensive is the fix? Expensive = write the RFC.
Q: What makes a good problem statement?
A good problem statement: (1) is user-framed, not tech-framed, (2) quantifies impact, (3) identifies root cause, (4) states scope boundaries. Test: can a reviewer read it and suggest a completely different solution? If yes, the problem statement is good — it leaves the solution space open. If the problem statement already implies a specific solution, it's too narrow.
Q: How do you handle disagreement in RFC reviews?
Distinguish: (1) factual disputes — resolve with data, (2) preference disputes — author decides, (3) blocking concerns — require a stated alternative. A reviewer who blocks without proposing an alternative loses their veto. The author must respond to comments in the doc (update the RFC text, not just reply in thread). If disagreement persists, escalate to a designated decision-maker — don't let the RFC stall forever.
The Deep Dive
— Spec refs, engine internals, the minutiae.RFC processes at major companies
1–5 pages. Mandatory for changes with cross-team impact. Template: Background, Objective, Scope, Design, Alternatives, Testing, Rollout. Decision recorded in-doc.
Narrative prose, no bullets. Read silently at the start of meetings. Forces complete thinking — no hiding behind bullet points. PR/FAQ variant for product decisions.
Public GitHub PR. Community comment, core team signs off. Every language change has a merged RFC. Historical archive of every decision and its reasoning.
GitHub Discussions for async RFC
GitHub Discussions (not Issues) is a good async RFC forum: threaded comments, emoji reactions for quick feedback, markdown support, searchable. Pair with a PR to a docs/rfcs/ directory to make decisions part of the repo history.
Tip: use a template that enforces the RFC structure. Pin the template as a Discussion announcement so authors know the format before starting.
Interview Questions
— Real questions from real interviews — with answers.Strong problem statement + honest alternatives unlocked the team's real concerns.
Reversibility and blast radius determine the weight of the process.
RFC overhead is real — the fix is scoping, not skipping.
Surface their concerns in the RFC before they raise them in review.
Solution-first problem statements are the most common RFC failure mode.
The decision record matters as much as the approval.
Memory Game
— Quick quiz — lock the concept in long-term memory.When should a full RFC be written instead of just opening a PR?