adr-template

Use an Architecture Decision Record (ADR) template to capture the context, decision, alternatives considered, and consequences. This structured approach ensures your team understands the rationale behind significant trade-offs and technology selections.

Create an architecture decision record for meaningful architectural changes like technology choices, irreversible trade-offs, or deploy, auth, and error-handling strategy changes. Skip ADRs for trivial or easily reversible decisions to maintain engineering governance focus.

An architecture decision record template should include Context, Decision, Alternatives Considered, Consequences (including risks), and a Compliance checklist. This structure provides a ready-to-copy format suitable for team review and engineering governance.

Manage changes to an accepted architecture decision record by keeping accepted ADRs immutable and using a "Superseded by" status when decisions evolve. This maintains historical context, prevents repeating past trade-off mistakes, and reinforces best practices.

The best way to evaluate alternatives during technology selection is to document real options considered alongside the final decision and their positive or negative consequences. Recording these trade-offs in an ADR prevents repeating past mistakes and clarifies the system design rationale.