Where should ADRs be stored?

ADRs should live in version control (Git) alongside the code they govern, typically in a dedicated 'adrs' directory or a centralized architecture repository.

Why use ADRs for infrastructure and cloud projects?

Infrastructure ADRs prevent 'decision drift' and save weeks of repeated debates by ensuring that choices like cloud provider or networking design are documented and easily referenceable.

What kind of decisions deserve an ADR?

A good heuristic is that if a decision takes more than 10 minutes to explain to a new team member or more than a day to revert, it deserves an ADR.

What is an Architecture Decision Record (ADR)?

An ADR is a short text file that documents a significant architectural decision, including its context, the choice made, and the resulting consequences.

How are ADRs updated when a decision changes?

ADRs are immutable. When a decision is changed, you do not edit the original file; instead, you create a new ADR that explicitly supersedes the old one to preserve historical context.

Architecture Decision Records (ADR)

Name: Architecture Decision Records (ADR)
Author: oborchers

byoborchers

•

Cloud Infrastructure

Documents and tracks significant architectural and infrastructure decisions using standardized, immutable records to prevent technical debt and simplify team onboarding.

This skill streamlines the creation and maintenance of Architecture Decision Records (ADRs) within your codebase, ensuring that critical infrastructure choices—from cloud provider selection to CI/CD strategies—are documented with clear context and consequences. By following the lightweight Nygard format, it helps platform and engineering teams avoid re-litigating old debates, tracks exemptions from Infrastructure-as-Code (IaC), and provides a historical audit trail for new team members. It is particularly useful for engineering leaders and developers building SaaS products who need a lightweight yet robust governance framework that lives alongside their code.

Key Features

019 GitHub stars

02Standardized ADR templates using the Nygard context-decision-consequences format

03Immutable version control for decision history with automated status lifecycle management

04Infrastructure-as-Code (IaC) exemption tracking for documenting manual cloud console interventions

05Sequential numbering and indexing to ensure a searchable architecture audit trail

06Cloud-agnostic guidance for AWS, GCP, and Azure foundational architectural patterns

Use Cases

01Onboarding new engineers by providing a documented history of why specific technical choices were made

02Standardizing naming conventions and multi-account strategies across cloud environments

03Managing technical debt by superseding outdated architectural decisions with clear migration paths

Key Features

019 GitHub stars

02Standardized ADR templates using the Nygard context-decision-consequences format

03Immutable version control for decision history with automated status lifecycle management

04Infrastructure-as-Code (IaC) exemption tracking for documenting manual cloud console interventions

05Sequential numbering and indexing to ensure a searchable architecture audit trail

06Cloud-agnostic guidance for AWS, GCP, and Azure foundational architectural patterns

Use Cases

01Onboarding new engineers by providing a documented history of why specific technical choices were made

02Standardizing naming conventions and multi-account strategies across cloud environments

03Managing technical debt by superseding outdated architectural decisions with clear migration paths