Documentation and ADRs

Overview

Document decisions, not just code. The most valuable documentation captures the why — the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered.

Instructions

Architecture Decision Records (ADRs)

Write an ADR when:

• Choosing a framework, library, or major dependency
• Designing a data model or database schema
• Selecting an authentication or API architecture strategy
• Any decision that would be expensive to reverse

Store ADRs in docs/decisions/ with sequential numbering: