Topic: adr vs rfc

ADR vs RFC: What's the Difference and When Should You Use Each?

Q: What is the difference between an ADR and an RFC?

An RFC (Request for Comments) is a pre-decision document: it proposes an architectural approach and solicits feedback before a decision is made. The RFC is open — it can be revised, debated, and accepted or rejected. An ADR (Architecture Decision Record) is a post-decision document: it records what was decided, why, and what alternatives were rejected. The ADR is closed — once Accepted, the body is immutable and changes happen through supersession. The formats are sequential, not competing. The ideal workflow is: RFC (proposal + feedback period) → decision reached → ADR written from the RFC outcome. Teams that skip the RFC write ADRs directly and accept more decision risk; teams that skip the ADR write RFCs but never produce a durable record.

Q: Should I write an RFC or an ADR first?

Write an RFC if the decision is contested, cross-team, high-cost-to-reverse, or if you genuinely don't know the right answer yet and need input. Write an ADR directly (skipping the RFC) if the decision is already clear to the decision-makers, the trade-offs are well understood, and you're recording rather than proposing. In practice: if you're presenting something to your team for feedback, write an RFC; if you're telling your team what was decided and why, write an ADR. The most damaging mistake is writing an ADR when you should have written an RFC — presenting a fait accompli when you actually wanted input, which creates resentment ('why even ask us?') and erodes trust in the ADR practice.

Q: Can you have both an RFC and an ADR for the same decision?

Yes, and this is the best practice for significant architectural decisions. The RFC documents the proposal and collects the feedback thread; the ADR records the final decision with rationale synthesized from that feedback. The two documents serve different audiences: the RFC is for reviewers who want to influence the decision; the ADR is for future readers who need to understand it. Once the ADR is written and Accepted, the RFC can be marked 'IMPLEMENTED' or 'CLOSED — see ADR-NNNN' and archived. The ADR becomes the canonical record; the RFC thread becomes supporting evidence that lives in the PR discussion history or a separate design-docs repository.

Q: What happens to the RFC once the ADR is written?

The RFC should be marked closed with a reference to the ADR: 'Status: ACCEPTED — see doc/decisions/0042-use-rabbitmq.md' or equivalent. If the RFC lived as a pull request, add the ADR number to the PR description before merging or closing the RFC PR. If the RFC lived as a Google Doc or Notion page, update the status header. Do not delete the RFC — it contains the feedback thread, the alternatives that were raised and rejected, and the reasoning that shaped the final decision. That thread is the raw material that the ADR's Context section should synthesize. Teams that delete RFCs after writing an ADR lose the evidence that explains why the ADR reads the way it does.

The most common confusion in engineering documentation: you call something a "design doc" or "RFC" and someone else calls the same artifact an "ADR." They're not synonyms. RFC (Request for Comments) is a pre-decision document — a proposal seeking feedback before the decision is made. ADR (Architecture Decision Record) is a post-decision document — a record of what was decided and why. Using the wrong format at the wrong moment is the most reliable way to damage team trust in your documentation practice. Write an ADR when you meant an RFC and you've presented a fait accompli to people who thought you wanted input. Write an RFC and never follow it with an ADR and you've left the decision unrecorded. The two formats are sequential, not competing: RFC opens the conversation, ADR closes it.

TL;DR

RFC = pre-decision, open, seeking input. Write an RFC when you have a proposal and want feedback before committing. The RFC can be revised, debated, withdrawn, or accepted. ADR = post-decision, closed, preserving rationale. Write an ADR when the decision is made and you need a durable record of what was decided, why, and what was rejected. The ideal workflow: RFC during the proposal phase → decision reached → ADR written from the RFC outcome. Both can coexist for the same decision; neither replaces the other.

The core distinction: timing and state

The single most important difference between an RFC and an ADR is when each is written relative to the decision, and what state it carries.

	RFC (Request for Comments)	ADR (Architecture Decision Record)
Timing	Before or during the decision — written when the outcome is still open	After the decision — written when the outcome is settled
Status	Open: can be revised, debated, rejected, or withdrawn	Accepted (or Rejected): body is immutable after acceptance
Primary purpose	Solicit input and surface alternatives before committing	Record rationale and rejected alternatives for future readers
Audience	Reviewers who will comment and influence the decision	Future engineers who need to understand a past decision
Outcome of disagreement	Revision of the proposal, or escalation to a decision-maker	A new ADR that supersedes the old one (not an edit)
Format	Flexible (PR, Google Doc, Notion page, GitHub issue)	Standardized template (Nygard, MADR, or team variant)
Storage location	Design docs repository, PR description, wiki, shared drive	`doc/decisions/` in the main repository (or team's ADR store)
Lifecycle	DRAFT → OPEN → ACCEPTED / REJECTED / WITHDRAWN	PROPOSED → ACCEPTED → SUPERSEDED / DEPRECATED

What "RFC" actually means in an engineering team context

The term "RFC" comes from the IETF (Internet Engineering Task Force), where it means a formally published document that has already been approved — IETF RFCs are not actually "requests for comments" in the literal sense by the time they're numbered; they're published standards. In engineering team usage, "RFC" means something different: a design proposal circulated for feedback before a decision is made. This is closer to what IETF calls an "Internet Draft."

In engineering teams, RFC is a shorthand for "here is our proposed approach, please comment before we commit." Well-known examples of formal RFC processes:

Rust RFCs: Formal pull requests to the rust-lang/rfcs repository. An RFC must be merged into that repo before a feature is implemented. After implementation, a separate tracking issue and stabilization process follow; the RFC is never retroactively turned into an ADR, but it serves a similar rationale-preservation function for the language itself.
Python PEPs (Python Enhancement Proposals): Functionally equivalent to RFCs; proposals go through a formal discussion and acceptance process before implementation.
Engineering team design docs: Less formal than Rust RFCs — a Google Doc, a Notion page, or a GitHub PR that the team comments on for a week. The format varies; the process (propose → feedback → decision) is consistent.

The key property that makes an RFC an RFC (in the team context) rather than an ADR is that it is written when the author does not yet have authority or consensus to close the decision — the document exists to build that consensus.

The RFC → ADR handoff pattern

For significant architectural decisions, the best-practice workflow sequences RFC and ADR rather than choosing one:

Write the RFC. Document the proposed approach, the alternatives considered, the trade-offs, and the open questions. Be explicit that this is a proposal, not a decision. Share with stakeholders and set a feedback window (typically one to two weeks for non-urgent decisions).
Collect feedback. Reviewers comment, raise alternatives, identify risks. The RFC author updates the proposal in response, or acknowledges feedback that won't change the recommendation. The RFC thread is the record of the deliberation.
Reach a decision. Either through consensus, a decision-maker call, or an explicit vote. The decision should be announced in the RFC thread so all participants know the outcome and its basis.
Write the ADR. The ADR is written from the RFC outcome. The ADR's Context section synthesizes the constraints and alternatives surfaced in the RFC thread. The Decision section states the chosen approach. The Consequences section captures the trade-offs that the RFC feedback highlighted. The ADR should stand alone — a reader with no access to the RFC should be able to understand the decision from the ADR alone.
Close the RFC. Mark the RFC as ACCEPTED (or REJECTED) with a reference to the ADR: "ACCEPTED — see ADR-0042." Merge or archive the RFC document. Do not delete it — the feedback thread is evidence.

The RFC thread is raw material for the ADR's Context section. This is the most underused aspect of the RFC → ADR handoff. The RFC discussion often surfaces the alternatives that reviewers raised, the constraints that ruled them out, and the organizational pressures that made the decision urgent. All of that belongs in the ADR's Context section. Teams that write ADRs without referring to the RFC thread write thin Context sections that omit the real reasons the decision went the way it did.

The two mistakes that damage team trust

Mistake 1: Writing an ADR when you meant an RFC

The symptom: you write an ADR titled "ADR-0042: We will use Kafka for the event bus" and share it for "feedback." Your colleagues comment with objections, alternatives, and concerns. You incorporate none of them and merge the ADR. The next time you share an ADR for feedback, nobody comments — they've learned that the feedback window is cosmetic.

The root cause: you had already decided before you shared the document. The document was framed as an ADR (past-tense, closed) but functioned as an RFC (seeking input). The mismatch between the framing and the reality created the trust problem.

The fix: Be honest about the decision state. If you want input before committing, write "RFC: Proposed approach for the event bus" — even if you strongly prefer one approach. An RFC can have a clear recommendation; it just makes clear that the recommendation is open to revision. If you've already decided, write an ADR but don't solicit "feedback" — share it as a record and invite questions instead.

Mistake 2: Writing an RFC and never writing the ADR

The symptom: the RFC gets feedback, reaches a decision in the thread, and is marked ACCEPTED. Six months later, a new engineer asks why the event bus is Kafka. Nobody can find the decision. The RFC exists but it's buried in a 60-comment PR thread in a design docs repository that nobody knows about. The decision is effectively unrecorded.

The root cause: the RFC closed the proposal process but didn't produce a durable record. The RFC thread has the rationale, but RFC threads are hard to find and hard to read — they're chronological discussions, not structured records.

The fix: Make the ADR a required output of the RFC process. When the RFC is marked ACCEPTED, the author is responsible for writing an ADR in doc/decisions/ before the RFC PR is merged. The ADR GitHub Action can enforce this: if an RFC PR contains changes to the RFC file, it can require a corresponding ADR file to be present in the same PR.

When to skip the RFC and write the ADR directly

Not every decision needs an RFC. The RFC process adds value when:

The decision will affect multiple teams and they should have input
You have a preference but not enough authority to close the decision alone
The trade-offs are non-obvious and you expect reviewers to surface alternatives you haven't considered
The decision is high-stakes and you want the deliberation on record

Skip the RFC (write the ADR directly) when:

The decision is entirely within your team's domain and authority
The trade-offs are well understood and the decision is clear to the decision-maker
Speed is critical and a feedback window would cost more than the risk of a suboptimal choice
You're writing a retrospective ADR for a decision already implemented — there's no pre-decision stage to solicit input on

The four-question threshold from the when-to-write-an-adr guide tells you whether a decision warrants an ADR at all. The RFC question is a separate test: given that this decision warrants documentation, does it also warrant a pre-decision feedback phase? Many ADRs don't — they're intra-team calls where the lead can decide and record without a formal RFC cycle.

Teams with existing RFC cultures: integrating ADRs without conflict

Some organizations (particularly those that grew up with Google's design doc culture or Rust-style RFC processes) have strong RFC habits but no ADR practice. When these teams adopt ADRs, the most common failure mode is treating the RFC as the ADR — keeping the decision in the RFC thread and never writing a structured record.

The integration approach that works without creating conflict:

Position ADRs as the output, not the replacement. "We'll keep writing RFCs the same way. We'll add one step at the end: when an RFC closes as ACCEPTED, whoever wrote it adds a 5-minute ADR to doc/decisions/." This framing adds ADRs to the existing process rather than competing with it.
Use the RFC thread as Context. The Context section of the ADR is the hardest field to write cold; the RFC thread already contains it. Tell the team: "Your RFC thread is your ADR draft — the Context section practically writes itself from the alternatives that were raised."
Start with retrospective ADRs on existing decisions. The ADR adoption guide's retrospective-first approach applies here: pick five decisions that have RFCs, write ADRs from those RFCs, and let the team see the difference between reading a 60-comment RFC thread versus a 300-word ADR. The comparison makes the ADR's value self-evident.
Don't require an ADR for every RFC. Only decisions that pass the four-question ADR threshold need an ADR. RFCs that were rejected, withdrawn, or that covered tactical design choices don't necessarily produce ADRs. The ADR practice's quality depends on selectivity; making every RFC produce an ADR floods the decisions directory with noise.

Format note: the RFC template vs the ADR template

There is no universally standardized RFC format for engineering teams the way there is for ADRs (Nygard, MADR, arc42). Most teams use something like:

# RFC-NNN: [Proposed change or feature]

**Author:** [Name]
**Created:** [Date]
**Status:** DRAFT | OPEN | ACCEPTED | REJECTED | WITHDRAWN
**Decision:** [leave blank until decision is reached]

## Problem
[What problem is this solving?]

## Proposed solution
[The recommended approach, with enough detail to evaluate it]

## Alternatives considered
[Other approaches evaluated; why they were not recommended]

## Open questions
[What remains unclear or contested; where reviewers should focus]

## Decision rationale
[Filled in when closed: why the final decision went the way it did]

Compare with the Nygard ADR template:

# ADR-NNNN: [Decision statement title — past-tense action, e.g. "Use Kafka for the event bus"]

## Status
Accepted

## Context
[The constraints, organizational pressures, and background that made this decision necessary]

## Decision
[What was decided, in authoritative terms]

## Consequences
[Upsides and downsides of the decision as implemented]

The structural difference reflects the functional difference: the RFC template has "Proposed solution" (uncertain, open to revision) and "Open questions" (signaling that review is requested). The ADR template has "Context" (retrospective framing), "Decision" (authoritative, not proposed), and "Consequences" (stating trade-offs as facts about the chosen path, not as questions about it).

How WhyChose fits in

When a significant decision is being explored with AI assistance — thinking through trade-offs in a Claude or ChatGPT conversation — that conversation is the pre-RFC deliberation. It contains the alternatives considered, the constraints that ruled them out, and the reasoning that led to a preliminary recommendation. That reasoning is exactly what the RFC's "Alternatives considered" section and the ADR's "Context" section need.

The WhyChose extractor surfaces decision-shaped conversations from your ChatGPT or Claude export, recovering that reasoning even when the conversation happened months ago. For the RFC → ADR handoff, the extractor output maps directly: the AI chat where the approach was worked through provides the raw material for the RFC's recommended approach and the ADR's Context section. The result is a more accurate Context than memory reconstruction alone — especially for retrospective ADRs being written long after the decision was implemented.

Get early access