Architecture Decision Records for real teams

Decisions need memory

Architecture gets expensive when decisions disappear into meetings, chat threads, and private assumptions. An ADR keeps the reason, trade-off, and consequence attached to the choice.

Good records do not replace judgment. They preserve enough context to make future judgment cheaper.

The useful shape

I keep ADRs short: context, decision, consequences, alternatives considered, and links to evidence. The goal is not ceremony. The goal is searchable team memory.

Status: accepted
Context: services need tenant-aware authorization
Decision: enforce tenant checks in application services and database filters
Consequences: simpler review path, more explicit tests, less accidental data leakage

A review rhythm that survives delivery

The record is useful only when it has a rhythm. Review it during design, link it from pull requests, and reopen it after incidents or major product shifts.