RFCs as decision records

A Request for Comments document is a proposal: problem, options, recommendation, and open questions. Done well, it aligns the team and leaves a clear record of why decisions were made.

Structure that works

1. Title and status: e.g. “RFC-042: Migrate auth to OIDC” with status (Draft, Accepted, Superseded).
2. Context: What problem are we solving? What constraints exist?
3. Options: List 2–4 alternatives with pros and cons. Include "do nothing" when relevant.
4. Recommendation: Which option and why? What’s the migration path?
5. Open questions: What still needs answers? Who decides?
6. Appendix: Links, diagrams, or detailed analysis that would clutter the main text.

Writing tips

• Keep the main body short (1–3 pages). Move details to appendices.
• Use concrete examples and, if possible, proof-of-concept results.
• Call out risks and mitigations explicitly.
• Set a review deadline and decision owner so RFCs don’t linger.

When to write one

Use RFCs for cross-team or high-impact changes: new services, schema changes, deprecations, or architectural shifts. Skip them for small, reversible changes where a short discussion or ticket is enough. Bottom line: A good RFC makes the problem and the chosen solution obvious to someone reading it six months later.