用途
Architecture Decision Record(ADR)技能用于帮助团队创建和维护架构决策记录。ADR 是轻量级文档,用于记录重要架构决策及其背景与后果。该技能适用于以下场景:做出重大技术选型(数据库、框架、云服务商)、设计系统架构或主要组件、为团队建立模式或约定、评估多种方案之间的权衡、记录会影响未来开发的决策。
为什么 ADR 重要
ADR 充当团队的架构记忆:
- 背景保留:记录决策的原因,而不仅仅是决定了什么。
- 新人上手:帮助新成员理解架构背后的理由。
- 避免重复讨论:避免对已定决策的无休止争论。
- 追踪演进:观察架构如何随时间演变。
- 责任明确:清晰的所有权与决策时间线。
ADR 格式(Nygard 模板)
每条 ADR 应遵循以下结构:
- 标题:格式为 ADR-####: [决策标题],例如 ADR-0001: Adopt Microservices Architecture。
- 状态:决策的当前状态,包括 Proposed(考虑中)、Accepted(已批准并实施)、Superseded(被后续决策取代,需引用 ADR 编号)、Deprecated(不再推荐但尚未被取代)、Rejected(考虑过但未采纳,需记录原因)。
- 背景:问题陈述或机会、业务/技术约束、干系人需求、系统当前状态、起作用的力量(相互冲突的关注点)。
- 决策:所做的选择、要遵循的关键原则或模式、由此带来的变化、谁负责实施。要求具体且可执行,例如“我们将采用基于 Node.js 与 Express 的微服务架构”,而非“我们将考虑使用微服务”。
- 后果:正面结果(收益)、负面结果(成本、风险、权衡)、中性结果(发生变化但无明显好坏)。
- 备选方案:至少记录 2 个备选方案,说明每个方案是什么、为何被考虑、为何未被选中。
- 参考(可选):会议记录或讨论线程、相关 ADR、外部研究或文章、概念验证实现。
ADR 生命周期
Proposed → Accepted → [Implemented] →(最终)Superseded/Deprecated;Proposed 也可能走向 Rejected。
最佳实践
- 保持 ADR 不可变:一旦接受,不要编辑 ADR,而是创建取代旧 ADR 的新 ADR。例如创建 ADR-0015 取代 ADR-0003,而非更新 ADR-0003。
- 使用现在时书写:ADR 是历史记录,写作时如同决策正在当下做出。例如“我们将采用微服务”,而非“我们采用了微服务”。
- 聚焦“为什么”而非“如何”:ADR 记录决策,而非实现细节。例如“我们选择 PostgreSQL 以获得关系一致性”,而非“用这些具体设置配置 PostgreSQL……”。
- 团队评审 ADR:在接受前获取相关干系人的意见,包括架构师(技术可行性)、开发者(实现可行性)、产品(业务对齐)、DevOps(运维关注点)。
- 顺序编号:使用 4 位零填充数字,如 ADR-0001、ADR-0002 等;即使有多个项目也保持单一序列。
- 存入 Git:将 ADR 与代码一起纳入版本控制,位置如 /docs/adr/ 或 /architecture/decisions/,格式为 Markdown,分支与实现相同。
快速上手清单
方式一:使用脚本增强生成器(推荐)
- 运行 /create-adr [number] [title] 生成自动填充背景的 ADR。
- ADR 编号、日期与作者自动填充。
- 审阅并填写决策细节。
- 将状态设为“Proposed”并与团队评审。
方式二:使用静态模板
- 从 assets/adr-template.md 复制 ADR 模板。
- 分配下一个顺序编号(检查现有 ADR)。
- 填写背景:问题、约束、需求。
- 记录决策:什么、为什么、如何、谁。
- 列出后果:正面、负面、中性。
- 描述至少 2 个备选方案:是什么、优缺点、为何未选。
- 添加参考:讨论、研究、相关 ADR。
- 将状态设为“Proposed”。
- 与团队评审。
- 批准后将状态更新为“Accepted”。
- 在实现 PR 中链接该 ADR。
- 部署后将状态更新为“Implemented”。
可用脚本
- scripts/create-adr.md:动态 ADR 生成器,自动填充背景。自动填充 ADR 编号、日期、作者、ADR 总数;用法为 /create-adr [number] [title];使用 $ARGUMENTS 与 !command 获取动态上下文。
- assets/adr-template.md:供手动使用的静态模板。
规则速查
- interrogation-scalability(高):规模问题、数据量、增长预测。
- interrogation-reliability(高):数据模式、UX 影响、一致性验证。
- interrogation-security(高):访问控制、租户隔离、攻击面。
常见陷阱
- 过于技术化:“我们将使用 Kubernetes 和这 50 个 YAML 配置……”;正确层级:“我们将使用 Kubernetes 进行容器编排,因为……”。
- 过于模糊:“我们将使用更好的数据库”;应具体:“我们将使用 PostgreSQL 15+ 处理事务数据,因为……”。
- 没有备选方案:只记录所选方案;应做比较:记录为何未选其他方案。
- 缺少后果:只列收益;应平衡:诚实说明成本与权衡。
- 没有背景:“我们决定使用 Redis”;应有背景:“鉴于我们 100 万以上并发用户和低于 50ms 的延迟要求……”。
相关技能
- ork:api-design:设计 ADR 中引用的 API 时使用。
- ork:database-patterns:ADR 涉及数据库选择时使用。
- security-checklist:ADR 有安全影响时参考。
能力细节
- adr-creation:关键词包括 adr、architecture decision、decision record、document decision;解决如何记录架构决策、创建 ADR、架构决策模板等问题。
- adr-best-practices:关键词包括 when to write adr、adr lifecycle、adr workflow、adr process、adr review、quantify impact;解决何时写 ADR、如何管理 ADR 生命周期、ADR 评审流程、如何量化决策影响、要避免的 ADR 反模式、关联相关 ADR 等问题。
- tradeoff-analysis:关键词包括 tradeoff、pros cons、alternatives、comparison、evaluate options;解决如何分析权衡、比较架构选项、记录备选方案等问题。
- consequences:关键词包括 consequence、impact、risk、benefit、outcome;解决该决策的后果是什么、记录决策影响、风险与收益分析等问题。
技能版本:2.0.0;最后更新:2026-01-08;维护方:OrchestKit。