SuperAPI AI 工具集

architecture-decision-record

编程与开发

查看项目

更新于 10-16 08:25

技能介绍

用途

Architecture Decision Record(ADR)技能用于帮助团队创建和维护架构决策记录。ADR 是轻量级文档,用于记录重要架构决策及其背景与后果。该技能适用于以下场景:做出重大技术选型(数据库、框架、云服务商)、设计系统架构或主要组件、为团队建立模式或约定、评估多种方案之间的权衡、记录会影响未来开发的决策。

为什么 ADR 重要

ADR 充当团队的架构记忆:

  • 背景保留:记录决策的原因,而不仅仅是决定了什么。
  • 新人上手:帮助新成员理解架构背后的理由。
  • 避免重复讨论:避免对已定决策的无休止争论。
  • 追踪演进:观察架构如何随时间演变。
  • 责任明确:清晰的所有权与决策时间线。

ADR 格式(Nygard 模板)

每条 ADR 应遵循以下结构:

  1. 标题:格式为 ADR-####: [决策标题],例如 ADR-0001: Adopt Microservices Architecture。
  2. 状态:决策的当前状态,包括 Proposed(考虑中)、Accepted(已批准并实施)、Superseded(被后续决策取代,需引用 ADR 编号)、Deprecated(不再推荐但尚未被取代)、Rejected(考虑过但未采纳,需记录原因)。
  3. 背景:问题陈述或机会、业务/技术约束、干系人需求、系统当前状态、起作用的力量(相互冲突的关注点)。
  4. 决策:所做的选择、要遵循的关键原则或模式、由此带来的变化、谁负责实施。要求具体且可执行,例如“我们将采用基于 Node.js 与 Express 的微服务架构”,而非“我们将考虑使用微服务”。
  5. 后果:正面结果(收益)、负面结果(成本、风险、权衡)、中性结果(发生变化但无明显好坏)。
  6. 备选方案:至少记录 2 个备选方案,说明每个方案是什么、为何被考虑、为何未被选中。
  7. 参考(可选):会议记录或讨论线程、相关 ADR、外部研究或文章、概念验证实现。

ADR 生命周期

Proposed → Accepted → [Implemented] →(最终)Superseded/Deprecated;Proposed 也可能走向 Rejected。

最佳实践

  1. 保持 ADR 不可变:一旦接受,不要编辑 ADR,而是创建取代旧 ADR 的新 ADR。例如创建 ADR-0015 取代 ADR-0003,而非更新 ADR-0003。
  2. 使用现在时书写:ADR 是历史记录,写作时如同决策正在当下做出。例如“我们将采用微服务”,而非“我们采用了微服务”。
  3. 聚焦“为什么”而非“如何”:ADR 记录决策,而非实现细节。例如“我们选择 PostgreSQL 以获得关系一致性”,而非“用这些具体设置配置 PostgreSQL……”。
  4. 团队评审 ADR:在接受前获取相关干系人的意见,包括架构师(技术可行性)、开发者(实现可行性)、产品(业务对齐)、DevOps(运维关注点)。
  5. 顺序编号:使用 4 位零填充数字,如 ADR-0001、ADR-0002 等;即使有多个项目也保持单一序列。
  6. 存入 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。