ADR vs RFC

Software teams make decisions every week, yet few teams preserve the reasoning behind them. As your company grows, context fades, people leave, and new engineers question old choices. Debates restart because no one can point to a clear record. Architecture begins to drift, not because the team lacks skill, but because it lacks memory. If you want stability and speed at the same time, you need a simple system that captures both exploration and commitment.

When to Use an RFC and When to Use an ADR

A Request for Comments documents a proposal before you commit. You write an RFC when a decision is still open, when several options exist, or when the impact spans multiple teams. It defines the problem, outlines constraints, compares approaches, and surfaces risks. The goal is focused feedback and alignment before you move forward. An Architecture Decision Record serves a different role. You write an ADR after you make a meaningful architectural choice. It captures the context, the alternatives you considered, and the reasoning behind the final decision. The difference is clear. An RFC explores a decision. An ADR records a decision. Keeping that boundary sharp prevents confusion about what is still under discussion and what is final.

Build a Searchable Decision Artifact Map

Treat RFCs and ADRs as parts of one decision artifact map. RFCs cover exploration. ADRs capture commitment. Store both in the same repository as your code so they stay close to the system they describe. Use consistent titles, clear dates, and named owners. Link ADRs to the RFCs that informed them, and mark outdated decisions when they no longer apply. Keep each document focused on one topic so it remains easy to search and scan. This discipline reduces repeated debates, improves onboarding, and gives leadership clear visibility into technical tradeoffs. If you cannot explain why your last major technical decisions were made without guessing, start documenting them now.

No time or resources to build it yourself? Check Moai and see how it can help your engineers.

Geert P. Thiemens
The Moai team