mcpField
A
adr-drafting

adr-drafting

github.com/giuseppe-trisciuoglio开发3653.5k 次安装7 周前更新
代码仓库

关于 adr-drafting

adr-drafting 是用于创建新架构决策记录的技能，适合需要记录技术选择及其权衡的团队。它会检查仓库现有规范，并在获批后生成 Markdown 文件。

主要功能

  1. 01确认决策记录所需信息
  2. 02检查仓库中的 ADR 规范
  3. 03按标准章节起草记录
  4. 04获批后创建 Markdown 文件
  5. 05仅处理新的 ADR

适用场景

  1. 01记录重要架构变更的理由
  2. 02为新 ADR 确定文件位置与编号

安装

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

$npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill adr-drafting

安装后在 Claude Code 中输入/adr-drafting确认已加载。

附带文件references/examples.mdreferences/template.md

详细介绍

ADR 起草

为重大的架构选择创建新的架构决策记录（ADR）文档，帮助团队清晰记录重要技术决策背后的原因。

概述

此技能可帮助你从调研到最终的 Markdown 文件，完成新的 ADR。它会确认决策详情、检查代码库中是否已有 ADR 规范，并起草包含标准章节 Title、Status、Context、Decision 和 Consequences 的新 ADR。

如果代码库尚无 ADR 规范，默认将 ADR 存放在 docs/architecture/adr，并使用带前导零的文件名，例如 0001-use-postgresql-for-primary-database.md。

请参阅 references/template.md 获取默认 ADR 模板，并参阅 references/examples.md 查看 ADR 示例和命名模式。

适用场景

当用户或 Agent 已决定进行有意义的架构变更，并需要通过新的架构决策记录来说明其理由、所选方向和权衡时，请使用此技能。适用于创建 ADR、记录架构决策、编写决策记录，或留存重要技术选择背后的项目历史等请求。

操作说明

阶段 1：确认 ADR 输入信息

向用户询问起草新 ADR 所需的最少信息：

  1. 决策标题
  2. 决策状态（如果尚未最终确定，默认为 Proposed）
  3. 背景：推动该决策的问题、限制条件或影响因素
  4. 决策：所选方案
  5. 后果：哪些方面会变得更容易、更困难、风险更高或成本更高
  6. 确认此请求是要创建新 ADR，而不是编辑现有 ADR
  7. 如果文档语言不明确，确认所需的代码库文档语言
  8. 确认是否必须沿用现有的 ADR 命名规范

如果用户实际上希望更新现有 ADR、更改较早 ADR 的状态，或管理取代关系链接，请说明此技能只负责起草新的 ADR 文档，并询问他们是否要改为创建一份新记录。

阶段 2：查找代码库中的 ADR 规范

起草前先检查代码库：

  1. 搜索可能存放 ADR 的位置，例如：
    • docs/architecture/adr
    • docs/adr
    • adr
    • architecture/adr
  2. 如果已有 ADR 文件，阅读一至三个示例，以推断：
    • 编号格式
    • 文件名模式
    • 标题格式
    • 语言和语气
  3. 如果不存在 ADR 目录，建议使用 docs/architecture/adr
  4. 尽可能根据现有文件确定下一个 ADR 编号
  5. 如果此前没有 ADR，从 0001 开始

在尚无规范时，首选的默认命名方式：

  • 目录：docs/architecture/adr
  • 文件名：NNNN-short-kebab-title.md
  • 标题：# ADR-NNNN: <Decision Title>
阶段 3：起草 ADR

使用以下标准结构起草：

# ADR-NNNN: Decision Title

## Status
Proposed

## Context
What problem, constraints, or trade-offs led to this decision?

## Decision
What architectural choice was made?

## Consequences
What becomes easier, harder, riskier, or more expensive because of this decision?

起草规则：

  • 标题应具体，并明确体现决策
  • 补充足够的背景，解释为何需要该决策
  • 清晰、直接地记录所选方向
  • 在已知的情况下，写明正面和负面后果
  • 不得编造用户未提供的理由、限制条件或结果
  • 如果缺少关键信息，应插入简洁的占位内容，或在定稿前提出后续问题
阶段 4：与用户审阅草稿

写入文件前，提供以下内容：

  • 建议的文件路径
  • 建议的标题
  • ADR 状态
  • 对已起草章节的简要预览

在创建文件前征求批准。如果用户希望调整，应先修改草稿。

阶段 5：创建 ADR 文件

获得批准后：

  1. 如果 ADR 目录不存在，则创建该目录
  2. 在仓库已有惯例的情况下，按照该惯例编写 ADR Markdown 文件
  3. 尽可能保留用户对决策理由的原有表述，同时确保文档简洁
  4. 报告最终文件路径，并概述所创建的内容
  5. 创建新的 ADR 文件后即停止，让此技能专注于单个新的决策记录

示例

示例 1：新的数据库决策

用户请求：“创建一份 ADR，记录从 SQLite 迁移到 PostgreSQL 的决定”

预期流程：

  1. 确认标题、状态、变更原因和预期影响
  2. 检查仓库中是否已有 ADR 文件
  3. 按照现有惯例起草新的 ADR；如果没有惯例，则默认使用 docs/architecture/adr/0001-move-to-postgresql.md
  4. 写入文件前征求批准
示例 2：新的服务边界

用户请求：“记录将账单拆分为独立服务的决定”

预期流程：

  1. 询问架构背景，以及当前设计为何不够理想
  2. 确认所选边界及其运营影响
  3. 按标准章节起草新的 ADR
  4. 仅在用户批准后创建文件

更长的 ADR 示例请参阅 references/examples.md。

最佳实践

  • 每份 ADR 专注于一项架构决策
  • 如果已有 ADR，则遵循仓库现有的命名、编号和写作风格
  • 优先采用简洁说明，避免冗长叙述
  • 如实记录权衡取舍，包括缺点和新风险
  • 除非用户确认其他状态，否则默认将状态设为 Proposed
  • 如果能明确判断，则使用仓库首选的文档语言

约束与警告

  • 此技能仅用于创建新的 ADR
  • 不要更新现有 ADR 文件、状态历史或取代关系链
  • 不要编造缺失的理由或影响
  • 如果仓库已使用其他 ADR 位置，则不要强行使用 docs/architecture/adr
  • 如果决策、背景或影响过于模糊，无法负责任地记录，请提出澄清问题

评论

支持 Markdown