architecture-decision-record

An architecture decision record (ADR) is a structured document that captures the rationale, context, and consequences of significant technical decisions. ADRs preserve architectural memory by documenting why choices were made, trade-offs evaluated, and outcomes expected, enabling teams to understand decision history and avoid repeating past analysis.

Create an ADR by following the Nygard template: include status, context (why the decision arose), decision (what was chosen), consequences (outcomes and trade-offs), and alternatives considered. Document the decision title, date, and participants, then store the ADR in version control alongside your codebase for team access and traceability.

Use ADRs for major backend decisions: database migrations, service boundary definitions, API design patterns, technology selections, and governance policies affecting multiple teams. ADRs are essential when decisions have long-term architectural impact, involve trade-offs between competing approaches, or require team alignment on rationale.

Yes. ADRs use standardized Nygard templates that work across teams and contexts. The structured format—context, decision, consequences, alternatives—translates to any technology choice: databases, frameworks, infrastructure platforms, or governance patterns, enabling consistent architectural documentation across diverse backend systems.

ADRs differ from general documentation by explicitly capturing decision rationale and alternatives considered, not just final state. They answer why a choice was made and what was rejected, creating a decision log rather than a static architecture diagram, enabling future developers to understand constraints and past reasoning.

ADRs serve as an architectural reference for new team members, explaining why systems are structured as they are without requiring oral history. Versioned and reviewed ADRs create institutional memory, prevent repeating rejected decisions, and help teams make consistent choices aligned with documented architectural patterns.