ADRs in Practice

Architecture decision records were introduced in the previous course as a concept. This lesson makes them operational. An ADR practice is not a template — it is a habit. The team that writes ADRs for every significant decision builds an institutional memory that compounds over time. The team that writes them occasionally builds a scattered archive of some decisions with no connection to the rest.

1. What Warrants an ADR Not every decision needs an ADR. The threshold: if the decision affects more than one team, takes more than a day to reverse, or will be questioned in three months, write an ADR. Technology selections: always. Integration pattern choices: always. Library selections for non-critical utilities: rarely. The threshold prevents both under-documentation and documentation fatigue.
2. The Lightweight Format Title. Date. Status (proposed, accepted, deprecated, superseded). Context: why the decision was needed. Decision: what was decided. Consequences: what follows from the decision. That is the entire format. One page. No headers, footers, version history, or approval workflows. The format is lightweight because the goal is adoption, not process.
3. Storage and Discovery Store ADRs in the repository alongside the code they govern. A docs/decisions/ directory with sequentially numbered files: 001-use-postgresql.md, 002-event-driven-order-processing.md. The numbering creates a timeline. The location creates proximity. The naming creates discoverability. Search "why did we choose PostgreSQL?" and the answer is in the repository.
4. Lifecycle Management ADRs are not permanent. When a decision is revisited — because the review trigger was reached or circumstances changed — the original ADR is marked "Superseded by ADR-015" and the new ADR references the original. The chain of decisions is visible. The evolution of the architecture is documented. Future architects can trace the reasoning from the first decision to the current state.