ADRs: The Missing Piece

You’ve been there. You open up some ancient service or a crusty module, look at the weird workaround someone implemented, and think:

“Why the hell did they do that?”

Then you Slack someone senior — they left the company two years ago. The Jira ticket? Long closed. Confluence? Rotting. Now you're left reverse-engineering context from Git diffs and guesswork.

That’s where ADRs come in.
And no, it's not a buzzword or yet another document no one reads. Done right, ADRs are your engineering team’s collective memory.

What the Heck Are ADRs?

Architectural Decision Records (ADRs) are just small, version-controlled text files that explain why a technical decision was made.

They’re not about “how” code works — your codebase already does that (hopefully).
They’re about why you made certain architectural decisions, especially the kind that:

• Took days of discussions
• Had multiple options on the table
• Introduced tradeoffs or constraints
• Are not obvious by just looking at the code

Basically: anything future-you (or someone else) would want to know before undoing it or scratching their head wondering what went wrong.

Why Should You Bother?

Because without them, you’re rewriting history with every onboarding.
Because no matter how senior or smart you are, you won’t remember why you chose that pattern over another in 6 months.

Here’s what ADRs really buy you:

• Context: What was happening in the org/codebase at the time?
• Rationale: What trade-offs were considered? What was ruled out and why?
• Clarity: What are the consequences? Are we locked into something?
• Documentation that actually lives with code, not in some dead wiki.

And here’s the best part: it takes less than 15 minutes to write one after a big decision.

🧠 How Do You Use Them?

Simple:

1. Create a folder in your repo:
   docs/adr or just adr/
2. Write a new markdown file for each decision:
   Name it something like:
   0001-use-event-driven-instead-of-rest.md
3. Use a simple format, like:

# ADR 0001: Use Event-Driven Architecture Instead of REST

Date: 2024-07-23

## Status
Accepted

## Context
We need a way for services to communicate asynchronously. Our system will handle bursty traffic and user events that can trigger downstream workflows.

## Decision
We’ll use Kafka to enable asynchronous, event-driven flows between services. This gives us loose coupling, retries, and better scaling for read models.

## Consequences
- Services will need to manage Kafka producers/consumers.
- Event schemas will need to be versioned and documented.
- We gain decoupling, but debugging flows might be harder.

4. Version it with your codebase. So when someone checks out a branch or reviews a PR, they can read why the decision was made.

When to Write an ADR?

You don’t need one for every CSS tweak or minor refactor. Use ADRs when:

• You change the way services talk to each other
• You pick a new library/framework/tool
• You shift deployment strategy (e.g. move from ECS to K8s)
• You change your DB schema strategy (e.g. soft deletes vs hard deletes)
• You go from REST to GraphQL or async messaging

Basically, if people in the future will ask "Why this and not that?", it’s ADR time.

Tools That Help (But Aren’t Mandatory)

• adr-tools: CLI to generate and manage ADRs
• Just use Markdown + Git — no need for anything fancy
• Add ADR reviews as part of your PR process or architecture meetings

⚠️ Don’t Let This Happen

Dev 1: “Why did we avoid PostgreSQL logical replication?”
Dev 2: “Uh… I think someone said something about audit issues, maybe?”
Dev 3: googles aimlessly, gives up, implements it anyway… breaks stuff

If you’ve ever experienced this, you already know: ADRs aren’t overhead, they’re insurance.

Final Thoughts

We spend so much time on linters, formatters, testing, and logging — but we ignore the biggest bottleneck in a codebase: human understanding.

ADRs give your team a second brain. One that doesn’t forget. One that speaks in plain English. And one that helps you move faster without tripping over old landmines.

You don’t need a wiki.
You don’t need consensus on format.
You just need to start.

Thinking of writing one already? Do it. Your future team will thank you.

Also... I’ve mentioned tradeoffs and decision-making here a lot.
Next time, maybe we talk about how to make better technical decisions in messy, real-world environments.

Stay tuned.