Architecture Decision Records (ADRs)

Best Practice: Architecture Decision Records (ADRs)

An Architecture Decision Record (ADR) is a short document that captures a single significant architectural decision: the context that forced the choice, the decision itself, and the resulting consequences. The lightweight format was popularized by Michael Nygard in 2011 and is now a widely used pattern, with templates collected at adr.github.io. ADRs live in the repository alongside the code, so the reasoning behind a system is version-controlled, discoverable, and reviewed with the same rigor as code. An ADR answers the question that haunts every maintainer: "Why was it built this way?" Instead of that knowledge living in a departed engineer's head or a buried chat thread, it sits in a numbered Markdown file next to the system it explains. For migrations, where many irreversible choices are made quickly and under pressure, ADRs preserve the rationale and trade-offs that future teams desperately need when they revisit or reverse those choices.

Step-by-Step Implementation Guidance

1. Choose a lightweight template (for example, Nygard's: Title, Status, Context, Decision, Consequences).
2. Store ADRs as numbered Markdown files in a docs/adr directory in the repo.
3. Write an ADR whenever a decision is significant, costly to reverse, or affects multiple teams.
4. Capture real context, including the forces and constraints, not just the conclusion.
5. Use statuses such as Proposed, Accepted, Deprecated, and Superseded.
6. Never edit a decided ADR's intent; instead supersede it with a new ADR that links back.
7. Review ADRs in normal pull requests so decisions get peer scrutiny.

Common Mistakes Teams Make When Ignoring This Practice

• Important decisions living only in chat threads or someone's memory.
• Recording the decision but omitting the context and trade-offs.
• Documents that drift from reality because they live outside the repo.
• Overusing ADRs for trivial choices until no one reads them.
• Rewriting history instead of superseding outdated decisions.

Tools and Techniques That Support This Practice

• adr-tools and Log4brains for creating and managing ADRs.
• MADR (Markdown Any Decision Records) templates.
• Static site generators to publish ADR logs for stakeholders.
• Pull request review to vet decisions before acceptance.

How This Practice Applies to Different Migration Types

• Cloud Migration: Record why a workload was rehosted versus refactored, and which provider services were chosen.
• Database Migration: Document the chosen migration strategy, consistency trade-offs, and rollback plan.
• SaaS Migration: Capture build-versus-buy reasoning and vendor lock-in trade-offs.
• Codebase Migration: Log decisions on framework choice, strangler-fig boundaries, and deprecation timelines.

Checklist

• A lightweight ADR template is agreed on.
• ADRs are stored in the repo and version-controlled.
• Each ADR records context, decision, and consequences.
• Statuses track the lifecycle of each decision.
• Superseded ADRs link to their replacements.
• Significant decisions trigger an ADR.
• ADRs are reviewed in pull requests.