Skip to content

AWS Architecture Decision Records (ADRs) Guide⚓︎

Overview⚓︎

AWS published a comprehensive guide recommending ADRs as a structured process for documenting architecturally significant decisions. The guide provides templates and best practices based on AWS’s internal usage.

Source: https://www.infoq.com/news/2022/06/aws-adr-guide/

Definition⚓︎

According to the AWS guide:

“An ADR is a short document that describes a team decision that influences the software architecture.”

AWS provides templates to standardize ADR creation, ensuring consistent capture of:

  • The decision itself: What was chosen
  • Context surrounding the decision: Why it was needed
  • Consequences of the choice: What impacts will result

Key Principles⚓︎

Ownership & Responsibility⚓︎

The team member proposing an ADR owns it throughout its lifecycle and maintains accountability for its content.

Immutability⚓︎

Once approved or rejected, ADRs become unchangeable. Updates require proposing new ADRs that supersede previous ones. This ensures:

  • Historical context is preserved
  • Past reasoning remains accessible
  • Decision evolution is trackable

Decision Log Value⚓︎

The collective ADRs create:

“A broad context, design information, and implementation details about the project.”

Best Practices⚓︎

Clear States⚓︎

ADRs progress through defined statuses:

  • Proposed: Initial submission for review
  • Accepted: Approved and ready for implementation
  • Rejected: Not approved, with reasons documented
  • Superseded: Replaced by a newer ADR

Team Review⚓︎

Collaborative meetings ensure decisions receive thorough examination before approval. This:

  • Brings diverse perspectives
  • Identifies potential issues early
  • Builds team consensus
  • Creates shared understanding

Change History⚓︎

Document evolution by marking old decisions as superseded when replaced. This maintains:

  • Clear decision timeline
  • Understanding of why changes were made
  • Ability to learn from past choices

Reference Tool⚓︎

Teams leverage the decision log during:

  • Code reviews: Validate conformance to architectural decisions
  • Architecture reviews: Ensure consistency with past choices
  • Planning: Understand constraints and context
  • Onboarding: Bring new team members up to speed

Benefits⚓︎

  • Reduces repetitive discussions: Past decisions are documented and findable
  • Improves architectural communication: Provides shared vocabulary and understanding
  • Supports distributed teams: Asynchronous decision making and review
  • Creates institutional knowledge: Prevents loss of context
  • Validates conformance: Reference during reviews

Implementation Considerations⚓︎

When to Create an ADR⚓︎

Create an ADR for decisions that:

  • Have significant architectural impact
  • Are difficult to reverse
  • Affect multiple components or teams
  • Involve trade-offs between competing concerns
  • Need to be remembered long-term

ADR Lifecycle⚓︎

  1. Draft: Author creates initial proposal
  2. Review: Team discusses and provides feedback
  3. Decision: Team accepts or rejects
  4. Archive: Store in decision log (never delete)
  5. Reference: Use during development and reviews

Use Cases⚓︎

  • Best for: Organizations valuing structured decision making
  • Project Size: Medium to large projects
  • Team Size: Multiple teams or distributed organizations
  • Culture: Teams that value documentation and process