mcpField
A
architecture-decision-record

architecture-decision-record

github.com/yonatangross开发2991.5k 次安装今天更新
代码仓库

关于 architecture-decision-record

Architecture Decision Records 是帮助团队记录重要软件架构选择的技能，提供 ADR 结构、生命周期指导、模板和生成脚本，用于整理背景、决策、备选方案及后果。

主要功能

  1. 01结构化 ADR 章节与模板
  2. 02决策生命周期指导
  3. 03备选方案与后果分析
  4. 04脚本辅助生成 ADR

适用场景

  1. 01记录技术选型
  2. 02比较架构方案
  3. 03为团队入职保留决策依据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/yonatangross/orchestkit --skill architecture-decision-record

安装后在 Claude Code 中输入/architecture-decision-record确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

test-cases.json
assets/
adr-template.md
checklists/
adr-review-checklist.md
examples/
adr-0001-adopt-microservices.md
adr-0002-choose-postgresql.md
adr-0003-api-versioning-strategy.md
references/
adr-best-practices.md
rules/
_sections.md
_template.md
interrogation-reliability.md
interrogation-scalability.md
interrogation-security.md
scripts/
adr-frontmatter.yaml
adr-manager.py
create-adr.md
list-adrs.py

详细介绍

架构决策记录

架构决策记录（ADR）是轻量级文档，用于记录重要的架构决策及其背景和影响。这项技能提供了模板、示例和最佳实践，帮助你在项目中创建和维护 ADR。

概览

  • 做出重大的技术选择（数据库、框架、云服务提供商）
  • 设计系统架构或主要组件
  • 为团队确立模式或规范
  • 评估多种方案之间的权衡
  • 记录会影响未来开发的决策

ADR 的重要性

ADR 是团队的架构记忆：

  • 保留背景信息：记录做出决策的原因，而不只是记录决策内容
  • 帮助新成员入职：帮助新团队成员理解架构决策的理由
  • 避免重复讨论：避免对已确定的决策无休止地争论
  • 追踪演进：了解架构如何随时间演进
  • 明确责任：清楚记录负责人和决策时间线

ADR 格式（Nygard 模板）

每份 ADR 都应遵循以下结构：

1. 标题

格式：ADR-####: [Decision Title] 示例：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] → (Eventually) Superseded/Deprecated
          ↓
      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，便于阅读
  • 分支：与实现所在分支相同

快速入门清单

选项 1：使用脚本增强型生成器（推荐）
  • 运行 /create-adr [number] [title]，生成自动填充上下文的 ADR
  • 自动填充 ADR 编号、日期和作者
  • 检查并填写决策详情
  • 将状态设为「Proposed」，并与团队评审
选项 2：使用静态模板
  • 从 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 万以上并发用户，且延迟要求低于 50 毫秒……」

相关技能

  • ork:api-design：设计 ADR 中引用的 API 时使用
  • ork:database-patterns：ADR 涉及数据库选择时使用
  • security-checklist：ADR 涉及安全影响时参考

技能版本：2.0.0 最后更新：2026-01-08 维护者：OrchestKit

能力详情

adr-creation

关键词： adr，架构决策，决策记录，记录决策 解决的问题：

  • 如何记录架构决策？
  • 创建 ADR
  • 架构决策模板
adr-best-practices

关键词： 何时编写 adr，adr 生命周期，adr 工作流，adr 流程，adr 评审，量化影响 解决的问题：

  • 何时应该编写 ADR？
  • 如何管理 ADR 生命周期？
  • ADR 的评审流程是什么？
  • 如何量化决策影响？
  • 应避免哪些 ADR 反模式？
  • 链接相关 ADR
tradeoff-analysis

关键词： 权衡，优缺点，备选方案，比较，评估选项 解决的问题：

  • 如何分析权衡？
  • 比较架构选项
  • 记录考虑过的备选方案
consequences

关键词： 后果，影响，风险，收益，结果 解决的问题：

  • 此决策会带来哪些后果？
  • 记录决策影响
  • 风险和收益分析

评论

支持 Markdown