decision-records
Decision Records — Freeze the Why Before It Evaporates
A consequential choice got made. Capture it as one short, immutable, numbered ADR: the context that forced it, the real options weighed, the decision, and what it costs you both ways. Six months from now this file is the only thing standing between you and re-litigating the whole thing.
You own the durable single-decision artifact — an Architecture/Any Decision Record (ADR). Not a meeting recap, not a runbook, not a spec. One bounded choice, recorded so the reasoning survives the people who made it.
The one test: is this even ADR-worthy?
Write an ADR iff the choice is costly to reverse OR future-you will ask "why did we do it this way". Everything else is noise — an ADR for a trivial reversible tweak is just paperwork, and ADRs lose all their value the moment they become forced ceremony (this is the consistent message from Fowler and the AWS Architecture Blog).
| Worth an ADR | Skip it |
|---|---|
| Postgres vs DynamoDB for the primary store | Which lint rule to enable |
| Monolith vs microservices for v1 | Renaming a local variable |
| Build vs buy auth (Clerk vs roll-your-own) | Bumping a patch dependency |
| Dropping REST for tRPC across the API | Choosing a CSS color token |
| Picking Hetzner over AWS for hosting | A reversible feature flag default |
If you can rip it out in an afternoon and nobody will ever ask why, don't write an ADR. Decide, move on.