RFCs vs ADRs: When to Use Which

Two of the most useful tools for documenting technical decisions are RFCs (Requests for Comments) and ADRs (Architecture Decision Records). They're often mentioned interchangeably, and some teams mash them together into a single process. But they solve different problems, and understanding the distinction helps you apply each one where it's most useful.

ADRs: The Decision Log

Michael Nygard proposed Architecture Decision Records in a 2011 blog post titled "Documenting Architecture Decisions." His motivation was straightforward: significant architectural decisions were getting lost. Teams would make choices about frameworks, data stores, communication patterns, and deployment strategies — then forget why six months later.

An ADR captures a single decision. The format Nygard proposed is deliberately minimal:

Title — A short noun phrase describing the decision. Status — Proposed, accepted, deprecated, superseded. Context — What situation prompted this decision? What constraints or forces are in play? Decision — What did you decide? Consequences — What are the expected results, both positive and negative?

That's the whole thing. An ADR for choosing PostgreSQL over MySQL might be 15 lines. An ADR for deciding to deploy on Kubernetes instead of bare EC2 instances might be 30.

The key properties of ADRs are:

One decision per record. An ADR doesn't try to cover your entire architecture. It covers one choice. "Use gRPC for internal service communication." "Store user sessions in Redis." "Adopt the strangler fig pattern for the legacy migration."

Immutable once accepted. You don't go back and edit an ADR when circumstances change. If you reverse or modify a decision, you write a new ADR that supersedes the old one. This preserves your decision timeline — you can see what you decided, when, and what replaced it later.

Lightweight by design. An ADR should take 10 to 20 minutes to write. If it's taking longer, the scope is probably too large for a single record.

Retrospective-friendly. ADRs can be written after the fact. If you made a decision last month and didn't document it, you can still write an ADR capturing the reasoning. It's not ideal, but it's better than nothing.

Teams that use ADRs well typically store them in a docs/adr/ or docs/decisions/ directory in their repository. They're numbered sequentially — 001-use-postgresql.md, 002-adopt-grpc.md — so the chronological order is obvious.

RFCs: The Proposal and Discussion

RFCs serve a different purpose. Where an ADR records a decision, an RFC proposes one and solicits feedback before it's finalized.

An RFC is typically a longer document — one to five pages — that includes a detailed problem description, a proposed solution, alternatives considered, trade-offs, and open questions. It's designed to be reviewed and discussed. Comments, objections, and counter-proposals are expected and welcome.

The key properties of RFCs are:

Discussion-oriented. The whole point is to get feedback. An RFC isn't handed down from above — it's put forward as a starting point for conversation. The document often changes significantly during review.

Mutable during review. Unlike ADRs, RFCs are revised as feedback comes in. The author updates the proposal, addresses comments, and refines the design. The final version represents the outcome of the discussion, not just one person's initial thinking.

Heavier process. An RFC takes hours to write, not minutes. It includes sections like Motivation, Detailed Design, Alternatives Considered, and Migration Plan. This weight is deliberate — it forces the author to think deeply before proposing a change.

Pre-decision. An RFC exists to help the team make a decision. Once the decision is made, the RFC becomes a historical record of the discussion that led to it.

The Rust programming language's RFC process is a well-known public example. When someone wants to change the language — add a feature, deprecate syntax, modify the standard library — they submit an RFC to the rust-lang/rfcs repository. The community discusses it, the RFC is revised, and eventually a core team member makes a decision to merge or close it. The React framework follows a similar public process for significant features.

The Practical Differences

Here's where it gets concrete. Consider these two scenarios:

Scenario A: Your team needs to decide whether to use UUIDs or auto-incrementing integers for primary keys in a new service. The trade-offs are well-understood. There's not much to debate — it's a matter of picking a convention and sticking with it.

This is an ADR. Write down the context (new service, need a PK strategy), the decision (UUIDs for portability and merge safety), and the consequences (larger index size, no natural ordering). Done in 15 minutes.

Scenario B: Your team is considering breaking a monolithic API into three services. This affects deployment, data ownership, inter-service communication, error handling, testing strategy, and on-call rotations. Multiple engineers have strong opinions, and the wrong choice will be expensive to reverse.

This is an RFC. You need a detailed proposal, you need to consider alternatives (what about just modularizing the monolith?), you need a migration plan, and you need input from the teams that will be affected. This takes hours to write and days to review. That investment is appropriate for the stakes involved.

When to Use Which

A simple heuristic:

Use an ADR when:

The decision is relatively contained — it affects one service or one team
The trade-offs are well-understood and don't require extensive analysis
You need to record what was decided and why, but don't need a long discussion phase
The decision is already made and you're capturing it retroactively
Examples: choice of database, logging framework, API versioning strategy, coding conventions

Use an RFC when:

The change is cross-cutting — it affects multiple teams or systems
The trade-offs are complex and require analysis to evaluate
You expect disagreement or multiple valid approaches
The change is expensive or impossible to reverse
You need buy-in from people outside your immediate team
Examples: service decomposition, new authentication architecture, data pipeline redesign, public API redesign

The gray zone: Some decisions fall in between. A mid-size refactoring that affects two teams might warrant either format. When in doubt, consider the audience. If you need feedback from people who aren't already in the loop, lean toward an RFC. If the people affected are already aligned and you just need to document the outcome, an ADR is sufficient.

They're Complementary

The best teams use both. Here's how they fit together:

An RFC drives the discussion for a major decision. The team reviews, debates, and refines the proposal. Once accepted, the RFC becomes a historical document — it records the discussion, the alternatives, and the reasoning.

But an RFC often involves multiple smaller decisions along the way. During the implementation of an RFC to decompose a monolith, you might make decisions about: which message broker to use, how to handle distributed transactions, what monitoring to add, how to structure the new repositories. Each of those can be captured as an ADR.

So the pattern looks like:

RFC — "Decompose the order service into three services" (reviewed, discussed, accepted)
ADR — "Use NATS for inter-service messaging" (decided during implementation)
ADR — "Use the saga pattern for multi-service transactions" (decided during implementation)
ADR — "Deploy new services to the existing Kubernetes cluster" (decided during implementation)

The RFC provides the strategic direction. The ADRs capture the tactical decisions made along the way. Together, they give a complete picture of what was decided and why — at every level of granularity.

Avoiding Common Traps

Don't force everything into one format. If your team only has RFCs, small decisions won't get documented because the overhead is too high. If your team only has ADRs, big decisions won't get adequate discussion because the format is too constrained.

Don't let process kill momentum. The point of both formats is to improve decision-making, not to slow it down. If writing a document feels like a bureaucratic gate rather than a thinking tool, the process needs adjustment. Keep ADRs short. Keep RFC review cycles bounded — a week or two, not months.

Don't skip the "why." This applies to both formats. The most common failure mode is documenting what was decided without explaining why. "We chose PostgreSQL" is useless without context. "We chose PostgreSQL because we need strong transactional guarantees for our payment processing pipeline, and our team has deep operational experience with it" is a decision that future engineers can evaluate and potentially reconsider when the context changes.

Start somewhere. If you have neither ADRs nor RFCs today, start with ADRs. They're lower friction, quicker to adopt, and immediately useful. Once the habit of writing things down is established, introduce RFCs for the bigger decisions that need a discussion phase. You don't need to adopt both on the same day.