Six months into a new job, you encounter a decision in the codebase that makes no sense. The library choice is odd, the architecture has a strange constraint nobody can explain, and the lead engineer who built it left a year ago. You spend two days investigating before someone in Slack vaguely remembers: “Oh, there was a whole debate about that. The old approach had a performance problem in production.” Two days gone, and you still don’t know exactly what the original problem was or what else was considered.

This is the problem that RFCs and ADRs solve. Not perfectly, but meaningfully.

What’s the Difference?

These two document types are often confused or used interchangeably. They’re related but serve different purposes.

An RFC (Request for Comments) is a proposal document, typically written before a significant technical decision is made. It describes a problem, proposes a solution, considers alternatives, and explicitly invites team feedback. The RFC process is the conversation — it’s how you make a technical decision collaboratively rather than in someone’s head.

An ADR (Architecture Decision Record) is a record of a decision that was made. It captures what was decided, why, what alternatives were considered, and what consequences flow from the decision. ADRs are typically short — one page is ideal — and written at the time of decision or shortly after.

You might write an RFC to propose adopting a new event streaming system, gather feedback, revise the proposal, and make a decision. You’d then write an ADR recording that decision, the key reasons, and the trade-offs accepted. The RFC is process; the ADR is record.

Some teams skip RFCs entirely and write ADRs for decisions made in meetings or Slack threads. That’s a reasonable approach for smaller teams with less complex decisions. Others use the RFC process for anything non-trivial and treat the accepted RFC as the ADR. Either works — what matters is having some written record of decisions and their rationale.

The Minimum Viable RFC

A good RFC doesn’t need to be long. The minimum that’s actually useful:

Problem statement — what specific problem are you solving? Be concrete. “We need better search” is not a problem statement. “Full-text search on the products table is timing out for queries with more than three words, affecting 15% of users who search with longer phrases” is.

Proposed solution — what are you proposing to do? Include enough technical detail that another engineer can evaluate it, but not so much that you’re writing the implementation docs before anyone’s agreed on the direction.

Alternatives considered — list at least two alternatives and explain briefly why you’re not proposing them. This shows you’ve thought it through and prevents “but why didn’t we just…” comments in review. It also helps future readers understand the decision space.

Trade-offs and risks — what are you giving up? What could go wrong? What are the dependencies or prerequisites?

Open questions — what decisions remain? What do you need feedback on specifically?

That’s it. If it takes you more than a day to write a useful RFC, it’s probably too long.

The ADR Format

The most widely used ADR format comes from Michael Nygard’s 2011 blog post, and it’s held up well. The core fields:

# ADR-0023: Migrate search to Elasticsearch

## Status
Accepted

## Context
Full-text product search is timing out for queries with 3+ words.
Current PostgreSQL ILIKE approach doesn't scale past ~500k products.
We've reached that threshold with the Q4 2025 catalogue expansion.

## Decision
Adopt Elasticsearch 8.x for product and content search,
keeping PostgreSQL for transactional data.

## Consequences
- Search latency for typical queries: ~20ms (down from 800ms+)
- Operational complexity: new infrastructure to maintain
- Index sync strategy needed between PostgreSQL and ES
- Estimated 2 engineer-weeks to implement initially

Status should be one of: Proposed, Accepted, Deprecated, Superseded. When a decision is later reversed or replaced, update the status and link to the superseding ADR — don’t delete the old one. The historical record of reversed decisions is often the most valuable part.

Where to Keep Them

The short answer: in the repository. ADRs that live outside the codebase get out of sync with the code, are harder to find at the right moment, and tend to quietly rot.

A standard approach is a docs/decisions/ or docs/adr/ folder at the repo root, with files named numerically: 0001-use-postgresql.md, 0023-adopt-elasticsearch.md. Tools like adr-tools automate the numbering and linking. Michael Bryzek and others have argued for keeping them alongside the code they’re related to (so a microservice’s ADRs live in that service’s repo), which makes more sense for monorepos or polyrepo organisations.

For RFCs, a separate repository or a shared notion/confluence space works fine — they’re more collaborative documents and benefit from commenting tools. Google Docs works. What doesn’t work is RFCs living in individual engineers’ files or Slack threads that get lost.

Getting Your Team to Actually Write Them

This is the harder part. Tooling is easy; process is cultural.

A few things that help: make the first ADR yourself. Write up a recent decision, keep it short, share it. Normalise the format. When someone proposes a change in a PR review and it’s significant, ask “should we ADR this?” rather than debating in comments. Link to ADRs from code — a comment saying // See docs/decisions/0023-elasticsearch.md for why we buffer writes is worth more than the ADR alone because it connects the decision to the code that implements it.

The friction of writing RFCs reduces significantly if you have a template. Put one in the repository so engineers don’t face a blank page. Keep the standard short enough that writing one takes an hour, not a day.

One honest note: not every decision warrants documentation. Choosing between two nearly-identical npm packages, picking a variable name, structuring a test file — these aren’t ADR territory. The heuristic is: would a new team member need to understand why this was decided to work effectively with it? If yes, write it down.

The compounding value of this practice only becomes apparent over time. Teams that have maintained ADRs for two or three years describe the repository as a genuine competitive advantage — onboarding is faster, regression discussions take minutes rather than hours, and the cost of maintaining and extending old systems drops measurably.