RFCs work when they are short, opinionated, and time‑boxed.
Good RFCs speed up decisions, capture dissent, and reduce rework. Bad RFCs create consensus theater where everyone says “LGTM” after skimming page 7. The difference isn’t tooling; it’s posture. Make it cheap to propose and strict to accept. Treat comments as input, not votes. Name a decision owner up front and give them a deadline.
Why RFCs exist (for engineers)
- Create a durable record of the problem, options, and tradeoffs before code calcifies the choice.
- Invite the right reviewers to find irreversible mistakes early (data shape, boundary choices, coupling).
- Make cross‑team constraints visible so we avoid surprises at integration time.
- Build a searchable history that future you will bless when debugging “why is it like this?”
Common failure modes
- Novel‑length documents that are really design docs trying to be specs. Keep the RFC tight; link deep dives.
- Unbounded comment threads where the work is arguing, not deciding. Set a review window and close it.
- Decision by polling. Opinions are not weighted equally; the owner decides after listening.
- Drive‑by approvals. If you’re a named reviewer, you’re accountable for reading and responding on time.
- Stale drafts. If the context changed, close the RFC instead of letting it rot as undead process.
Lightweight mechanics that scale
- Template: problem statement, constraints, options (with pros/cons), preferred path, risks, open questions.
- Page limit: one page for the core, plus links to docs, diagrams, or spikes.
- Review window: 3–5 business days by default; shorten for low‑risk changes, extend with justification.
- Roles: author, named reviewers (domain owners), decision owner (one person), approver of risk (e.g., SRE/security) when relevant.
- Meeting policy: async first; if a synchronous discussion happens, summarize back into the RFC.
- Decision log: date decided, owner, rationale summary, dissenting opinions captured, follow‑ups.
Tooling that keeps momentum
- Keep RFCs in the repo with the code (e.g.,
docs/rfcs/), opened via PR. Status via labels:draft,reviewing,accepted,rejected,superseded. - Use short slugs like
rfc-012-tenant-migrations. Link issues, spikes, and diagrams. - When accepted, mint or update an ADR. The RFC is the conversation; the ADR is the decision.
A five‑day example timeline
- Day 0: Author posts draft, tags reviewers, sets decision date.
- Day 1–2: Reviewers comment; author updates or answers.
- Day 3: If unresolved high‑impact questions remain, time‑box a 30‑minute live review.
- Day 4: Decision owner decides and records rationale. If “needs more evidence,” define the spike and new date.
- Day 5: Convert to ADR and link to tracking tickets. Archive alternatives as “considered and rejected.”
What to RFC (and what not to)
RFC: public API changes, data model evolutions, cross‑service contracts, irreversible migrations, new external vendors, security‑relevant posture changes.
Not an RFC: local refactors, copy updates, small internal abstractions, test strategy changes that don’t alter external behavior.
Measuring if your RFC process works
- Median time to decision (target days, not weeks).
- Percent of accepted RFCs linked to ADRs and tickets (should be ~100%).
- Number of “late design changes” discovered after implementation started (trend down).
- Reviewer SLA hit rate (named reviewers responding within the window).
If your RFCs routinely trigger architectural clarity and unblock execution, the process is working. If they become a museum of frozen ideas, burn it down and start smaller.
My favorite shape
- One‑pager first: Problem, options, preferred path, risks, open questions.
- Review window: 3–5 days with explicit reviewers.
- Decision owner: One name. Comments are input, not consensus.
- ADR link: The accepted RFC becomes an ADR.
If your RFC takes a month to approve, it’s not a process — it’s a museum.