Create ADR

Purpose

Document significant technical decisions with full context, alternatives considered, rationale, and consequences. One ADR file per decision. ADRs serve as the institutional memory of why the system is built the way it is, preventing repeated debates and providing context for future architects. A well-maintained ADR log is the single source of truth for architectural rationale — it answers "why did we do it this way?" faster than any code comment or wiki page.

Architecture/Decision Trees

Should You Write an ADR?

Is this a significant technical decision with lasting impact?
  |-- YES --> Does it affect architecture, data model, or system behavior?
  |     |-- YES --> Does it have multiple valid alternatives?
  |     |     |-- YES --> WRITE AN ADR
  |     |     |-- NO  --> Skip (trivial decision)
  |     |-- NO --> Skip (operational detail)
  |-- NO --> Is the rationale non-obvious?
        |-- YES --> WRITE AN ADR
        |-- NO --> Skip