Architecture Decision Record (ADR)

An Architecture Decision Record documents a significant technical decision along with its context and consequences. ADRs capture the "why" behind architectural choices so future team members understand the reasoning - especially important when they question why something was done a particular way. This skill follows Michael Nygard's lightweight ADR format.

When to Use

• Making significant technical decisions that affect system architecture
• Choosing between technology options (frameworks, databases, services)
• Establishing patterns that future development should follow
• Documenting the rationale for constraints or non-obvious approaches
• Preserving institutional knowledge about past decisions

When NOT to Use

• The decision is a product or UX design choice, not architecture or technology -> use develop-design-rationale
• You are still exploring whether an approach is feasible -> time-box the exploration and record it with develop-spike-summary first
• You need to pitch a solution to stakeholders -> use develop-solution-brief; an ADR records a decision, it does not sell one
• Nothing is actually being decided (the status quo continues unchanged): an ADR without a decision is noise; wait until there is one