👋 Hey {{first_name|there}},
Your team keeps rebuilding things that already worked because nobody captured why they were built that way. One strict template fixes that.
Why this matters / where it hurts
Someone opens a service. They find a caching layer bolted onto a synchronous write path and ask the obvious question: "Why did we build it this way?"
Silence.
The person who made that call left eight months ago. The Slack thread is buried in a channel that got renamed twice. The design doc, if it ever existed, runs forty pages long, loaded with alternatives nobody evaluated and diagrams nobody updated. It is, for all practical purposes, invisible. So the team guesses. They rewrite. And sometimes, with painful irony, they rewrite it back to exactly the thing that failed before, because nobody documented why it failed in the first place.
I've watched this happen more than I'd like to admit. Entire sprints burned rebuilding something that was deliberately chosen for good, defensible reasons. Gone. Not because people were careless, but because the reasoning lived in one person's head and walked out the door with them.
In Lesson #39 on bulkhead architecture, we talked about keeping failures contained. ADRs apply the same instinct to decisions: isolate the reasoning, make it findable, stop one departure from cascading confusion across the org.
🧭 Mindset shift
From: "We'll remember why we chose this."
To: "If it's not written in one page, the decision doesn't exist."
Most teams swing between two extremes. They write nothing. Or they write everything. The forty-page design doc with seven appendices is a write-only artifact. People create it, file it, and never open it again. Meanwhile, the real reasoning drifts through hallway conversations and Slack threads that expire from memory in weeks.
The fix isn't more documentation. It's a smaller, stricter container. One page. Five sections. Fifteen minutes to read. If you can't explain the decision in that space, you probably haven't finished thinking it through yet, and that realization alone is worth the exercise.
Every architecture-level decision gets an ADR before implementation begins. No exceptions for "obvious" choices, because obvious today is mysterious in six months.
If the ADR takes more than fifteen minutes to read, split it or cut it. Brevity is a forcing function for clarity, not a shortcut around it.
ADRs are append-only. Never edit old ones. Supersede them with a new record that links back. The trail of why things changed is the entire point.