ADR 团队协作八问：从「谁能创建」到「原则如何介入」的架构决策记录工作指南

本文以 architecture-decision-record 仓库的 ADR 团队协作问题清单（西班牙语版）为核心骨架，围绕八组团队协作问题逐一展开：谁可以创建 ADR、什么情况下值得写/不值得写、生命周期如何流转、阶段门槛如何判定、角色与责任如何划分、治理层级如何设计、以及哪些组织原则会影响 ADR 的运作。读完本文，你将获得一套可直接照抄到团队 Wiki、代码库decisions/目录或协作文档中的「问题清单 + 示例答案」模板，并理解每类问题背后与源码、模板、示例 ADR 对应的落地依据。

为什么团队要用「问题清单」来约定 ADR

架构决策记录（Architecture Decision Record, ADR）的价值不在于把决策「记下来」，而在于让团队围绕「为什么要这样做」进行对话。正如仓库主文档 README 所定义的：ADR 是一份记录重要架构决策及其上下文（context）与后果（consequences）的文档。当它沦为事后补交的强制文书时就没有价值——这一点在 团队协作建议 中被反复强调。

因此，与其直接向团队下发一份「必须写 ADR」的制度，不如先让团队坐在一起回答一组结构化的问题。这些问题的作用是：

• 统一认知：让「什么算值得记录的决策」从个人直觉变成团队共识；
• 建立可复制的流程：把创建、评审、投票、维护、退役变成明确的步骤；
• 划分权责：明确谁能发起、谁能批准、谁来维护、谁来定期复审；
• 对齐原则：让 ADR 的运作方式与组织的领导力原则、风险偏好、保密要求一致。

这套思路在仓库中有直接对应物：Claude Code 的 architecture-decision-record-skill 第一步就是「判断这个决策是否值得写 ADR」，第二步「查找或创建adr/、decisions/目录」，其 写作指南 更是把「团队协作注意事项」列为一等公民。也就是说，问题清单不仅是管理建议，它已经渗透到了本仓库提供的自动化能力中。

问题一：谁可以创建 ADR？

需要考虑的方面

• 组织中的具体个人、具体角色、具体团队或具体部门是否被允许创建 ADR？
• 是否存在可以「委托」（commission）ADR 的人——即自己不写、但有权要求他人代写？

示例答案（可直接参考）

我们组织中任何阅读过架构决策记录 README 页面的人都可以提出 ADR，也就是说，任何人都可以开始起草并与团队分享。

这个示例答案刻意保持了「低门槛」：把准入条件定为「读过 README」而不是「某个职级」。它的好处是让 ADR 成为自下而上的工具，而非自上而下的审批流。仓库的 AWS ADR 流程文档 proceso-de-registros-de-decisiones-de-arquitectura-de-aws 也印证了这一取向：「任何团队成员都可以创建 ADR，但团队必须为 ADR 建立所有权定义（ownership）」，作者即所有者，负责主动维护和沟通 ADR 内容。

在落地时，你还可以在答案中补充「委托」通道，例如：产品负责人或技术负责人可以委托某位工程师代写某个技术选型 ADR，并在文档中注明委托人与受托人。

问题二：什么情况值得撰写 ADR？

需要考虑的方面

判断「值得写」不能只盯着技术，而要综合以下维度：

• 组织内团队的工作方式（ways of working）；
• 软件系统的结构；
• 跨团队协调的复杂度；
• 长期可维护性；
• 外部接口的稳定性；
• 你希望这份决策最终让谁受益。

示例答案（可直接参考）

当我们希望未来的开发者能理解我们做这件事的「为什么」时，我们就会创建 ADR。

「未来的开发者理解为什么」是 ADR 最核心的诉求。它对应 写作指南 中的判定标准：只要未来开发者需要理解「为什么」，就值得写；以及「决策具有架构意义、跨团队、或难以逆转」同样值得写。

仓库中的示例 ADR 可以帮你直观理解「什么算值得写」。例如 monorepo-frente-a-multirepo 记录的是代码组织方式这一影响深远的结构性选择，它同时写清了「Asunto（主题）/Decisión（决策）/Estado（状态）」与「Supuestos（假设）/Restricciones（约束）/Posiciones（立场）/Argumento（论证）/Implicaciones（影响）」等完整要素——这正是「值得写」的决策应有的信息密度。

问题三：什么情况不值得撰写 ADR？

需要考虑的方面

识别「不值得写」同样重要，它防止 ADR 沦为噪音。请从这些角度排查：

• 非架构决策：与架构无关；
• 微小决策：风险极低、自成一体（self-contained）、仅涉及单个开发者；
• 已被覆盖的决策：标准、政策或文档中已经完整覆盖；
• 临时性决策：临时绕行方案（workaround）、概念验证（proof of concept）、实验（experiment）。

示例答案（可直接参考）

当一个决策的范围、时间、风险和成本都有限，或者它已经被其他文档覆盖时，我们会跳过 ADR。

这与 写作指南 的「跳过标准」完全一致：不写 ADR 的情形包括「非架构性的、微小的（低风险、自包含、单人决策）」「已被现有标准/政策/文档覆盖」「临时性的——绕行方案、概念验证或实验」。

一个实用的判断技巧（来自 skill 文档）：如果你不确定，就问「这个决策是什么？未来谁需要理解它的为什么？」——通常一问就有答案。如果决策只是一行能被 linter 或风格指南覆盖的写法偏好，那就不需要 ADR。

问题四：ADR 的生命周期是什么？

需要考虑的方面

• 创建过程、调研过程、决策过程、实施过程、退役（sunsetting）过程分别是什么样？
• 如何随时间追踪ADR 的生命周期，例如如何让 ADR 从一个状态流转到下一个状态？
• 如何把状态变化同步给相关干系人？

示例答案（可直接参考）

我们希望 ADR 拥有五个生命周期阶段：Inicio（发起）→ Investigación（调研）→ Evaluación（评估）→ Implementación（实施）→ Mantenimiento（维护）→ Retiro（退役）。

注意示例答案写的是「五个阶段」却列出了六个节点——这正是清单类文档的常见形态，你可以根据团队实际取舍。仓库中 AWS ADR 流程文档给出了另一种同样成立的状态机：Propuesto（Proposed，已提议）→ Aceptado（Accepted，已接受）/ Rechazado（Rejected，已拒绝）→ Sustituido（Superseded，已被取代），并明确「一旦团队接受 ADR，它就变得不可变；如果新知识要求不同决策，团队提出新 ADR，新 ADR 被接受后取代旧 ADR」。

两种模型可以组合使用：用「发起→调研→评估→实施→维护→退役」描述工作流推进，用「Proposed / Accepted / Rejected / Superseded」描述文档状态。Nygard 模板 plantilla-de-registro-de-decisión-de-michael-nygard 对状态的提问是「Estado（状态）：是 propuesto（已提议）、aceptado（已接受）、rechazado（已拒绝）、obsoleto（已废弃）还是 sustituido（已被取代）？」——直接把状态枚举写进了模板，你可以在自己团队的 ADR 文件头部照抄这一行。

问题五：生命周期各阶段的判定标准是什么？

需要考虑的方面

阶段门禁（gate）本质上是验收标准：你怎么知道一份 ADR 已经「足够好」，可以进入下一阶段？请用这些检查项自问：

• 问题是否被清晰表达？
• 是否考虑了备选方案？
• 权衡取舍（trade-offs）是否被充分理解并记录？
• 所有相关上下文是否齐备？
• 所有相关干系人是否参与？
• 所有反馈是否已纳入？

示例答案（可直接参考）

我们希望当活跃团队已经做到以下四点后，干系人对 ADR 进行投票：1）完成调研；2）完成评估；3）向干系人发布 ADR 提案并附上意见征集请求和一周的时间盒（timebox）；4）所有干系人意见均已纳入并处理。

这个示例答案的亮点在于它把「什么时候投票」变成了可验证的清单而非感觉：调研完成、评估完成、发布并留出一周窗口、反馈闭环。你可以在此基础上调整：把「一周」改成符合团队节奏的「两个工作日」或「两个迭代周期」，并在提案里写明投票规则（如简单多数、一致同意、或按治理层级加权）。

写作指南 提供的验收问题与上面完全同构：问题是否清晰阐述？备选方案是否真的被考虑？权衡是否被充分理解和记录？上下文是否齐备、所有相关干系人是否参与？所有反馈是否已纳入？——这意味着即使不用本仓库，你也可以把这组问题直接抄进自己的评审模板。

问题六：哪些角色与责任与 ADR 互动？

需要考虑的方面

• 角色：proponente（提议人）、investigador（调研人）、evaluador（评估人）、revisor（评审人）、aprobador（批准人）、mantenedor（维护人）等；
• 责任：与干系人沟通、确保期望得到满足、在网站或内网发布、定期复审（尤其在有重大变化发生时）。

示例答案（可直接参考）

我们希望每份 ADR 始终有一位主要联系人、一位次要联系人和一个负责团队；他们负责沟通、发布、维护、每年至少一次的定期复审，以及必要时最终的退役。

「主联系人 + 次联系人 + 负责团队」是一个极简但完整的问责模型：既不会把责任压到单个人身上（有后备），又不会散到没人负责（有明确团队）。写作指南 给出的简化版本与此一致：「为每份 ADR 指定主要联系人、次要联系人和负责团队，负责沟通、发布、维护、定期复审（例如每年至少一次）以及最终的退役」。

AWS ADR 流程文档则补充了「所有权」维度的细节：ADR 所有者必须主动维护和沟通内容；接受前内容若有变更须经所有者批准；若团队给出改进意见，ADR 保持「Proposed」状态，所有者制定行动项并分配负责人，且由所有者负责重新安排评审；若团队拒绝，所有者须写明拒绝理由，并把状态改为「Rejected」，以避免未来重复讨论同一话题。

问题七：治理（governance）如何与 ADR 互动？

需要考虑的方面

• 组织的工作方式；
• 特殊的合规需求（例如法律或人力资源方面的要求）；
• 如何处理共识 vs 冲突 vs 升级（escalation）；
• 是否存在比其他人更有影响力的领域、个人或团队——例如有权批准、投票或否决 ADR？

示例答案（可直接参考）

ADR 的治理遵循以下优先级顺序：CEO → CTO → CLO → 实施该 ADR 的团队 → 团队中最了解该架构决策的专家。除非 ADR 中另有描述，其他任何人都不拥有治理权。

这份示例答案给出了一个「显式权力列表」：它把治理权收敛到五个层级，并明确「除非 ADR 中另有说明，否则其他人没有治理权」。这样设计的好处是可预期：任何人在评审一份 ADR 时都能一眼看出谁有权拍板、谁有权否决，从而避免「会议室政治」式的无限升级。

落地建议：把这条写进团队 ADR 模板的头部或独立治理文档，并规定「ADR 中可以自述特殊治理安排」这一逃生通道。CLO（首席法务官）出现在列表中，提醒你在治理设计时要考虑合规视角，而非只考虑技术视角。

问题八：哪些原则与 ADR 互动？

需要考虑的方面

组织的「工作方式」通常包含一组左右决策质量的对立张力：

• 快速前进 vs 缓慢前进；
• 决策上追求共识 vs 允许冲突；
• 风险偏好 vs 安全偏好；
• 公开讨论 vs 私下讨论；
• 以及诸如此类的其他权衡。

示例答案（可直接参考）

我们采用以下领导力原则：偏向行动（bias for action）、异议后承诺（disagree-and-commit）、对易于逆转和易于隔离的决策，70% 的把握估算就足够好（70% estimates are good enough），以及公开的工作方式——但组织保密协议中描述的机密信息除外。

这份示例答案实际上给了你一套可以逐条落地的原则：

• 偏向行动：不要因为追求完美而拖延决策；
• disagree-and-commit：允许分歧充分表达，但一旦决定就全力执行；
• 70% 把握足够好：对低风险、易逆转、可隔离的决策降低证据门槛，从而保持速度；
• 默认公开、例外保密：除保密协议规定的机密信息外，工作与讨论默认公开。

把这些原则写进 ADR 治理文档后，它们可以直接充当「问题二/问题三」的加速器：符合 70% 标准且易逆转的决策可以跳过重流程；涉及机密信息的决策自动进入私密通道。

综合落地：把八问组织成一份团队 ADR 工作章程

八组问题各自独立，但组合起来就是一份完整的团队 ADR 工作章程。建议按以下结构整理成团队文档（可直接复制到decisions/或 Wiki）：

配套的工程化落地手段包括：

• 命名与目录：按 命名约定 使用「现在时祈使短语 + 小写连字符 +.md」的文件名（如choose-database.md、format-timestamps.md），放在adr/或decisions/目录；若项目采用编号制，可加零填充序号（如0007-choose-database.md）；
• AI 辅助写作与维护：本仓库提供 Claude Code skill，见 skills/architecture-decision-record-skill/SKILL.md，它内置了「判断是否值得写、建目录、命名、选模板、写 Context/Decision/Consequences」的完整流程，可直接拷贝到.claude/skills/使用；
• 不可变 vs 活文档：默认「接受后不可变」，新信息以带日期戳的增补方式加入，或用新 ADR 取代旧 ADR（旧 ADR 状态改为Superseded by ...，新 ADR 注明Supersedes ...）；若团队偏好「活文档」风格，也可以在原 ADR 中追加带日期戳和「决策后到达」说明的新信息，但要在项目内保持一致并写明采用哪种约定；
• 与代码评审联动：把 ADR 引用进代码评审——评审者发现代码变更违反某 ADR 时，要求作者修正并附上 ADR 链接（详见 AWS 流程）；需要更强约束的团队可引入 PR 守护工具（如 ADR Guard、Decision Guardian，见 README）。

结语：问题清单是团队对话的起点，而非终点

八组问题之所以有效，是因为它们把「ADT 该怎么做」从模糊的期望变成了可以逐条回答、逐条投票、逐条修订的具体条目。每个问题都附带「需要考虑的方面」和「示例答案」两层：前者保证思考不遗漏维度，后者保证讨论有一个可反驳、可修改的起点。

建议团队第一次使用时：每人先独立写下自己的答案，再对照示例答案逐条讨论，把分歧点记录下来——那些分歧点往往正是最值得写 ADR 的架构议题。讨论结束后，把收敛后的答案固化进团队文档与 ADR 模板，并每年（或每半年）像复审 ADR 一样复审这份章程本身，让它与团队一起进化。