mcpField
A
architecture-decision-record

architecture-decision-record

github.com/validkeys开发175 次安装21 周前更新
代码仓库

关于 architecture-decision-record

该技能从 technical-requirements.yaml 提取架构决策，并生成独立的 ADR 文件和索引。适用于需要记录设计取舍、支持项目交接与审查的团队。

主要功能

  1. 01提取并筛选架构决策
  2. 02整理决策备选方案
  3. 03生成编号 ADR 文件
  4. 04创建 ADR 索引与差距分析

适用场景

  1. 01将技术需求转为可审阅的 ADR
  2. 02为新成员说明架构取舍
  3. 03识别需求中尚未覆盖的决策领域

安装

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

$npx skills add https://github.com/validkeys/sherpy --skill architecture-decision-record

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

包含的文件

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

references/
adr-document-spec.md
adr-index-spec.md
example-ADR-001.md
example-ADR-003.md
example-INDEX.md

详细介绍

架构决策记录

从 technical-requirements.yaml 中提取关键架构决策，并将每项决策整理为独立的 ADR 文件。ADR 记录系统为何采用当前的构建方式，而不仅仅记录选择了什么，因此对于新成员入门、审计和重新审视权衡至关重要。

前置条件

  • {base_directory}/requirements/technical-requirements.yaml（由 /technical-requirements-interview 生成）

用法

/architecture-decision-record [base-directory]

如果未提供目录，则在当前目录中查找 requirements/technical-requirements.yaml，并自动检测目录。

如果未找到，则提示用户：“你的需求文档位于何处？”

等待用户提供路径后再继续。将其存储为 base_directory。

流程

步骤 1：确定基础目录并加载技术需求

如果未提供目录参数，则检查当前目录中是否存在 requirements/technical-requirements.yaml。

  • 如果找到，则将当前目录用作 base_directory
  • 如果未找到，则提示：“你的需求文档位于何处？”并等待用户回复

确定 base_directory 后，读取 {base_directory}/requirements/technical-requirements.yaml，并找出每个决策点。检查以下部分：

  • architecture — 模式、框架、结构选择
  • technology_stack — 语言、运行时、主要库、数据库
  • data_model — 存储引擎选择、架构设计决策
  • api_design — REST、GraphQL 或 RPC，版本策略
  • security — 身份验证机制、令牌策略、加密方案
  • testing — 测试策略、覆盖率目标、工具
  • deployment — 托管、CI/CD 管道、容器化
  • trade_offs 和 open_questions — 明确标记的决策

将每项决策收集为候选 ADR。符合以下任一条件的决策均符合要求：

  • 涉及在多个备选方案之间作出有意义的选择，或
  • 对系统未来的灵活性有显著影响，或
  • 被明确标记为权衡事项或待解决问题
步骤 2：确定备选方案

针对每项候选决策，推断实际可行的备选方案。可参考以下来源：

  • 技术需求中的 trade_offs 部分（如果存在）
  • 所选技术或模式的常见备选方案
  • 需求中任何表示“考虑过的选项”的措辞

如果无法推断备选方案，请注明“未记录备选方案”，而不要凭空编造。

步骤 3：分配 ADR ID 和标题

从 ADR-001 开始，按顺序为 ADR 编号。标题应简短且明确：

  • 好：使用 PostgreSQL 作为主数据存储
  • 不好：数据库决策

按逻辑对相关决策分组（例如，先列出所有身份验证决策，再列出所有部署决策）。

步骤 4：编写 ADR 文件

创建目录结构：

mkdir -p {base_directory}/architecture/adrs

每个 ADR 编写一个文件：{base_directory}/architecture/adrs/ADR-NNN-kebab-case-title.md

每个文件均采用以下格式：

ADR 文档包括：标题栏（ADR-NNN: Title、Status、Date、Source），以及四个必需部分：Context（问题描述）、Decision（所作选择）、Alternatives Considered（已排除选项表格）和 Consequences（正面影响、负面影响／权衡、风险）。

完整的 ADR 文档规范（包含所有部分和格式规则）请参阅 references/adr-document-spec.md。

完整示例请参阅 references/example-ADR-001.md 和 references/example-ADR-003.md。

步骤 5：编写 INDEX.md

创建 {base_directory}/architecture/adrs/INDEX.md，作为汇总表：

索引包含一个表格，列为：ID（链接）、Title、Status、Date。

完整的 INDEX 规范请参阅 references/adr-index-spec.md。

完整示例请参阅 references/example-INDEX.md。

步骤 6：差距分析

生成所有文件后，直接报告：

## ADR Gap Analysis

**Project:** [name]
**ADRs Generated:** [n]

**Decision Areas Covered:**
[✓ / ✗] Architecture / structural patterns
[✓ / ✗] Technology stack
[✓ / ✗] Data storage
[✓ / ✗] API design
[✓ / ✗] Security / authentication
[✓ / ✗] Testing strategy
[✓ / ✗] Deployment / infrastructure

**Open Questions carried forward:** [n]
[List any open_questions from technical-requirements.yaml that could not yet be
formalized as Accepted ADRs — these are candidates for future ADRs.]

**Recommendations:** [none / list]

输出格式

{base_directory}/architecture/adrs/
  INDEX.md
  ADR-001-[title].md
  ADR-002-[title].md
  ...

输出示例

示例 ADR 文件（ADR-001、ADR-003）和 INDEX.md 请参见 references/。

评论

支持 Markdown