Architecture decision records that teams actually read

Most ADRs die the week after they are written. Not because architecture is unimportant — because the template asks for a novel when the team needed a decision someone could find at 2 a.m.

A good ADR is not proof that you had a meeting. It is proof that you chose something, knew the cost, and left breadcrumbs for the next person.

Write for the next on-call

An ADR should answer four questions in under a page:

1. Context — what pressure forced a choice now?
2. Decision — what did we pick, in one sentence?
3. Consequences — what becomes harder after this?
4. Revisit triggers — what would make us reverse it?

If you cannot name a revisit trigger, you are writing dogma, not a decision record.

“Revisit when p95 latency on checkout exceeds 2s for seven days” is a trigger. “Revisit when we learn more” is not.

Link it to the code

Put the ADR next to the module it governs, or link the PR that implemented it. Records that live only in Confluence get orphaned the first time the org chart moves.

A one-line comment in the repo — see docs/adr/003-tenant-middleware.md — beats a perfectly formatted page nobody can find from the stack trace.

Overturn without drama

Good ADRs make reversal cheap: date the supersession, keep the old record, and update the link from code. Teams that punish “wrong” decisions stop recording anything honest.

Architecture changes. The record should show when and why it changed — not pretend the first guess was prophecy.

Takeaway

Short, linked, reversible. That is how ADRs survive contact with production.

If nobody reads them, the problem is usually length and location — not whether architecture matters.