Technical Decision Making: RFCs and ADRs
Technical decisions have long-term consequences. RFC (Request for Comments) and ADR (Architecture Decision Record) processes make decisions collaborative and well-documented.
Why We Need Process Without process, technical decisions are made in Slack, meetings, or worst—unilaterally by whoever writes code first. This leads to: inconsistent architectures, repeated debates, context loss when people leave.
RFC: Request for Comments RFCs are proposals for significant technical changes: new services, architecture changes, tool selections, major refactors.
When to write an RFC: Changes affecting multiple teams, decisions with long-term impact, expensive mistakes if wrong, need consensus from senior engineers. When NOT to write an RFC: Small changes, well-established patterns, urgent fixes.
RFC Structure Title: Brief description (e.g., "Move from REST to GraphQL") Problem: What's wrong with current state? Quantify with data. Proposal: Detailed solution with diagrams, code examples, migration plan. Alternatives: Other options considered and why rejected. Open Questions: What don't we know yet? Timeline: Phased rollout with milestones.
RFC Process 1. Author writes RFC, shares draft with close collaborators 2. RFC posted to team channel, comment period opens (1-2 weeks) 3. Author addresses all feedback, updates RFC 4. Team meeting discussion, aim for consensus 5. Engineering lead makes final decision if needed 6. RFC marked "Accepted" or "Rejected" with reasoning
ADR: Architecture Decision Record ADRs document decisions after they're made. They're lightweight—just a few paragraphs.
ADR Template: Title: Use PostgreSQL for user datastore Status: Accepted (or Proposed, Deprecated, Superseded) Context: We need persistent storage for 100K users with complex queries. Decision: We will use PostgreSQL instead of MongoDB. Consequences: Pros: ACID guarantees, powerful queries. Cons: Harder horizontal scaling than NoSQL. Date: 2026-01-06
ADR vs RFC RFCs are for big, contentious decisions requiring consensus. ADRs document smaller decisions or finalize RFC outcomes. Store ADRs in Git (docs/adr/ directory). Number them sequentially: 001-postgres-for-users.md.
Benefits Knowledge retention: New engineers read RFCs/ADRs to understand why systems are built this way. Avoid repeated debates: "We discussed this in RFC-023." Better decisions: Multiple perspectives catch blind spots. Accountability: Decisions have clear owners and reasoning.
Common Pitfalls Don't make RFC process too heavyweight. If writing an RFC takes longer than implementing the change, nobody will use it. Don't let RFCs become rubber stamps. If feedback isn't incorporated, trust erodes. Don't let perfect be the enemy of good. Accept RFCs with "we'll figure out X during implementation" if X isn't critical.
Example: Microservices vs Monolith We wrote RFC-047: Migrate to Microservices. Proposal outlined breaking monolith into 12 services. Feedback raised concerns: operational complexity, team too small (5 engineers). Alternative proposed: modular monolith with clear service boundaries, split later if needed. After discussion, we rejected microservices, accepted modular monolith. ADR-047 documents the decision. Two years later, monolith is still working great. RFC process saved us from premature optimization. RFCs and ADRs slow down decisions slightly, but prevent much larger slowdowns from bad decisions.