Architecture Decision Record (ADR)

Source: Michael Nygard's ADR pattern + Google/Meta/ByteDance design doc culture Core Philosophy: Every architectural decision is a bet. ADRs record the bet, the rationale, and the expected payout so future teams know why you bet what you bet.

Why ADRs Matter

  Without ADRs:
  ❌ "Why did we use MongoDB instead of Postgres?" — nobody knows
  ❌ New hires repeat old debates endlessly
  ❌ Trade-offs are forgotten — only the outcome is visible
  ❌ Bad decisions can't be revisited because we don't know why they were made