软件工程 / 架构设计方法论知识图谱 / 分组目录 / 方法论层 / 架构决策记录
methodology · G · P0 · active

架构决策记录

Architecture Decision Record
P0基础verified方法论 methodology方法G · 架构设计质量属性GL-METHOD · 方法论层

§1摘要与结论

TL;DR · 一句话结论

把每个架构上重要的决策记录为短文本文件（含上下文、决策、状态与后果），使决策依据、取舍与被否决的备选可被追溯、复核与取代，而非散落在会议记录与个人记忆中。

别名：ADR、Architecture Decision Record、架构决策记录　|　英文：Architecture Decision Record　|　类型：方法 / practice

§2局部关系图

架构决策记录 的 1-2 跳邻域关系图前置依赖（prerequisite）：本质复杂度不可消除，故架构只能在约束下权衡前置依赖（prerequisite）：边界划分是对多重质量属性的权衡依据推导（derives_from）：SLO 目标选择体现架构即权衡依据推导（derives_from）：权衡决策方法依据架构即权衡的本质依据推导（derives_from）：风格选型本质是以约束换取期望属性依据推导（derives_from）：属性冲突治理依据架构即权衡的本质依赖关联（dependency）：成本与质量冲突约束技术选型依据推导（derives_from）：文档化方法以架构描述为对象组织视图与对应关系依据推导（derives_from）：文档化依视图与视角约定组织架构信息依据推导（derives_from）：敏感点与权衡点分析是架构权衡判断的内核细化（refines）：效用树构造与敏感点识别细化 ATAM 评估流程的分析环节组合（combination）：决策记录与文档化方法共同承载架构决策与理由促成（enables）：架构文档是架构评估流程的输入前置依赖（prerequisite）：视图与视角概念是理解架构描述构成与对应关系的前提组合（combination）：架构描述记录边界与接口的外部可见属性促成（enables）：敏感点与权衡点分析为架构风格选型提供判据案例印证（case_instance）：印证：以视图与依赖图文档化架构，支撑无源码理解案例印证（case_instance）：印证：去中心化与本地优先等主张皆为显式架构取舍案例印证（case_instance）：印证：以分层文档组织视图，再补跨视图信息案例印证（case_instance）：印证：按不同关注点组织层级与模块视图案例印证（case_instance）：印证：把不可见的架构转写为可复核的架构描述案例印证（case_instance）：印证：以蓝本为参照的多视图文档与深链互引案例印证（case_instance）：印证：以够用原则选择最小接入组合案例印证（case_instance）：印证：选型即权衡，无全能工具案例印证（case_instance）：印证：多源交叉验证与分章文档化案例印证（case_instance）：印证：编译期特性裁剪消除偶然复杂度案例印证（case_instance）：印证：五段式节点页与图谱化文档实现（implements）：AWS 支柱评审落地质量属性场景分析实现（implements）：Azure 风格目录指导架构风格选择实现（implements）：AWS 支柱冲突识别支撑效用树权衡点组合（combination）：风格选择是架构权衡的典型对象组合（combination）：视图记录边界与接口的外部可见属性依据推导（derives_from）：决策记录依架构即权衡，留存取舍与理由依据推导（derives_from）：ATAM 以架构权衡为根本前提依据推导（derives_from）：风格选择依质量属性权衡而非对错依据推导（derives_from）：限界上下文依边界与接口隔离原理前置依赖（prerequisite）：识别敏感点与权衡点是记录架构决策的前提前置依赖（prerequisite）：质量属性场景与评估是风格权衡选型的前置分析组合（combination）：风格选型结果以 ADR 记录理由与被否决项对照（contrasts）：按质量属性选风格与按领域模型划边界的依据存在张力架构决策记录架构决策记录（MTH-G-01）架构即权衡架构即权衡（ESS-O-02）质量属性场景与ATAM质量属性场景与ATAM（MTH-G-02）架构风格选择方法架构风格选择方法（MTH-G-03）架构文档化方法架构文档化方法（MTH-G-05）边界与接口隔离边界与接口隔离（ESS-G-03）本质复杂度与偶然复杂度本质复杂度与偶然复杂度（ESS-O-01）技术选型的够用原则技术选型的够用原则（MTH-O-03）质量属性冲突治理质量属性冲突治理（MTH-O-05）Open Code Re…Open Code Review 图谱（CAS-X-15）视图与视角视图与视角（ESS-G-06）架构描述与对应关系架构描述与对应关系（ESS-G-07）效用树与敏感点权衡点分析效用树与敏感点权衡点分析（MTH-G-06）去中心化聊天架构逆向去中心化聊天架构逆向（CAS-X-01）harness 源码架构…harness 源码架构解析（CAS-X-09）MCP 四件套选型对比MCP 四件套选型对比（CAS-X-12）架构风格架构风格（ESS-G-05）领域驱动战略设计领域驱动战略设计（MTH-G-04）服务等级目标方法服务等级目标方法（MTH-K-01）dsh 插件依赖增量定位dsh 插件依赖增量定位（CAS-X-10）Claude Code …Claude Code 架构逆向（CAS-X-13）AWS 良好架构框架AWS 良好架构框架（TEC-G-01）Azure 架构中心Azure 架构中心（TEC-G-03）质量属性权衡决策方法质量属性权衡决策方法（MTH-M-06）
前置依赖实现依据推导案例印证对比冲突
以本节点为中心，静态内联 1–2 跳邻域：内环 4 个直接邻接、外环 19 个二跳节点，共 24 个节点；连线按边类型着色（六类配色见下）。构建期计算，无运行期脚本。

§3原理 · 为什么

架构是一组根本性决策，其价值不仅在于结论，更在于决策当时权衡的语境、采纳与放弃的理由。决策背后的假设、约束与被否决的备选如果只存在于个人记忆或会议记录中，会随人员流动而蒸发；后人面对既成事实时无法判断它是否仍然成立，也难以安全地推翻，只能被迫继承历史包袱。ISO/IEC/IEEE 42010 明确把 architecture rationale 纳入架构描述，要求记录决策依据及被否决的架构备选，ADR 正是落实该要求的轻量载体。它把隐含于代码与口头传言的架构知识显式化，使架构从「谁记得」变为「谁都能查」。在长生命周期系统里，这份可追溯的决策账本是可维护性、可演化与可审计的共同基础，也是新人理解系统为何如此的最短路径。记录的理由还使决策可被质询：当假设变化时，团队能据此判断旧决策是否失效，从而有依据地更新而非反复争论。

§4机制 · 如何运作

Nygard 模板含五个部分：Title（短名词短语）、Context（价值中立地陈述 forces）、Decision（主动语态 We will…）、Status（proposed/accepted/deprecated/superseded）、Consequences（列出全部正、负、中性后果）。每个决策一个文件，单调递增编号且不复用；决策变化时不修改旧记录，而是新增一条并标 superseded 链接到新记录，从而保留完整的决策演化史与时间线。Fowler 建议采用 inverted pyramid 写法：先写结论与理由，再展开取舍与「认真考虑过的备选方案及利弊」，并可记录决策置信度与应触发重评的上下文变化。由于一条 ADR 只承载一个决策，读者可局部理解而无需通读全部文档；写 ADR 的过程本身即是一次结构化思考，常能暴露分歧、促成澄清与共识。

§5工程 · 怎么落地

将 ADR 置于源仓库（如 doc/adr）与代码同版本控制，用 Markdown 等轻量标记以便评审、检索与 diff；只记录 architecturally significant 决策（影响结构、非功能特性、依赖、接口或构造技术），避免沦为流水账。团队应约定谁有权写、何时写、如何评审与合并，并在架构评审、迭代回顾或重大技术选型时生成 ADR；新旧决策用链接形成可追溯的决策图，取代关系一目了然。对容易过时的决策设置复核提醒，把 ADR 当作活的决策账本而非一次性文档。实践中可先在一两个模块试点模板，再扩展为全组织约定，并用 lint 或目录结构保证编号连续、状态字段合法、链接不悬挂。当决策被推翻时，应新增记录并在理由中引用旧记录，形成可阅读的决策链。对跨团队共享的决策，还应明确 owner 与失效条件，使他人能在上下文变化时判断是否需要重开讨论。

§6权衡卡

收益 · 正确姿势

归根结底，ADR 的收益取决于团队是否真的在决策时查阅它，而非产出了多少文件。

代价 · 风险

逐决策记录在决策频繁时会产生文档负担，过度细化会退化为流水账；只写结论不写理由的 ADR 则失去全部价值。

反例 · 误区

反例：把 ADR 当作静态设计文档一次性写完，或将被取代的记录直接改写删除，都会破坏决策溯源，使后人无法区分「当前有效决策」与「历史权衡」。

第二个反例是追求形式化模板而忽略实质内容，团队为填表而写、逐渐厌倦维护，最终整个机制荒废；第三个反例是把 ADR 当作审批关卡，使记录变成官僚负担而非学习工具。

原文要点
  • ADR 只负责记录，不保证决策正确：文档完备也可能掩盖错误判断，需配合评审与定期复核，否则信心会被「写下来了」本身误导。
  • 因此是否引入 ADR 及其详细程度，应视团队规模、系统寿命与合规要求而定，小项目可只记录少数关键决策。

权衡原文仅按显式标记词归栏引用（收益 / 代价 / 反例），其余句子按原序列为「原文要点」；内容逐字引用未改写。

§7学习路径条

MTH-G-02质量属性场景与ATAM→MTH-G-01架构决策记录

§8案例带

CAS-X-01 · 经 MTH-G-05

去中心化聊天架构逆向

对一个仅有 58 份设计文档、尚未实现的开源去中心化聊天项目做架构逆向：从设计文本提炼 18 个模块及其依赖关系，重建模块依赖 DAG 与三条核心数据流 DAG，并输出全景理解与深度需求分析。

CAS-X-02 · 2 跳派生：当前节点 → ESS-O-02 → ESS-G-05

网申填写扩展逆向架构

对 Chrome MV3 网申自动填写扩展的逆向架构分析：梳理 popup、content、background、options 四模块职责，解剖 12 个站点适配器、双通道消息协议与隐私脱敏机制，并评估其零依赖零构建选型。

CAS-X-05 · 2 跳派生：当前节点 → ESS-O-02 → ESS-G-03

preset 通道耦合分析

对 harness「委派工具层→续用管理器→preset 服务→MCP 服务器」这条通道做耦合分析：识别契约、服务定位、数据契约、组合语义、路径与装配一致性六类耦合点，定位「静默丢弃特化」与「装配漂移」两处实质缝隙。

CAS-X-08 · 2 跳派生：当前节点 → ESS-O-02 → ESS-G-03

dsh-manager 插件深度分析

以「编译依赖、运行时注入、组合装配」三硬依据加源码行号，对第三方插件做依赖、功能、需求溯源与设计问题裁决，并复用上游 DAG 知识库节点标识，使分析结果可与主图互查。

CAS-X-09 · 经 MTH-G-05

harness 源码架构解析

对 deepseek-harness 官方源码做分层解析：镜像官方架构文档，按九个层与九十余模块建立文档集群，产出跨层联动矩阵与七条关键路径，并钉住「模型可见即已记录」、能力缝三角等设计不变量。

CAS-X-10 · 经 MTH-G-05

dsh 插件依赖增量定位

以官方插件 DAG 为蓝本，对一个官方清单之外的全新社区插件做功能定位与依赖位置增量分析，产出可下钻交互依赖图与多形态文档的源码级架构逆向案例。

CAS-X-11 · 2 跳派生：当前节点 → ESS-O-02 → ESS-G-05

Hermes 七层架构总览

对八千余文件的工业级 AI Agent 项目做七层架构总览逆向，揭示其「越用越聪明」的自进化闭环如何在层间传导的控制型架构案例。

CAS-X-12 · 2 跳派生：当前节点 → ESS-O-02 → MTH-O-03

MCP 四件套选型对比

对四个同类 MCP 服务器做源码级能力与成本对比，并以常驻 token 预算为轴给出分级接入策略的技术选型实战案例。

CAS-X-13 · 经 MTH-G-05

Claude Code 架构逆向

以社区逆向源码、系统提示词与官方文档三源交叉验证，还原一个商业 Agent 的查询引擎、子Agent、工具与权限体系的逆向分析案例。

CAS-X-15 · 经 MTH-G-05

Open Code Review 图谱

对阿里开源 AI 代码审查 CLI 做源码级解析并构建「知识 + 实践资产 + AI 索引」三合一知识图谱的工程案例。

CAS-X-16 · 2 跳派生：当前节点 → ESS-O-02 → MTH-O-05

控制理论⊗Agent 设计

将控制理论五维（负反馈 / 状态估计 / PID / 鲁棒 / 分层）系统映射到 Agent 工程环节，并以真实产品案例验证的跨学科方法论案例。

§9信源与核验

核验状态True（verified）
置信度high
复核日期2026-10-12
生命周期active
规范信源WEB-004、WEB-005、STD-001、BK-013
书证核验BK-013 Ch6.5.1 Why Document Architectural Decisions?（direct），Ch6.5.2 A Template for Documenting Architectural Decisions（direct），Ch6.5.4 Which Decisions to Document（direct），Ch6.5.5 The Payback for Documenting Architectural Decisions（direct）
入口链接https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions　https://martinfowler.com/bliki/ArchitectureDecisionRecord.html
勘误
常见误解：ADR 是长篇架构设计文档
核验结论：ADR 是记录单个 architecturally significant decision 的短文本文件（1–2 页），含 Title/Context/Decision/Status/Consequences，与完整架构描述互补而非替代　[WEB-004]
勘误
常见误解：决策变化时应直接修改原 ADR
核验结论：应保留旧 ADR 并标 superseded 链接到新 ADR，单调编号不复用，以保留决策演化史　[WEB-005]

§10原始关系清单

展开：本节点的全部原始关系边（4 条，含边 ID 与方向）
关系方向对端节点说明
组合→ MTH-G-03架构风格选择方法
E-210		风格选型结果以 ADR 记录理由与被否决项
组合→ MTH-G-05架构文档化方法
E-726		决策记录与文档化方法共同承载架构决策与理由
依据推导→ ESS-O-02架构即权衡
E-201		决策记录依架构即权衡，留存取舍与理由
前置依赖← MTH-G-02质量属性场景与ATAM
E-208		识别敏感点与权衡点是记录架构决策的前提