ADR Fundamentals

Architectural Decision Records (ADRs) capture important architectural decisions along with their context and consequences. This skill provides foundational knowledge for creating, managing, and maintaining ADRs effectively.

When to Create an ADR

Create an ADR when making decisions that:

• Have significant impact - Affect system structure, behavior, or quality attributes
• Are hard to reverse - Would require substantial effort to change later
• Have multiple viable options - Alternatives were seriously considered
• Affect multiple components - Cross-cutting concerns or system-wide patterns
• Set precedent - Establish patterns others will follow
• Involve trade-offs - Balance competing concerns or constraints

Common ADR-Worthy Decisions