本文由 AI 分析生成
建立時間： 2026-03-28 來源： https://adr.github.io/
Summary
The official GitHub ADR organization page explaining Architectural Decision Records — a lightweight practice for capturing significant design choices and their rationale. Each ADR documents a single Architectural Decision (AD), its context, options considered, decision made, and consequences. The collection of ADRs in a project forms its architectural decision log.
GitHub ADR 組織官方頁面，說明架構決策紀錄（ADR）——一種輕量化的設計決策文件實踐。每個 ADR 記錄單一架構決策、其背景、考量選項、最終決定及後果，形成專案的架構決策日誌。
Key Points
- Core definitions: AD = a justified design choice; ASR (Architecturally Significant Requirement) = a requirement with measurable effect on architecture; ADR = record capturing a single AD + rationale; Decision Log = the full collection of ADRs
- Origin: Michael Nygard’s 2011 blog post popularized the concept; Eric Evans’ DDD and Sustainable Architectural Decisions by Zdun et al. provide theoretical grounding
- Y-statement format: a common template structure — “In the context of
, facing , we decided - Industry adoption: Azure Well-Architected Framework features ADRs; AWS Prescriptive Guidance recommends ADRs for tech decision-making; included in IEEE Software
- Agile compatibility: ADRs align with iterative engineering — lightweight enough to write quickly, valuable enough to preserve institutional knowledge
Insights
The most common pain point ADRs solve is the “why did we do it this way?” question six months later when the original decision-maker has left. ADRs externalize rationale that otherwise exists only in someone’s head. The trade-off decision (“we chose X despite Y downside because Z”) is exactly what gets lost when only the outcome is documented.
ADRs are particularly valuable during tech migrations: they capture the “we considered staying on X, but chose Y because of constraint Z” reasoning that prevents future teams from second-guessing choices that were correct at the time. The consequence of not capturing this is re-evaluating the same decision repeatedly.
The GitHub ecosystem makes ADRs easy: storing docs/decisions/0001-use-postgresql.md in the repo means ADRs live alongside the code they explain, get code-reviewed like any other change, and are version-controlled.
Connections
Raw Excerpt
An Architectural Decision Record (ADR) captures a single AD and its rationale. The collection of ADRs created and maintained in a project constitute its decision log. Put simply, ADRs can help you understand the reasons for a chosen architectural decision, along with its trade-offs and consequences.