RFC (Request for Comments) / Design Documents

Overview

An RFC (Request for Comments) is a design document that proposes a significant technical change and solicits structured feedback from the team before a decision is made. Unlike an ADR, which records a decision already taken, an RFC is a proposal -- it invites discussion, critique, and refinement.

RFCs are the primary mechanism for making large-scale technical decisions collaboratively. They ensure that significant changes are well-thought-out, that alternatives are considered, and that the team has an opportunity to surface concerns before implementation begins.

When to Write an RFC

Write an RFC when:

• A change affects multiple teams, services, or systems
• The implementation will take more than a few days of effort
• There are multiple viable approaches and the trade-offs are not obvious
• The change introduces new infrastructure, frameworks, or patterns
• You need buy-in from stakeholders outside your immediate team
• The decision is hard to reverse once implemented