The fintech startup started using RFCs (Request for Comments documents) when we hit seven engineers and decisions stopped being made naturally in conversation. Before RFCs, we’d build something, present it, discover disagreement, and partially rewrite. The disagreement was always there — we just discovered it late.
RFCs in theory: write down what you’re proposing before building it, get feedback, align, then build. RFCs in practice, initially: long documents that people didn’t read, discussions that went in circles, and decisions that weren’t really made.
The format that fixed it took six months to evolve.
Why RFCs Fail
Too long, too detailed. The author knows every nuance of the problem and wants to share it. The reader needs to understand the decision, not re-derive it. A 15-page RFC with comprehensive background gets skimmed; the nuance is lost.
Buried decision. The RFC tells a story that builds to a conclusion, but busy reviewers read the first two sections and stop. The decision they need to comment on is on page 4.
Missing context. The author understands why this matters. The reader doesn’t have that context. The RFC feels like a solution in search of a problem.
No clear ask. “Comments welcome” is not a useful ask. “Do you agree with the choice of Flink over Kafka Streams? Do you see any operational risks with the deployment model?” is a useful ask.
No deadline. Without a deadline, the discussion drifts and the RFC enters a state of “not quite decided” that can persist for weeks.
The Format That Worked
## [Title]
**Author**: [name]
**Status**: Draft | Review | Decided | Implemented
**Decision needed by**: [date]
---
### Decision
[1-3 sentences. What has been decided or what needs to be decided.
This is the most important section. Put it first.]
### Context
[2-4 paragraphs. Why are we making this decision now? What problem
are we solving? What constraints apply?]
### Options Considered
**Option A: [Name]**
[2-3 sentences describing it]
Pros: ...
Cons: ...
**Option B: [Name]**
[2-3 sentences describing it]
Pros: ...
Cons: ...
### Recommendation
[Which option you recommend and why. Be direct.
"I recommend Option A because X" not "Option A may be worth considering."]
### Open Questions
- [Specific thing you need input on]
- [Another thing]
### Appendix (optional)
[Background detail for those who want to go deeper]
Why Each Section Matters
Decision first: reviewers who only read one section read the first. Putting the decision first means even a quick reader knows what’s being decided.
Status and deadline: “Decision needed by Friday” creates urgency. Without a deadline, reviews drift. The status field lets people know whether this is still open or already settled.
Context separate from decision: keeps the narrative of the context from burying the decision. Forces the author to articulate why this matters in isolation.
Explicit options: forcing yourself to write out multiple options, with honest pros and cons for each, often reveals that the “obvious” choice isn’t as obvious as you thought. It also gives reviewers something concrete to react to.
Open questions: the most important thing to get right. These are the specific things you need from reviewers. Vague asks get vague responses. “Does anyone see operational risks with running two Flink clusters?” gets specific responses.
The Review Process
Share the RFC before the meeting, not at it. Async reading produces better comments than reading in a room together. Give 2–3 days for async review before any synchronous discussion.
Use comments in the document. Google Docs or Notion inline comments on specific sections beats “thoughts?” in Slack. Specific comments stay attached to the specific text being discussed.
Designate a decision maker. RFC discussions stall when everyone’s opinion carries equal weight and consensus is required. Designate who makes the final call. Everyone comments; one person decides.
Close the loop. After the decision is made, update the RFC with:
- Final decision and rationale
- Any rejected alternatives and why
- Names of people consulted
This becomes institutional memory. Six months later, when someone asks “why did we use Flink?”, the answer is in the RFC.
What a Good RFC Unlocks
Disagreement discovered cheaply. The cost of disagreement in a 30-minute RFC review is zero. The cost of disagreement three weeks into implementation is weeks of rework.
Asynchronous participation. Not everyone who has relevant input can attend every meeting. An RFC captures decisions in a format that people can engage with in their own time.
Onboarding material. New team members who read the RFC archive understand not just what was built but why. This is significantly more useful than code comments or documentation that describes the “what” without the “why.”
Trust. Engineers who see their input reflected in decisions feel heard. Engineers who watch decisions happen in rooms they weren’t in feel excluded. RFCs make decisions more visible and the reasoning more transparent.
What RFCs Don’t Fix
Low-trust environments. If the team doesn’t trust that feedback will be genuinely considered, RFCs become theater — people write comments for the record, not because they expect to change anything. Fix the trust problem first.
Analysis paralysis. Some teams use RFC processes to delay decisions indefinitely. A RFC is a decision-making tool, not a decision-avoiding tool. Set a deadline and hold to it.
Decisions that don’t need a RFC. Not every technical decision needs a formal document. Small, reversible, low-stakes choices should be made quickly and informally. Reserve RFCs for decisions that are hard to reverse, affect multiple people, or require shared understanding to execute well.
The discipline of asking “does this need an RFC?” is itself useful. If the answer is “yes, because we’ll regret not having alignment before we start,” write one. If the answer is “no, because we can just try it and change it if it’s wrong,” don’t.