The 15-Minute ADR With Decisions That Actually Survive

👋 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.

🧰Tool of the week: The 1-Page ADR Template

ADR Template: capture any architecture decision in 15 minutes

Title and number - Use a sequential ID and a short descriptive title. "ADR-0047: Use Redis for session caching." Not "Caching discussion." Searchability matters.
Status - One of four values: Proposed, Accepted, Superseded, Deprecated. Nothing else. Keep it machine-scannable so you can grep your decision history.
Date and author - Who proposed it, when? This feels trivial until you're reading the record eighteen months later, and context depends entirely on knowing what the system looked like at that moment.
Context - Three to five sentences, no more. What problem triggered this? What constraints exist? Include traffic or scale numbers if they shaped the decision. Strip everything else.
Decision - State the choice in one sentence. Then two to four sentences on high-level implementation. No deep design. Just enough to be unambiguous.
Alternatives considered - Two or three options you rejected, one sentence each on why. This is the section teams skip most often and regret most deeply. Future-you needs to know what was ruled out.
Consequences (good) - Two to three bullets. What improves? Latency drops, coupling decreases, on-call burden shrinks. Be specific. Vague benefits are the same as no benefits.
Consequences (bad) - Two to three bullets. What gets worse? Operational complexity, new failure modes, steeper learning curve. Honest ADRs list real costs. Dishonest ones get ignored.
Review and approval - Name the roles that sign off. Tech lead, domain owner, SRE on-call. Not "the team." Forty-eight hours is a good default review window.
Supersedes / superseded by - Link to any prior ADR this replaces. Leave blank for first-time decisions. This single field turns a pile of disconnected documents into a navigable decision trail.

🔍 In practice: Switching from polling to webhooks

Scenario: The notification delivery pipeline polls an external provider API every 30 seconds. The provider now supports webhooks. The team needs to decide whether to switch.

Scope: Notification delivery only. User-facing preferences and routing logic are out of scope.
Context: Three-person team, 2.8M unnecessary API calls per day, P95 delivery latency at 28 seconds.
ADR-0023 drafted. Title: "Replace polling with inbound webhooks for notification delivery." Status: Proposed.
Decision, one sentence: Accept inbound webhooks, verify HMAC signatures on every payload, deprecate the polling worker within 30 days.
Alternatives documented. Increase polling to every 5 seconds: rejected, provider rate limits cap at 100 req/s and spikes would breach them. Switch providers entirely: rejected, 6+ week migration cost against 99.97% current reliability.
Good consequences: Latency drops from 28 seconds to under 2. API volume falls by ~95%. The polling worker, a persistent source of on-call alerts, disappears.
Bad consequences: New inbound endpoint becomes a security surface. Webhook delivery failures need a fallback, likely a lightweight polling backup on a 5-minute interval.
The tradeoff we accepted: The team wanted to skip "alternatives considered" because webhooks felt obvious. Three months later, a new engineer proposed increasing polling frequency. The ADR answered the question before it became a meeting. That one paragraph saved an hour of debate and a week of wasted prototyping.
Result: ADR reviewed and accepted within 36 hours. Delivery latency dropped 93%. Zero re-litigation of the decision since.

✅ Do this / ❌ Avoid this

Do this:

Store ADRs in the repo next to the code they describe. A /docs/adr/ folder with numbered markdown files works. Not a wiki nobody visits.
Write "Consequences (bad)" first. Starting with costs forces honesty, and honesty improves the decision itself before you ship it.
Link every ADR from the pull request that implements it. Decision and execution should never live in separate worlds.

Avoid this:

Treating ADRs as design docs. The moment you add class diagrams and sequence flows, you've crossed a line. ADRs capture decisions, not designs.
Editing old ADRs to match the current reality. Supersede them instead. The history of change is the entire value.
Letting proposals rot. If an ADR sits in "Proposed" for more than a week, escalate or withdraw. Stale proposals erode trust faster than having no process at all.

🧪 Mini challenge

Goal: Write your first real ADR in fifteen minutes flat.

Pick one architecture decision from the last three months that has no written record. The stranger it looks to newcomers, the better.
Open a blank Markdown file. Paste the 10-item template from this issue. Set a 15-minute timer.
Fill every section. If you freeze on "Alternatives considered," ask a teammate what else was on the table. That conversation is usually the most valuable part.
When the timer rings, stop. Read it back. If a new hire could understand the decision and why the alternatives lost, you're done. Commit it as docs/adr/ADR-0001.md.

Try it, hit reply, and tell me what you found.

🎯 This week's move

Create /docs/adr/ in your primary service repo with a short README linking to this issue's template.
Identify the three most "mysterious" decisions in your current system. The ones where every new hire asks, "Why is it like this?" Those are your first ADR candidates.
Write one retroactive ADR for a past decision. It'll be imperfect. Partial context committed to the repo beats perfect context locked in someone's memory.
Add an ADR checkbox to your PR template or architecture review checklist. Default, not suggestion.

By the end of this week, aim to: have 1 committed ADR in your repo and a team agreement on when future decisions deserve one.

👋 Wrapping up

Architecture decisions have a half-life. If you don't capture the reasoning within a week, it's gone. Permanently.
The best ADR is one page long, honest about what it costs, and stored next to the code it explains.
Brevity isn't laziness. If fifteen minutes can't capture the decision, the decision isn't clear yet.

Know a dev who's trying to level up? Forward this issue to them.

One question for you: What's the oldest "why did we build it this way?" mystery still lurking on your team? Hit reply and tell me in one sentence.

If you’re new here, these are the five issues readers keep coming back to:

Thanks for reading.

See you next week,
Bogdan Colța
Tech Architect Insights