Architecture Decision Records (ADR)

Core Principle

Document decisions, not just implementations. Capture the "why" when it's fresh.

The most valuable documentation isn't what you built—it's why you built it that way. Architecture Decision Records capture the context, options considered, and trade-offs at decision time. Six months later, when someone asks "why did we choose this?", the ADR provides the answer.

Good ADRs are:

• Written when decisions are made (not after)
• Context-rich (capture constraints and alternatives)
• Consequence-aware (document trade-offs honestly)
• Living documents (can be superseded or deprecated)

When to Use