mohamadkhani.pro

Architecture Decision Records That Age Well

1 min read

An Architecture Decision Record is a short document that answers one question: why did we choose this? Not what we built — why. Teams that keep good ADRs stop re-litigating the same decisions every eighteen months.

The format that works

Every ADR template works if you actually fill it in. The one I keep coming back to:

# ADR-0007: Use an outbox table for event publication
 
## Status
 
Accepted (2026-08-14)
 
## Context
 
Orders are written to PostgreSQL; events must reach Kafka.
Dual writes can lose events on crash.
 
## Decision
 
Write events to an `outbox` table in the same transaction;
a relay publishes them to Kafka.
 
## Consequences
 
- No lost events between DB and Kafka
- At-least-once delivery: consumers must be idempotent
- One more table to monitor for growth

Three traits of ADRs that survive

  1. They are short. If it doesn't fit on one screen, it won't be read in a year.
  2. They record rejected options. The rejected alternatives are the whole point — they tell future readers what was already considered.
  3. They state expiry conditions. "This holds while we're under 5k events/sec" turns a stale ADR from misinformation into a documented threshold.

Where they live

In the repository, next to the code, reviewed in pull requests. A wiki page nobody watches is where context goes to die. If the decision can't be found next to the system it shaped, it effectively doesn't exist.

Summary

  • Record why, not what — the diff already explains what.
  • Keep them short, store rejected options, add expiry conditions.
  • Keep them in version control and let them age via supersession, not silent rot.