Why I write Architecture Decision Records
Six months after a decision, nobody remembers why it was made. The person who made it may have moved on, and the context lives in a meeting nobody recorded. An Architecture Decision Record (ADR) fixes that with one short document per decision.
The format I use
# ADR-0007: Use AWS CDK for new platform stacks
## Status
Accepted
## Context
What problem are we solving? What constraints apply?
## Decision
What we chose, in one or two sentences.
## Consequences
What gets easier, what gets harder, what we must watch.
What makes a good ADR
- One decision per record. If it needs two headings, it's two ADRs.
- Options you rejected. These are often the most valuable part.
- Honest consequences. Every choice has a cost; write it down.
- Immutable once accepted. Supersede it with a new ADR instead of editing history.
What it changed for us
In architecture groups I've been part of, ADRs gave us a shared place to discuss trade-offs before building, and a quick answer for every new team member who asks "why is it like this?". The time spent writing them is small compared with the meetings they save.
If a decision is worth arguing about, it's worth writing down.