🤝 Writing RFCs and Architectural Proposals

A Perspective on Scaling Decisions through Documentation

For a Programmer, an RFC is not just a document; it is a consensus-building engine. Writing a proposal allows you to “code in the large,” influencing the direction of the entire department by clarifying thought processes, exposing hidden risks, and inviting collective ownership of the solution.

1. The Mindset: Asynchronous Alignment

A Programmer uses written proposals to move away from high-friction, low-context meetings.

Clarity of Thought: If you cannot explain the architecture in writing, you do not understand it well enough to build it yet.
Democratic Innovation: RFCs allow everyone—from juniors to specialists—to provide feedback on their own schedule, reducing the “loudest voice in the room” bias.
Historical Context: Five years from now, your RFC will explain why a specific trade-off was made, preventing “Gervais Principle” cycles where teams revert to old, failed patterns.

2. The Anatomy of a High-Impact RFC

A great proposal should follow a standard structure to ensure no critical angle is missed:

A. The Summary & Context

Abstract: A one-paragraph “TL;DR” of the proposal.
Problem Statement: What pain point are we solving? Use data (latency, error rates, developer hours lost) to justify the effort.

B. Proposed Architecture

The “Happy Path”: High-level overview of the new system.
Visual Models: Use C4 diagrams or sequence diagrams to simplify complex mental models.

C. Trade-offs and Alternatives

The “Why Not”: List at least two other solutions you considered and exactly why they were rejected (e.g., cost, complexity, lack of ecosystem support).
Consequences: What are we giving up? (e.g., “This improves read speed but increases write latency”).

D. Cross-Cutting Concerns

Observability: How will we monitor this in production?.
Security: How does this impact our data privacy or attack surface?.
Rollout Strategy: How do we move from the old way to the new way without downtime?.

3. The Lifecycle of an RFC

The Draft: Write the initial proposal and share it with a “inner circle” of trusted peers to catch obvious flaws.
The Review Period: Open the document to the wider team. As a Senior, your role here is to facilitate, not defend. Respond to every comment with curiosity.
The Decision: Move the RFC to “Approved,” “Rejected,” or “Withdrawn.”
The ADR: Once the direction is set, create an Architecture Decision Record (ADR) that points back to the RFC for deep context.

4. Techniques for RFC Writing

Steel-manning Objections: Anticipate the strongest arguments against your proposal and address them directly in the text.
The “One-Way Door” Test: Clearly state if this is a Type 1 (hard to reverse) or Type 2 (easy to reverse) decision. Focus the team’s energy on the Type 1 aspects.
Scope Guarding: If the discussion drifts into minor implementation details (bike-shedding), steer it back to high-level architectural contracts.

5. Checklist for Proposals

Accessibility: Is the document readable by a mid-level engineer without 30 minutes of background explanation?
Definition of Success: Does the RFC include clear metrics for how we will measure if this was a good idea?
Infrastructure Impact: Have we estimated the “cloud tax” or operational overhead of this new system?
Documentation: If approved, is there a plan to update our “Documentation as Code” living knowledge base?

“The code is the implementation; the RFC is the soul of the system. One tells the computer what to do; the other tells the engineers why it matters.”