It's Like They Never Heard Me Say It

Verbal agreements evaporate the moment something breaks, and the developer who wrote nothing down ends up carrying the blame. What an ADR is, what it's for, how to structure one, and how to name it.

You start your day, walk into that blessed daily standup, and the same dialogue kicks off.

"Why was this done this way?"

(On your tenth frustrated attempt, you give the TL the same answer as always.)

"It was a decision we agreed on — the two of us and the architects."

(The TL plays dumb.)

"Whatever, it has to be done this other way."

(You stay quiet, staring, breathing to keep from losing it.)

"It's already done, but fine, whatever. I'll redo it."

The feature was about to ship when the time bomb went off: an unplanned refactor that pushed the delivery date back.

This isn't one specific incident in one specific place. It's a composite — part what I went through myself, part what other developers on other teams have told me. The details change; the pattern is what repeats.

#The developer took the hit

The only person who had any record of the conversation was the developer. The TL, conveniently, didn't recall a thing. The architects, who had given a verbal green light, pushed back as if they'd never said a word about it.

The developer absorbed the impact. And the blame: the team pointed at them "for doing it wrong."

#The verbal veto

The problem wasn't what was said — it's that it stayed just that: spoken, nothing more, never written down. Words get carried off by the wind, and whoever agrees to something out loud benefits from exactly that: nothing written down. Because when something goes wrong, that same person starts reshaping reality and tells a version that suits them.

Nobody approved anything. Nobody saw anything. Nobody proposed anything. The developer didn't follow what was agreed — they did, but that gets denied too.

In other words: without a record to contradict it, the last version of the story is the one that sticks — and that version gets written by whoever decided out loud, not by whoever carried out the decision.

#Why the people above you don't want it in writing

One day, exhausted, that developer proposed writing a document. Neither the TL nor the architects pushed for it — if anything, they blocked it.

You don't need to assume bad intent. It's simpler than that: the system doesn't reward whoever leaves a record, it rewards whoever keeps things ambiguous. A TL or an architect who decides out loud keeps the room to say "I never said that" if something goes wrong later. Their judgment stays protected — they never have to defend it in writing or answer for it when it fails. Meanwhile, the person left exposed is whoever executed the decision without anything signed.

That incentive protects the promotion of whoever decides verbally, and damages the one of whoever executes it and then takes the blame. It's not a conspiracy — it's what happens when the cost of a bad decision gets paid by someone else.

#This is exactly what ADRs are for

An ADR (Architecture Decision Record) is exactly what that developer needed: a short document that records an architectural decision — who made it, why, and what alternatives got ruled out.

It doesn't replace the conversation — the conversation still happens, in the daily, on the call, in the hallway. What the ADR does is make sure that, after that conversation, something survives that nobody can rewrite with Monday-morning hindsight.

The format I use is based on the one Michael Nygard popularized — I added the approval deadline myself, because in practice that's the part that saved me the most.

#How it's structured

# 0007. Use optimistic concurrency for inventory updates

## Status
Proposed — approval deadline: 2026-08-09 EOD. No response by then = approved.

## Decided by
- Jane Doe (Tech Lead)
- John Smith, Ana Torres (Architecture)
- You (author of this ADR)

## Context
What triggered this decision, what constraints existed, why it had to be resolved now.

## Options considered
| Option | Pros | Cons |
|---|---|---|
| A. Pessimistic lock | Simple, no conflicts | Blocks, doesn't scale |
| B. Optimistic concurrency | Scales, non-blocking | Conflicts need handling |

## Decision
Which one was chosen and why, in one paragraph.

## Consequences
What gets easier, what gets harder, what debt this creates.

Five pieces do the work: who decided, what context existed, what options were compared, what got chosen, and what state the approval is in. Everything else is formatting.

#How they're named and where they live

An ADR isn't a loose Google Doc nobody reopens — it lives in the repo, versioned like the rest of the code.

• Folder: docs/adr/ (or docs/decisions/ — either convention works as long as the team sticks to it).
• File name: a sequential four-digit number plus a short kebab-case title. Example: 0007-use-optimistic-concurrency-for-inventory.md.
• Numbers are never reused or reordered, even if an ADR gets rejected.
• An accepted ADR is immutable. If the decision changes later, you don't edit the old file — you write a new ADR that replaces it, and the old one moves to "Superseded by ADR-00XX."

That sequential numbering is what turns the folder into a timeline: anyone can read, in order, how the architecture evolved and why.

#Set a deadline, and send it by email

I learned this the hard way: an ADR without an approval deadline just floats forever in a Slack channel nobody reopens.

What worked for me: send the ADR by email — not chat — to everyone who needs to approve it, with an explicit deadline. 48 hours is reasonable. If there's no objection by then, you move forward with the proposal.

Silence is communication too. And unlike a verbal "yes" on a call, an email with a date and named recipients can't be denied later.

#Push for it anyway, even if nobody asks you to

Writing this takes a morning, sometimes more. And it's realistic to expect that neither the TL nor the architects will push for it — not because they're against ADRs as such, but because, as we saw, the incentive to leave things vague is still theirs. That doesn't change just because an ADR is good practice: a professional practice doesn't get adopted for being correct, it gets adopted when someone holds onto it against that incentive.

That someone can be you. Not as a heroic gesture, but because it's the cheapest way to solve the actual problem: no longer depending on someone else's memory for your work to hold up. If you find someone else on the team pushing for the same thing, join them — an ADR protects everyone who was part of the decision, not just whoever wrote it.

Three months later, when someone needs to reconstruct why a decision was made, that document will have the answer. You won't need to raise your voice to defend yourself: the document already has it covered.

#adr #architecture #decision-making #documentation