The RFC and ADR: Structured Async Decision-Making

An RFC (Request for Comments) is a written document that proposes a change, explains the reasoning, and invites structured feedback before a decision is made. An ADR (Architecture Decision Record) is the permanent record of a decision that was made, including the context and the alternatives that were rejected.

Together, these two formats replace the majority of architectural meetings in a mature async organization.

Anatomy of an RFC

A good RFC has five sections:

1. Problem Statement: What is the current situation, and why is it insufficient? Be specific. Link to incidents, metrics, or tickets that demonstrate the problem.
2. Proposed Solution: What are you recommending? Describe it in enough detail that someone unfamiliar with the system can evaluate it.
3. Alternatives Considered: What else did you consider, and why did you reject it? This is the most important section — it shows you thought rigorously and prevents reviewers from suggesting options you already evaluated.
4. Trade-offs and Risks: What does this approach cost? What could go wrong? What are the operational implications?
5. Decision Requested: What specific approval or feedback do you need, and by when?

The deadline in section 5 is critical. Without it, RFCs sit unread. A good pattern: "Please comment by EOD Friday. If I receive no objections, I will proceed with the proposed approach on Monday."

Anatomy of an ADR

An ADR is written after a decision is made. It is short — typically one page — and answers three questions:

1. What was decided? State the decision in one sentence.
2. Why was it decided? Summarize the context and the winning argument.
3. What was rejected and why? List the alternatives and the reason each was ruled out.

ADRs are stored in the repository alongside the code they affect, typically in a directory called docs/decisions/ or adr/. They are numbered sequentially: ADR-001-use-postgres.md, ADR-002-migrate-to-redis-sessions.md.

docs/
  decisions/
    ADR-001-use-postgres-for-primary-store.md
    ADR-002-adopt-github-actions-for-ci.md
    ADR-003-reject-graphql-use-rest.md

When a new engineer joins and asks "Why are we using REST instead of GraphQL?", the answer is not "Ask Sarah" — it is "Read ADR-003."