架构决策记录（ADR）实践指南：使用decision-kit提升团队决策质量

1. 项目概述：一个为决策过程赋能的工具包

在软件开发、产品设计乃至日常的项目管理中，我们每天都在做决策。小到选择今天用哪个库来处理HTTP请求，大到决定产品的核心架构和未来的技术路线。很多时候，这些决策依赖于个人或团队的经验、直觉，甚至是临时的讨论，缺乏结构化的记录和可追溯的依据。这就导致了一个常见问题：几个月后，当我们需要回顾“当初为什么选择A方案而不是B方案”时，往往只剩下模糊的记忆和零散的聊天记录，决策的上下文和关键权衡点早已丢失。

jnemargut/decision-kit正是为了解决这个问题而生。它不是一个复杂的决策支持系统，而是一个轻量级、开源的“决策记录工具包”。它的核心思想非常简单：为每一个重要的技术或产品决策，创建一份结构化的、可版本控制的文档。你可以把它理解为给“决策”这个抽象过程，建立了一套像代码一样的“提交日志”和“文档规范”。

这个工具包适合任何需要记录和沟通决策的团队或个人，尤其是技术负责人、架构师、产品经理和项目经理。它不强制你使用任何特定的决策框架，而是提供了一套基础的模板和工具，帮助你开始实践“架构决策记录”（Architecture Decision Record, ADR）或类似的轻量级方法。通过使用它，你可以确保团队的关键选择有据可查，新成员能快速了解项目的历史脉络，并且在未来需要调整方向时，能清晰地知道当初的约束条件和假设是否已经发生变化。

2. 决策记录的核心价值与常见误区

在深入拆解decision-kit之前，我们有必要先厘清“记录决策”这件事本身的价值，以及实践中容易踏入的误区。很多团队一开始热情高涨，要求每个改动都写决策记录，结果很快因为流程繁琐而放弃。或者，记录变成了形式主义，内容空洞，除了增加负担外毫无用处。

2.1 为什么我们迫切需要记录决策？

第一，保存决策上下文，对抗“组织失忆”。一个项目运行一两年后，最初的成员可能已经离职或调岗。新接手的工程师面对一个看似“奇怪”的代码实现或架构选择时，如果没有当时的决策记录，他要么需要花费大量时间考古（翻看古老的PR、会议纪要），要么可能在不了解历史原因的情况下，贸然进行“优化”，反而引入了新的问题。一份好的决策记录，能清晰地说明当时面临的选项、各自的优缺点、所做的权衡以及最终的选择，相当于为项目留下了一份“设计图纸”和“建造日志”。

第二，促进结构化思考，提升决策质量。当你知道需要把思考过程写下来供他人审阅时，你会不自觉地更深入、更全面地考虑问题。你会被迫去列举更多的备选方案，更客观地分析每个方案的利弊，而不是依赖直觉拍脑袋。这个过程本身就是一个极好的思维训练，能有效减少决策的盲目性和随意性。

第三，建立可追溯的沟通基线。在跨团队协作中，决策记录是一个绝佳的沟通工具。它提供了一个中立的、事实性的讨论基础。当有分歧时，大家可以回到决策记录，看当时的假设是否成立，约束是否改变，而不是陷入“我觉得”、“你认为”的无休止争论。它让决策过程从“黑盒”变为“白盒”。

2.2 实践中必须避开的几个“坑”

注意：记录决策的初衷是提效，而非制造官僚主义。以下几点是许多团队踩过的雷区。

坑一：事无巨细，记录一切。不是每个微小的选择都需要一份正式的决策记录。为“是否使用let还是const”写ADR是荒谬的。决策记录应该聚焦于那些有长期影响、涉及权衡、且未来可能被质疑或需要重新评估的决策。例如：选择微服务还是单体架构、选用React还是Vue作为前端框架、决定自研还是采购某个核心组件。

坑二：记录变成“事后补票”。决策应该在做出时或做出后立即记录，此时记忆最清晰，上下文最完整。如果等项目上线几个月后再来“回忆”和“补写”，不仅费时费力，而且很容易失真，失去了记录的意义。

坑三：内容空洞，流于形式。只写结论“我们决定用MongoDB”，而不写“为什么”。一份合格的记录必须包含：状态（提议/已接受/已弃用）、决策背景、考虑的方案、决策结果、以及最重要的——决策依据。没有依据的记录只是一纸空文。

坑四：写完后束之高阁。决策记录不是墓碑，而是活文档。当项目的技术环境、业务需求或团队认知发生变化时，当初决策的前提可能已不复存在。这时，应该启动对旧决策的重新评估，并更新记录的状态（例如标记为“已过时”或“被取代”），甚至可以链接到新的决策记录。建立定期回顾决策的机制，是发挥其最大价值的关键。

decision-kit的设计哲学，正是为了帮助团队规避这些陷阱，以一种轻量、可持续的方式，将决策记录的好习惯融入开发流程。

3.decision-kit工具包深度解析与快速上手

jnemargut/decision-kit项目本身结构清晰，目标明确。它不是一个庞大的Web应用，而是一套基于文本文件的规范和配套脚本工具。这种设计使其具有极低的接入成本和极高的灵活性，可以无缝集成到任何基于Git的版本控制工作流中。

3.1 项目结构与核心组件

典型的decision-kit仓库会包含以下核心部分：

1. templates/(模板目录)：这是工具包的心脏。里面通常提供了多种Markdown格式的决策记录模板。最常见的是基于MADR（Markdown Architecture Decision Records）或轻量级ADR的模板。一个基础的模板可能包含以下章节：

   • Title（标题）：简短描述决策，如“ADR-001: 使用PostgreSQL作为主数据库”。
   • Status（状态）：提议、已接受、已弃用、已过时。
   • Context（背景）：为什么要做这个决策？问题是什么？有什么约束条件？（技术债、团队技能、截止日期等）。
   • Decision（决策）：我们决定做什么？用一句清晰的话说明。
   • Consequences（结果）：这个决定会带来什么？包括好的和坏的影响。这是对未来维护者的重要提示。
   • Alternatives Considered（考虑的备选方案）：我们考虑了哪些其他方案？为什么否决了它们？
   • References（参考）：链接到相关的讨论、Issue、PR、文档等。

2. scripts/(脚本目录)：包含一些自动化脚本，例如：

   • create-adr.sh或new-decision.js：用于快速从模板生成一个新的决策记录文件，并自动填充序号、日期等元信息。
   • list-adrs.sh：列出所有决策记录及其状态，生成一个摘要目录。

3. docs/或decisions/(记录存放目录)：所有生成的决策记录Markdown文件都集中存放在这里。通常按数字序号（如0001-use-postgresql.md）或日期排序。

4. README.md：项目的使用说明，解释了理念、快速入门指南和贡献方式。

3.2 五分钟快速集成到你的项目

假设你有一个现有的Git项目，想立刻开始使用decision-kit，可以遵循以下步骤：

步骤1：引入决策工具包最直接的方式是将其作为子模块（git submodule）添加到你的项目中，或者直接复制templates/和scripts/目录到你的项目根目录下的一个文件夹（例如.decision-kit/）。子模块的方式便于同步上游更新。

# 在你的项目根目录下执行 git submodule add https://github.com/jnemargut/decision-kit.git .decision-kit

步骤2：创建决策记录目录在你的项目文档区（例如docs/下）创建一个architecture/decisions/目录，用于存放所有决策记录。

mkdir -p docs/architecture/decisions

步骤3：尝试创建你的第一份决策记录使用工具包提供的脚本（这里以假设的bash脚本为例）：

# 进入工具包脚本目录 cd .decision-kit/scripts # 运行创建脚本，指定标题和输出路径 ./create-adr.sh "使用容器化部署方案" ../docs/architecture/decisions/

脚本会自动从模板复制一份新文件，命名为类似0001-use-containerized-deployment.md，并在文件内部预填充了结构，你只需要用编辑器打开，填写具体内容即可。

步骤4：将决策记录纳入版本控制像对待源代码一样，将新创建的决策记录文件提交到Git。

git add docs/architecture/decisions/0001-use-containerized-deployment.md git commit -m “docs(adr): 添加关于容器化部署的决策记录 [ADR-001]”

至此，决策记录流程已经和你的代码开发流程绑定在一起。每次重要的架构或技术决策，都伴随这样一份可追溯的文档。

3.3 模板定制：让它更适合你的团队

decision-kit提供的默认模板是一个很好的起点，但最好的模板是适合自己团队文化的模板。我强烈建议你在使用几周后，根据团队的反馈对模板进行定制。

常见的定制点包括：

• 增加Drivers（驱动因素）部分：在Context之前，明确列出促成这次决策的核心驱动因素，例如：“性能要求达到每秒1000请求”、“开发团队对Go语言更熟悉”、“必须在三个月内上线MVP”。这能让决策背景更具象。
• 增加Compliance（合规性）部分：如果项目受安全、数据隐私等法规约束，可以增加此部分，说明决策如何满足合规要求。
• 简化Alternatives部分：如果团队觉得列举所有备选方案负担太重，可以调整为只记录被认真考虑过的前2-3个主要方案。
• 增加Validation（验证）部分：记录如何验证这个决策是有效的，例如通过性能压测结果、用户A/B测试数据等。这对于后续回顾非常有价值。

定制模板的过程，本身就是一次关于“如何更好地做决策”的团队讨论，其价值甚至超过工具本身。

4. 高级实践：将决策记录融入团队工作流

工具易得，习惯难养。要让决策记录从“一个好东西”变成“团队的自然习惯”，需要将其巧妙地嵌入到现有的开发流程中，而不是作为一个额外的、孤立的任务。

4.1 与项目管理工具（如Jira, GitHub Issues）集成

决策通常起源于一个具体的问题或需求。最好的实践是，让决策记录与对应的工单（Issue）或用户故事（User Story）强关联。

• 在Issue中发起讨论：当遇到一个需要重大技术决策的Issue时（例如，“如何实现高并发的文件上传？”），首先在Issue评论区进行初步的技术讨论，列举几个可能的方向。
• 创建决策记录：当讨论趋于一致，或需要拍板时，负责人运行脚本创建决策记录。在记录中，Context部分可以直接引用该Issue链接，References部分也可以链接到相关的评论。
• 闭环反馈：决策记录完成后，将文件的链接贴回原始Issue，并关闭或标记该Issue。这样，整个决策链路就完整地记录在了项目管理系统里。未来任何人查看这个Issue，都能一目了然地看到最终的解决方案及其背后的完整思考。

4.2 在代码审查（Code Review）中引用决策记录

这是强化决策记录权威性和实用性的关键一环。当你在Review一个Pull Request时，如果发现代码实现与某份已通过的决策记录相悖，或者涉及一个新的、未记录的架构变更，你应该立即提出。

• 对于违背已有决策的代码：评论可以这样写：“这里的实现似乎采用了方案B，但我们在ADR-002中已经明确选择了方案A，理由是XXX。请确认是ADR需要更新，还是代码需要调整？”
• 对于引入新架构变更的代码：评论可以这样写：“这个PR引入了一个新的缓存层，这是一个有长期影响的架构变更。我建议我们先创建一份决策记录（例如ADR-005），描述选择Redis而不是Memcached的原因，待记录通过后再合并代码。这有助于团队知识同步。”

通过将决策记录作为CR的“法律依据”，你不仅提升了代码质量，也极大地推广了决策记录文化。

4.3 建立决策记录的维护与回顾机制

决策记录不是“一锤子买卖”。我建议团队建立两种轻量级的定期回顾机制：

1. 季度架构回顾会：每个季度，花1-2小时，快速过一遍所有状态为“已接受”的决策记录。重点讨论两个问题：

   • 前提是否依然成立？当时决策所依赖的技术条件、业务假设、团队能力是否发生了变化？（例如，某个当初不成熟的云服务现在已变得稳定且便宜）。
   • 结果是否符合预期？决策带来的正面和负面影响，哪些预测对了，哪些没料到？ 如果发现前提已变，可以将旧决策标记为“已过时”，并启动新决策流程。这个过程能有效防止技术栈和架构僵化。

2. 新成员入职必读清单：将最重要的5-10份决策记录作为新成员的技术入职资料。让他们在熟悉代码前，先了解项目的“设计哲学”和关键抉择的历史，这能帮助他们更快地理解代码背后的“为什么”，加速融入团队。

5. 实战案例：一个微服务通信协议的决策全过程

让我们通过一个虚构但非常典型的案例，来看decision-kit如何在实际项目中发挥作用。

项目背景：我们正在开发一个电商平台“ShopFast”，最初是单体应用。随着业务增长，我们决定拆分为用户、商品、订单、支付等多个微服务。现在，我们需要决定服务间采用何种通信协议。

第一步：识别决策点，创建记录我们意识到这是一个典型的、有长期影响的架构决策。技术负责人运行命令：./create-adr.sh “微服务间通信协议选型” docs/decisions/生成文件0003-service-communication-protocol.md。

第二步：填写决策记录我们召集了一次简短的设计会议，并基于讨论结果填写了记录：

# ADR-003: 微服务间通信协议选型 **状态**: 已接受 **决定日期**: 2023-10-27 ## 背景 (Context) “ShopFast”系统正在从单体架构向微服务架构迁移。服务之间需要进行大量的数据交换（如：下单时需要调用用户服务验证、调用商品服务锁库存、调用支付服务）。我们需要选择一个高效、可靠、易于开发和维护的通信协议。 **驱动因素**: 1. 开发效率：团队对技术的熟悉度。 2. 性能：内部服务调用延迟要低，吞吐量要高。 3. 可维护性：协议应清晰、易于调试和问题排查。 4. 生态系统：与我们将要使用的服务网格、监控工具等的集成度。 ## 考虑的方案 (Alternatives Considered) ### 方案A: RESTful HTTP/JSON * **优点**： * 通用性强，几乎所有语言和框架都支持。 * 易于调试，使用curl、浏览器或Postman即可测试。 * 技术门槛低，团队非常熟悉。 * **缺点**： * 性能相对较低（文本序列化、HTTP头开销）。 * 缺乏严格的接口契约，容易产生前后端不一致。 * 对于复杂的查询或操作，API设计可能变得笨重。 ### 方案B: gRPC (基于HTTP/2和Protocol Buffers) * **优点**： * 高性能，二进制编码，多路复用，延迟低。 * 强类型接口定义（.proto文件），天生具备API契约，生成客户端/服务端代码，减少错误。 * 支持流式通信等高级特性。 * **缺点**： * 对浏览器支持不直接（需要通过grpc-web网关）。 * 二进制格式对人类不友好，调试相对复杂（需要专用工具）。 * 团队需要学习新的技术栈（.proto语法，gRPC生态）。 ### 方案C: 异步消息（如RabbitMQ, Apache Kafka） * **优点**： * 解耦彻底，发送方无需知道接收方状态。 * 天然支持削峰填谷、流量缓冲。 * 易于实现事件驱动架构和最终一致性。 * **缺点**： * 系统复杂性增加，需要引入和维护消息中间件。 * 调试和问题追踪链路更长。 * 不适合需要同步响应的请求/响应模式。 ## 决策 (Decision) 我们决定采用 **混合模式**： 1. **对于核心的、需要同步实时响应的服务间调用（如：下单流程中的验证和库存锁定），采用 gRPC**。以牺牲少量调试便利性，换取更高的性能和更强的接口约束，这对于核心交易链路至关重要。 2. **对于非核心的、事件驱动的、或可异步处理的数据同步（如：订单创建后发送邮件通知、更新搜索引擎索引），采用异步消息（Apache Kafka）**。以实现系统解耦和流量缓冲。 3. **暂时不使用纯RESTful HTTP作为服务间通信的主要协议**。 ## 依据 (Rationale) 1. **性能与可靠性是核心链路的首要考量**。gRPC在性能上的优势明显，且强类型契约能减少联调错误，从长期看提升了开发效率和系统稳定性。调试困难可以通过引入服务网格（如Istio）的分布式追踪来缓解。 2. **系统解耦是微服务的重要目标**。引入Kafka处理异步场景，符合架构演进方向，能为未来实现更复杂的事件驱动架构打下基础。 3. **团队学习成本可控**。gRPC和Kafka的学习曲线虽然存在，但它们是云原生领域的标准组件，掌握它们对团队长期技术成长有利。我们可以通过组织内部技术分享和创建示例项目来加速学习。 ## 结果 (Consequences) ### 正面影响 * 核心链路性能得到提升，延迟降低。 * 接口定义更加清晰，减少了潜在的集成错误。 * 系统架构更清晰，同步与异步边界明确。 * 团队掌握了gRPC和Kafka两项重要技术。 ### 负面影响 * 初期开发效率会略有下降，需要学习新工具。 * 需要引入额外的基础设施（Kafka集群），并关注其运维。 * 问题排查需要依赖更专业的监控和追踪工具（如Jaeger）。 * 需要编写和维护`.proto`文件。 ## 参考 (References) * Issue #45: “研究微服务间通信技术选型” * 设计会议纪要链接 * gRPC官方文档 * 《微服务设计模式》相关章节

第三步：决策落地与后续这份记录被提交到代码库。之后：

• 新的服务脚手架模板中，默认集成了gRPC和Kafka客户端的配置。
• 在实现“下单”服务时，开发人员明确知道调用用户服务要用gRPC，而发送订单创建事件要用Kafka。
• 当有新同事质疑“为什么不用简单的HTTP”时，我们直接引导他阅读ADR-003。
• 半年后，当我们评估服务网格时，发现gRPC与Istio的集成度非常好，这验证了当初决策的前瞻性。

这个案例展示了，一份清晰的决策记录如何将一次会议讨论，转化为可长期指导团队行动的“架构宪法”。

6. 常见问题与排查技巧实录

即使有了好工具，在推行决策记录文化的初期，你依然会遇到各种阻力或困惑。以下是我在实践中总结的一些典型问题及其应对策略。

Q1：团队觉得写这个太麻烦，耽误编码时间，怎么办？A1：这是最常见的阻力。关键在于降低启动门槛和凸显即时价值。

• 降低门槛：强调只记录“重要”决策（见2.2坑一）。提供极其便捷的创建脚本（一键生成）。模板要简单，初期甚至可以只包含“背景、方案、决定、依据”四个必填项。
• 凸显价值：在下次有人问“我们当初为啥这么干？”的时候，主动、快速地甩出一份决策记录链接。在代码评审中，用决策记录作为讨论依据，让大家亲眼看到它能减少沟通成本、避免重复讨论。让工具自己证明其价值，比任何说教都管用。

Q2：决策记录应该由谁来写？A2：谁主导决策，谁负责撰写初稿。通常是该问题的技术负责人或架构师。但这不意味着是“一个人的事”。初稿完成后，应该发起一个简单的审阅流程（例如，在团队频道分享链接，或创建一个轻量的审阅PR），邀请相关干系人（产品、测试、其他资深工程师）补充意见。这样既保证了质量，也达成了共识。

Q3：决策记录和技术设计文档（Tech Spec）有什么区别？A3：两者互补，但侧重点不同。

• 决策记录（ADR）：聚焦于在多个可行方案中做出选择，并记录为什么这么选。它更关注权衡和理由。篇幅相对较短。
• 技术设计文档：描述被选中的方案具体如何实现。它包含详细的系统设计、API定义、数据模型、流程图、测试策略等。篇幅通常较长。
  • 关系：一份技术设计文档的开头，应该引用相关的决策记录，说明这个设计是基于哪个关键决策。而决策记录的References部分，可以链接到详细的设计文档。先有决策，再有详细设计。

Q4：如何处理错误的决策？A4：决策记录不怕记录“错误”，怕的是记录“僵化”。当发现一个已接受的决策有问题时：

1. 不要直接删除或修改原记录。这会破坏历史追溯性。
2. 创建一份新的决策记录，标题可以是“取代ADR-XXX：关于XXX的新决策”。
3. 在新记录的Context中，明确指出旧决策（ADR-XXX）的不足或前提变化。
4. 将旧记录的状态更新为“已弃用”或“已过时”，并在其末尾添加一行：“被 [新决策记录链接] 取代”。
5. 这样，历史脉络被完整保留，任何人都能清楚看到演变的逻辑。

Q5：决策记录应该放在项目仓库的什么位置？A5：必须放在项目代码仓库内，与代码一起版本控制。这是核心原则。常见位置有：

• docs/architecture/decisions/（清晰，与其它架构文档放在一起）
• docs/adr/（更简洁）
• 对于非常注重文档的项目，甚至可以放在根目录的.arch/目录下。 绝对不要放在Confluence、Google Docs等与代码库分离的地方，否则极易失去同步。

推行决策记录，本质上是在推行一种更严谨、更透明、更负责任的技术工作文化。jnemargut/decision-kit提供了一把好用的“锄头”，但能否开垦出肥沃的“土地”，取决于团队是否愿意一起投入耕耘。从我个人的经验来看，初期可能会有些许不适，但一旦习惯养成，你会发现它在提升团队技术决策质量、加速新人融入、减少技术债务争议方面带来的回报，远超那一点点书写的时间成本。