Architecture Decision Records
Overview
Use this skill to make architecture decisions auditable, reversible when possible, and maintainable as constraints evolve.
Scope Boundaries
- A technical decision changes long-term system direction.
- Multiple viable options exist and trade-offs must be explicit.
- Teams need a durable rationale for future reviewers.
Core Judgments
- Decision scope: what is affected and what is intentionally out of scope.
- Option set quality: whether alternatives are truly viable.
- Reversibility: cost and risk if the decision is later changed.
- Expiry/revisit trigger: what future signal should force reevaluation.
Practitioner Heuristics
- Record decisions at the same abstraction level as the problem; avoid mixing architecture and local code style debates.
- Rejected options are as important as selected ones for future context.
- State assumptions explicitly, especially around traffic, team capacity, and compliance constraints.
- Include consequences for operations and developer workflow, not only runtime behavior.
Workflow
- Define decision question and non-negotiable constraints.
- Enumerate realistic options and decision criteria.
- Analyze trade-offs including failure modes and operational impact.
- Select a decision and capture why alternatives were rejected.
- Define measurable revisit triggers and ownership.
- Link the record to affected architecture artifacts and implementation work.
Common Failure Modes
- ADRs describe outcomes after the fact without real alternative analysis.
- Decision records never revisit invalidated assumptions.
- Records duplicate design docs and lose decision focus.
Failure Conditions
- Stop when constraints are incomplete or contradictory.
- Stop when no meaningful alternatives are considered.
- Escalate when decision ownership and revisit triggers are undefined.