All insights
EngineeringProcess5 min read
The architecture decision review that's actually useful
Most ADRs (architecture decision records) sit unread in a wiki folder. The ones that matter share a small set of design choices.
ADRs are one of those tools every engineering team adopts once and then mostly forgets about. The few teams who actually use them — and benefit — share a few habits that the rest don't.
What works
- Short — under 500 words for most decisions.
- Names the alternatives considered and rejected, with reasons.
- Dated and signed — you can see who made the call when.
- Linked from the code they affect, not buried in a wiki.
What kills ADRs
Long templates that take an hour to fill out. Approval workflows that turn ADRs into committee work. Treating them as required for every change instead of for the decisions that future engineers will need to understand. Most ADR programs die from over-process, not under-use.
An ADR is a note to the next engineer who'll have to revisit this. Write it like that.