A Decision Nobody Wrote Down Is a Rumor With Consequences

Watch the 40-second version here: Architecture Decision Records That Pass Review

Every team has one. The cache TTL set to 47 minutes for reasons lost to time. The "temporary" dependency that is now load-bearing. Ask who decided and you get four names, two of whom left the company last year.

The decision evaporated. The consequences did not.

This is why staff-level engineers write Architecture Decision Records. An ADR is one page answering: what did we decide, what did we reject, what are we on the hook for now. Four sections: context, options, decision, consequences. Twenty minutes of writing that outlives every meeting that produced the decision.

Now the part nobody tells you. The options section is the entire point. A decision with no options section is not a record, it is a press release. "We chose Postgres" teaches the reader nothing without the alternatives. The rejected options are where the actual knowledge lives. Six months later a new hire suggests "why not Mongo" and instead of re-litigating a settled debate, you hand them the ADR. The argument died before it was born.

Then there is the selfish effect. Undocumented decisions are incident fuel. At 2am nobody can reconstruct why the circuit breaker threshold is 12 and not 50, so they guess. They guess under pressure. ADRs are the difference between debugging the system and reverse-engineering it while the pager screams.

It also reads well in interviews. Juniors describe what the system does. Staff-level candidates explain what it could have been and why it is not. The answer that lands shows trade-off thinking, and ADRs are trade-off thinking in document form.

Here is a template you can steal. Save it as docs/adr/001-whatever.md and fill one in today:

# ADR 004: Use React Query for server state

Date: 2026-10-13
Status: Accepted

## Context
Dashboard refetches on every tab change. Three hand-rolled caches
disagree with each other. Users see stale data; support tickets agree.

## Options
1. React Query: battle-tested cache/invalidate, +28KB.
2. Custom fetch hook: full control, we own every bug forever.
3. Redux + thunks: team knows it, but it is boilerplate city for
   data that is just "load this URL and cache it".

## Decision
React Query. It matches our shape of problem exactly: lots of
reads, few writes, invalidation is the hard part.

## Consequences
- Accept: bundle grows ~28KB; team must learn cache keys.
- Risk: if we later need offline-first, revisit.
- If this proves wrong, ADR 005 supersedes it. ADRs are never edited.

The last line matters more than it looks. Never edit an ADR. Supersede it. The history of being wrong is just as valuable as being right.

Write the decision down today, or future you reverse-engineers it at 2am during an incident. Future you is the reader. Do not make them suffer.