The Proposal Document
While an ADR records a decision after it's made (or at the moment it's made), an RFC (Request for Comments) is used before a decision is made. It is a proposal document — a structured way of saying "here's a significant change I think we should make, and I'd like your input before we commit to it."
The term "RFC" comes from the Internet Engineering Task Force (IETF), where RFCs have defined the fundamental protocols of the internet (HTTP, TCP/IP, DNS) since 1969. In modern engineering organizations, the term is borrowed to mean any structured proposal for a significant technical change. Companies like Google (design docs), Amazon (six-pagers), and Rust (RFCs) all use variations of this pattern.
When should you write an RFC instead of just making the change?
Use an RFC when the proposed change is:
- Hard to reverse — Choosing a new cloud provider, adopting a service mesh, changing the data serialization format across all services.
- Cross-cutting — Affects multiple teams, services, or systems.
- Controversial — Reasonable engineers might disagree on the approach.
- Expensive — Requires significant engineering time (weeks or months) to implement.
These are what Amazon calls "Type 1" decisions — one-way doors that are difficult or impossible to walk back through. For "Type 2" decisions (easily reversible, low-blast-radius), an RFC is overkill. Just make the decision, optionally record it as an ADR, and move on.
The Goal of an RFC:
- Define a complex problem clearly. Force the author to articulate the problem precisely, with data.
- Propose a detailed solution. Include enough technical detail that reviewers can evaluate feasibility.
- List alternative solutions that were considered and explain why they were rejected.
- Gather feedback from stakeholders across the organization to surface blind spots, risks, and objections before writing code.
- Build consensus. The RFC process ensures that by the time implementation begins, the key stakeholders have already weighed in. This prevents the demoralizing pattern of building something for weeks only to have it rejected in a late review.
RFC vs. ADR — The Relationship:
| Aspect | RFC | ADR |
|---|---|---|
| When | Before a decision | At the moment of (or after) a decision |
| Purpose | Propose and debate | Record and preserve |
| Audience | Broad — anyone who might be affected | Future engineers and the team itself |
| Length | Long — often 3-10 pages with diagrams | Short — typically 1 page |
| Mutability | Evolves during review | Immutable once accepted |
| Format | Often a Google Doc, Notion page, or wiki for easy commenting | Markdown file in Git |
RFCs and ADRs are complementary, not competing. The typical flow is: write an RFC → gather feedback → reach consensus → record the final decision as a concise ADR. The RFC captures the debate; the ADR captures the outcome. You can think of the RFC as the working notes and the ADR as the meeting minutes.
Key Point: The most common failure mode with RFCs is treating them as a formality — writing the RFC after the decision has already been made, or ignoring feedback because the author is emotionally committed to their proposal. An RFC process only works if the organization genuinely allows proposals to be changed or rejected based on feedback. If RFCs are rubber stamps, engineers will stop engaging with them within a few months. The signal that an RFC culture is healthy: proposals are regularly modified or rejected based on reviewer feedback, and authors treat this as a success, not a failure.