M8-097M8: ML Systems, Engineering & ResearchTechnical Communication & ImpactMedium
⚡Flashcard Drill➔Mastery:

Explain the Purpose, Lifecycle, and Structural Template of Architectural Decision Records (ADRs)

📐 Mathematical Definition
ADR=context+decision+alternatives+rationale+consequences\text{ADR}=\text{context}+\text{decision}+\text{alternatives}+\text{rationale}+\text{consequences}
⚡ One-Sentence Core Answer
An Architectural Decision Record (ADR) is a lightweight, immutable document capturing a significant architectural choice—recording context, problem constraints, considered alternatives with trade-offs, selected decisions, and downstream consequences to preserve institutional memory and prevent circular technical debates.

📌 Key Takeaways

  • •
    Core ADR structural template: Title & Status -> Context & Constraints -> Decision -> Alternatives Considered (with rejection rationale) -> Positive and Negative Consequences.
  • •
    Preserving rejected alternatives: Documenting why viable alternatives were not chosen is as critical as the final decision, preventing future teams from endlessly re-debating discarded paths.
  • •
    Living version-controlled lifecycle: Storing ADRs as Markdown files within the source code repository under git version control, transitioning statuses across Proposed, Accepted, Deprecated, and Superseded.

📐 Mathematical Derivations

ADR Template Structure & Governance Lifecycle:

(1) The Standard ADR Template (Michael Nygard Architecture):
- Title & Metadata: ADR-0042: Adoption of vLLM PagedAttention for Production LLM Serving; Date; Authors; Decider(s); Status.
- Status Lifecycle: Proposed -> Accepted -> [Superseded by ADR-XXXX | Deprecated].
- Context & Constraints:
- What specific technical or business problem forces this decision?
- What constraints exist (latency budgets, GPU VRAM limits, cloud vendor locks, compliance mandates)?
- Decision:
- State the precise, active architectural choice: 'We will migrate our real-time LLM inference fleet from TensorRT-LLM to vLLM with Ray orchestration.'
- Alternatives Considered & Rejection Rationale:
- Alternative A (TensorRT-LLM): High raw throughput, but compilation times for dynamic LoRA adapters are unacceptable for our multi-tenant SaaS.
- Alternative B (Triton C++ Backend): Maximum low-level control, but requires extensive custom CUDA C++ maintenance that our Python-centric team cannot support.
- Consequences (The Honest Balance Sheet):
- Positive Impacts: 3.5×3.5\times higher token serving throughput, seamless dynamic LoRA hot-swapping via PagedAttention.
- Negative Impacts / Trade-offs: Increased Python process memory overhead, dependency on rapid upstream vLLM API changes.
- Follow-up Obligations: Requires rewriting monitoring probes for vLLM Prometheus metrics.

(2) When to Write an ADR:
- Significant architectural changes (changing database engines, switching model serving runtimes, choosing serialization protocols).
- Decisions that are difficult to reverse (Type 1 decisions).
- Decisions with substantial cross-team controversy or trade-off complexity.

🏭 Production Trade-offs

In-Depth Analysis & Engineering Trade-offs: ① Documenting rejected alternatives is the highest-value component of an ADR—six months later, new engineers will inevitably ask 'Why didn't we just use library X?'; an ADR provides an immediate, authoritative answer documenting the exact historical constraints that disqualified X. ② ADRs must live alongside code in Git—storing architecture decisions in external corporate wikis (Confluence, Notion) guarantees they will rot and be forgotten; storing them as Markdown files in docs/adr/ inside the repo ensures they are reviewed in PRs. ③ ADRs are immutable historical records—never edit an accepted ADR to reflect a new architectural pivot; instead, author a new ADR that explicitly marks the prior record as Superseded by ADR-XXXX. ④ Keep ADRs concise and scoped to a single decision—an ADR should be 1–2 pages long focusing on a single specific choice; broad multi-faceted system overhauls belong in comprehensive System Design Documents that reference individual ADRs. ⑤ Clarify the decision owner—consensus-driven deliberation is healthy, but every ADR must list the explicit single-threaded decision maker who ultimately authorized the choice. ⑥ Interview takeaway—outline the Nygard template (Context -> Decision -> Alternatives -> Consequences), explain why documenting rejected alternatives stops circular debates, and describe the Git-based immutability lifecycle.
⚠️ Common Interview Pitfalls
  • ✕
    Failing to document rejected alternatives and trade-offs, allowing teams to endlessly repeat identical technical debates every few quarters.
  • ✕
    Modifying historical ADRs in-place when architectural paradigms change rather than creating a new ADR that explicitly supersedes the predecessor.
  • ✕
    Writing massive 20-page ADRs covering entire system redesigns rather than keeping them focused on singular, atomic architectural choices.
🎯 Interviewer Follow-up Inquiries
  • ?
    How do you integrate ADR approvals into standard Git pull request workflows and technical architecture review boards?
  • ?
    What criteria determine whether a technical decision should be documented as an ADR versus a lightweight pull request description?
  • ?
    How do you organize and index an ADR repository when the number of historical records grows past several hundred entries?
⚡
Test muscle memory on this topic via 3-Layer Flashcards
Active Recall: Mentally formulate Prompt ➔ Math Derivation ➔ Benchmark Implementation in 3 minutes.
🎯 Drill This Card Now➔
📚

Associated Knowledge Base Guides & Mindmaps

Explore the comprehensive technical article, exam cards, and global architecture tree.

← PreviousM8-096: Explain Strategies for Building Cross-Functional Consensus and Securing Buy-In for Complex Technical Proposals📋Back to BankNext →M8-098: Explain Methodologies for Constructing Business-Aligned, Measurable, and Adaptable Technical Roadmaps
中文速览与面试要点

如何做技术决策并记录(ADR)?

用架构决策记录(ADR)记录背景、决策、备选方案、理由与后果;让决策可追溯、可复盘,避免反复争论与知识流失。

核心要点

  • 数学机理: 架构决策记录(Architecture Decision Record, ADR) ——(1) 结构 ——(a) 标题与状态 ——编号、标题、状态(提议/已接受/已废弃/被取代);(b) 背景(context) ——面临的问题、约束(时间、成本、合规、团队能力、既有系统);(c) 决策(decision) ——明确选择了什么(可执行、无歧义);(d) 备选方案(alternatives) ——考虑过哪些方案、各自的优缺点、为何未选; 关键 ——记录'未选'避免后人重复讨论;(e) 理由(rationale) ——选择的依据(权衡、数据、原则);(f) 后果(consequences) ——正面影响、负面影响(需接受的代价)、对后续决策的影响。(2) 作用 ——(a) 可追溯 ——为什么做这个决定(半年后还能查);(b) 可复盘 ——决策的依据当时是否成立,现在是否需重审;(c) 避免反复争论 ——记录后不必每次重新辩论;(d) 知识沉淀 ——新人能理解历史决策(避免'为什么这么设计'的困惑);(e) 问责 ——明确决策者与时间。(3) ADR vs 设计文档 ——(a) ADR ——聚焦 单个决策 (轻量、一个决定一篇);(b) 设计文档 ——描述 整体设计 (较重、多决策);(c) 关系 ——设计文档可引用多个 ADR。(4) 何时写 ——(a) 影响架构/接口/技术栈的决策;(b) 难以逆转的决策;(c) 有争议的决策;(d) 不必 ——琐碎的、易改的。(5) 粒度 ——(a) 一个决策一篇 ADR(轻量);(b) 简短(半页到一页);(c) 版本控制(与代码同仓库)。(6) 决策的流程 ——(a) 明确决策者 (谁拍板);(b) 收集输入 (相关方意见);(c) 评估备选 (权衡矩阵);(d) 决策并记录 ;(e) 沟通 (让相关方知晓);(f) 定期重审 (条件变化时)。(7) 常见问题 ——(a) 不记录(知识流失);(b) 只记决策不记理由与备选(无法复盘);(c) 过长(无人读);(d) 不更新(决策已变但记录未改);(e) 无人负责(决策模糊)。(8) 工具 ——(a) Markdown 文件(docs/adr/)与代码同仓库;(b) 模板化;(c) 编号与索引。 与其他问题的关系 ——(a) 与推动方案(决策的沟通);(b) 与 disagree and commit(决策后执行);(c) 与技术传承(知识沉淀)。 度量 ——(a) ADR 覆盖率(重大决策有记录的比例);(b) 决策重审频率;(c) 新人理解历史决策的时间。
  • 深度剖析与工程权衡:① 记录未选的备选方案最关键 ——避免后人重复讨论;面试中能指出这点是深度理解的标志。② ADR 轻量、一个决策一篇 ——与设计文档分工不同。③ 记录理由使决策可复盘 ——条件变化时可重审。④ 明确决策者 ——避免模糊责任。⑤ 不必为琐碎决策写 ——否则无人读。⑥ ADR 需与代码同仓库并版本化 。⑦ 面试要点 ——被问怎么做技术决策,应给出' ADR 结构(背景/决策/备选/理由/后果)+ 明确决策者 + 收集输入 + 定期重审 + 与代码同仓库 ';能指出记录备选方案与理由的价值是深度理解的标志。
  • 背景(context)——问题是什么、约束是什么(时间/成本/合规/团队能力)
  • 决策(decision)——选择了什么(明确、可执行)
  • 备选方案(alternatives)——考虑过什么、为何未选
  • 理由(rationale)——为何选这个(权衡依据)
  • 后果(consequences)——正面/负面影响、需接受的代价、后续影响

常见陷阱

  • 不记录决策理由(无法复盘)
  • ADR 写得过长(无人阅读)