RFC and ADR (Decision Logs): The Practical Guide to Never Again Saying "Who Decided This?"

Have you ever looked at a piece of code and wondered: "Why on earth did they choose this technology?". Usually, the person who made the decision has already left the company, the context is lost, and the architecture becomes an "archaeological mystery."

I've been learning that documentation doesn't have to be a bureaucratic burden. Instead, it should be the backbone of a high-performing team. I want to share how you can structure technical decisions using RFCs and Decision Logs to stop having the same debates every six months.

---

1. The Problem: "Collective Amnesia"

Every software team eventually suffers from:

• Slow Onboarding: Architecture only exists in the veterans' heads.
• Infinite Meetings: The same technical debate resurfaces every sprint because the decision was never recorded.
• Hallway Decisions: Two people agree on something over coffee, and the rest of the team only finds out when the deploy breaks.

---

2. Where did this come from? (It's not just a "trend")

The idea of documenting decisions is as old as the internet itself:

RFC (Request for Comments): Created in 1969 by Steve Crocker for ARPANET. The name was chosen to be humble: it wasn’t an order; it was a "request for comments."

ADR (Architecture Decision Record): Proposed in 2011 by Michael Nygard. He suggested recording technical decisions in short, versioned files right inside the Git repository.

What’s the difference?

RFC (The "Before"): Focused on Collaboration. You propose an idea to get feedback and find flaws before writing the first line of code.

Decision Log / ADR (The "After"): Focused on Record-keeping. It is the official answer to: "What did we decide and why?"

---

3. ADR vs. Decision Log: Protecting the Whole Project

A common mistake is thinking that documentation is only for "code stuff." To build a great product, we need to protect the memory of the entire project.

The Definition:

ADR (Architecture Decision Record): Focused on the "How". These are deep technical decisions (e.g., migrating from REST to GraphQL, choosing a caching strategy).

Decision Log: Focused on the "What/Why". These are** critical project or business decisions** (e.g., postponing a feature, changing a release date, or deciding NOT to use microservices due to cost).

"While ADRs protect your code's integrity, Decision Logs protect your project's history."

---

4. The Practical Workflow 🚀

The golden rule is: stay close to the code. Don't use complex external tools. Use Markdown and Git.

1. Draft the Proposal: Write a simple .md file.
2. Open a Pull Request: The team discusses the proposal right there, line by line.
3. Finalize: If approved, it becomes an official record. If rejected, it stays archived as a valuable "lesson learned."

---

5. Complete Markdown Examples

Example A: The Proposed RFC (The Discussion Phase)

This is the document used to gather feedback.

# RFC 001: Implementing Redis Cache for Product API

**Status:** Under Review ⏳
**Date:** 2026-01-29
**Author:** [Your Name]

## 1. Context and Problem
Currently, our product API queries the main database on every request. With increasing traffic, we've noticed:
* Average latency has risen to **1.2s**.
* Database is hitting **90% CPU usage** during peak hours.
* Static data (names/descriptions) is being queried redundantly thousands of times.

## 2. Proposal: Introduce a Cache Layer
We propose using **Redis** to store product query results for a 1-hour period (TTL).

### Expected Benefits:
* Reduce latency to under **100ms** for cached data.
* Relieve load on the primary database.

## 3. Alternatives Considered
* **Memcached:** Discarded; we need basic persistence and future support for complex data structures.
* **In-Memory Cache:** Discarded; running multiple containers would lead to cache inconsistency between instances.

## 4. Risks and Impacts
* **Inconsistency:** Cache may be stale for up to 1h (will require a future invalidation strategy).
* **Cost:** New infrastructure service (AWS ElastiCache).

## 5. Implementation Plan
1. Configure Redis in Staging.
2. Implement **Cache-Aside** pattern in the product service.
3. Monitor Hit/Miss metrics via Dashboard.

Example B: The Rejected RFC (The Filter in Action)

This saved the team weeks of wasted effort on a migration they couldn't sustain.

# RFC 002: Monolith to Microservices Migration

**Status:** REJECTED ❌
**Date:** 2026-01-29
**Author:** Enthusiastic Dev

## 1. Proposal
Break our current application into 5 independent microservices (Users, Orders, Products, Payments, Notifications).

## 2. Reason for Rejection
* **Excessive Complexity:** We are only 3 developers. Managing 5 infrastructures would create unsustainable overhead.
* **Cost:** Cloud costs would triple without a clear ROI.
* **Premature Optimization:** The monolith handles load well; our main issue was solved by **RFC 001 (Redis)**.

**Conclusion:** We will reassess once the team size doubles.

Example C: The Approved Decision Log (The Final Record)

This is the "Source of Truth" that will live in the repository forever.

# ADR 001: Implementation of Redis for Caching

**Status:** Approved ✅
**Date:** 2026-01-29
**Deciders:** Engineering Team

## Context
Faced with 90% DB CPU peaks and 1s+ latency, we needed a solution to reduce load without a full database rewrite.

## Decision
We decided to implement **Redis** as a distributed cache layer.
* Pattern: **Cache-Aside**.
* TTL: **60 minutes**.
* Infra: Managed via AWS ElastiCache.

## Consequences
* **Positive:** Immediate latency drop to ~80ms. 60% load reduction on DB.
* **Negative:** New point of failure in architecture. Requires memory monitoring.
* **Risks:** Data may be slightly stale for up to 1h.

---
*Reference: Based on the discussion initiated in RFC 001.*

---

6. Why is this vital for small teams?

If you have many demands and little time, you might think documentation is a "waste of time." It’s actually the opposite:

• Avoids Rework: You don't discuss the same thing twice.
• Autonomy: New developers can read ADRs and understand the "why" without interrupting seniors.
• Scalability: When the team grows, the culture of documentation is already there.

Conclusion 🏁

Documentation is an act of empathy for your "future self" and your teammates. Industry leaders like Uber, Spotify, and GitLab use these processes to scale knowledge without losing agility.

I'm just starting to apply this, and the clarity in our technical discussions has improved immensely.

What about your team? How do you keep your technical memory alive? Let me know in the comments! 👇

---