Architectural Decision Records (ADR) — adr.github.io overview
Source
- Type: webpage
- Origin: https://adr.github.io/
- Imported: 2026-05-24
- Images: The page body is textual (definitions, lists, external links only). No inline diagrams or screenshots appeared in HTML and there was no
og:image; nothing substantive to embed beyond optional site chrome, so none were bundled intoassets/.
Content
Motivation and definitions
An Architectural Decision (AD) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. An Architectural Decision Record (ADR) captures a single AD and its rationale. In short, an ADR surfaces the reasons for a chosen architectural decision, along with trade-offs and consequences.
The collection of ADRs maintained in a project is its decision log. This sits within Architectural Knowledge Management (AKM), though ADR practice can extend to design and other decisions (“any decision record”).
The aim of the GitHub adr organization is to:
- Motivate the need for capturing decisions and establish a shared vocabulary.
- Strengthen ADR tooling in support of agile and iterative/incremental engineering.
- Point to public knowledge related to AKM and ADRs.
ADRs in the media
- (German) Slides Architekturentscheidungen sichtbar und nachvollziehbar gestalten at JavaLand 2026, 2026-03-10.
- Azure Well-Architected Framework features ADRs and links this site (2024-11-10).
- Love Unrequited: The Story of Architecture, Agile, and How Architecture Decision Records Brought Them Together, Michael Keeling, IEEE Software Vol. 39 Issue 4 (2022) (PDF stamp).
- Design Practice Reference (LeanPub) positions capturing architectural decisions as essential.
- Chapter 3 of “Patterns for API Design…” discusses recurring API design decisions with options and criteria (related blog post).
- (German) Gut dokumentiert: Architecture Decision Records by @obfischer, heise online.
Background information
Organization work aligns with Sustainable Architectural Decisions (Zdun et al.), including the Y-statement format from that piece.
Further pointers mentioned on the site:
- Architectural Decision Guidance Across Projects … (WICSA 2015) — comparison of seven templates.
- Architectural Decisions — The Making Of — history since the late 1990s, examples, rationale guidance.
- Documenting Architecture Decisions — Michael Nygard (2011), cited as popularizing the idea.
- Architectural Decision Records (ADR) in the Open Practice Library.
- AWS: Architectural decision records.
- Video: Architecture Decision Records in Action (Michael Keeling, Joe Runde).
- Series: ADRs and Architecture Stories (Mark Richards).
- Architectural Knowledge Management (AKM) landing page.
Related sections on the same site
Key takeaways
- ADR: one structured record per significant decision, with rationale and consequences; collectively they form the project decision log under the broader umbrella of Architectural Knowledge Management.
adron GitHub exists to evangelize terminology, tooling, and links to authoritative reading (Nygard, Zdun et al., industry guides, practitioner media).- The homepage is primarily a curated index — deep structure lives in sub-pages (practices, templates, tooling).