mcpField
D
doc-adr

doc-adr

github.com/vladm3105开发1751 次安装1 天前更新
代码仓库

关于 doc-adr

doc-adr 是用于编写和检查架构决策记录的 Skill，每份记录聚焦一项决策。它按背景、决策与后果组织内容，并规定备选方案、追溯关系和就绪度检查。

主要功能

  1. 01单项决策记录结构
  2. 02背景、决策与后果
  3. 03备选方案比较指引
  4. 04上游标签与追溯关系
  5. 05基于模板的验证

适用场景

  1. 01记录技术选择及其理由
  2. 02实施前比较不同方案
  3. 03为后续 SPEC 工作准备决策

安装

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

$npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-adr

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

详细介绍

doc-adr

用途

创建一份架构决策记录（ADR）——SDD 工作流的第 5 层。 ADR 使用“背景—决策—后果”模式记录一项架构决策：为什么需要该决策、选择了什么、权衡过哪些替代方案，以及接受了哪些后果。

层级：第 5 层——连接容器（PRD）与组件（SPEC）的决策桥梁；ADR 本身不是 C4 层级。 上游：EARS、BDD（遵循必要上游契约；通过 @ 标签链可传递追溯到上游 PRD/BRD）。 下游：SPEC → TDD → IPLAN → Code。

每份 ADR 都只涉及一项决策。出现新的架构选择时，应新建一份 ADR（ADR-02、ADR-03……），而不是扩展现有 ADR；使用 @depends: ADR-NN 关联它们。

适用场景

以下情况适用 doc-adr：

  • BRD §8 / PRD §14 中的架构主题需要记录决策。
  • 需要在多个替代方案中选择技术、模式或集成方式。
  • 需要记录长期架构选择的理由和后果。

如需根据上游制品或提示词端到端生成，请使用 ../doc-adr-autopilot/SKILL.md。如需规划项目所需的 ADR 集合，请参阅 ../adr-roadmap/SKILL.md。

前置条件

ADR 属于第 5 层，因此在编写前，请确认所需的上游制品（EARS + BDD）已存在，并阅读规范：

  1. 模板（事实来源）： ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml
  2. 层级 README： ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md
  3. ID 和标签标准： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  4. 编写风格： ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

确认所需的上游制品：ls docs/0{3,4}_*/ 2>/dev/null（EARS 和 BDD）。仅引用已存在的文档；切勿臆造 ADR-XXX 之类的占位符，也不要引用尚不存在的 SPEC 编号。确认 ID 无冲突：ls docs/05_ADR/ 2>/dev/null。通过 EARS/BDD 的 @ 标签链可传递追溯到上游 PRD/BRD。

层级指南

状态生命周期（ADR 特有）

ADR 使用Proposed → Accepted → Deprecated → Superseded，而非 Draft/In Review/Approved。状态与 SPEC-Ready 评分对应：

状态SPEC-Ready含义
Proposed70–89%正在评估的决策
Accepted≥90%已批准，可用于 SPEC
Deprecated—不再相关（保留作历史记录）
Superseded—已被更新的 ADR 取代（附上链接）
必需结构（10 个编号章节 + 术语表 + 附录后置内容）

document_control 是第 1 节（状态、日期、决策者、作者、 originating_topic → PRD §14、brd_reference、SPEC-Ready 评分、修订 历史）。随后依次为：

  1. 背景（问题陈述、业务驱动因素、约束、技术背景）· 3. 决策（选定的解决方案、关键组件、MVP/下一周期范围）·
  2. 考虑过的替代方案（选定方案加上 2–3 个被否决的方案，每个方案均列出优缺点；被否决的方案须指出具体的否决因素，成本和契合度可选）· 5. 后果（积极结果、权衡/风险及严重程度；如果决策涉及支出，还需给出成本估算）· 6. 架构流程（图示 + 集成点）· 7. 实施评估（阶段、回滚、监控基线）· 8. 验证（成功标准、BDD 交叉引用）· 9. 可追溯性 · 10. 相关决策。

还必须包含术语表（glossary: 键）和附录（appendix: 键），作为必需的后置内容（不编号）。章节编号和标识符取自 ADR-TEMPLATE.yaml 自带的 # Section N: 编号——模板是事实来源。

各章节的内容要求和编写 _antipatterns 请参阅 ADR-TEMPLATE.yaml。

元素 ID 和标签
  • 元素 ID（在 ADR 内）： ADR.{doc_id}.{section_id}.{hash}（例如 ADR.01.03.e5b1）。为每个元素生成一个稳定的 4 位十六进制标识符，并确保其在所属章节内唯一（HASH01）；发生冲突时扩展为 8 位。在此提示词中不要计算 SHA-256——哈希形式是由确定性工具流程生成的规范化目标，而精确到字节的字段提取仅针对 BRD §7 定义（ADR 在 Phase 2+ 中处理）。权威依据：framework/governance/ID_NAMING_STANDARDS.md。 不存在数字类型代码——元素的类型由其所在章节决定。
  • ADR 是文档级工件。 引用时使用连字符形式 ADR-NN，绝不使用带点的元素 ID。自标记为 @adr: ADR-NN （例如 @adr: ADR-033）；交叉链接使用 @depends: ADR-NN 和 @discoverability: ADR-NN (rationale)。
  • 必需的上游标签（Layer 5）： @ears @bdd——两者都必须提供（依据必要上游约定），并使用各自上游的元素 ID 形式 （@ears: EARS.01.03.5e2a、@bdd: BDD.01.03.8f4c）。通过 EARS/BDD 的 @-标签链可追溯上游 PRD/BRD 血缘关系——不要在 ADR 元素上添加 @brd:/@prd:。
  • 已移除的模式（不要使用）：DEC-XXX、ALT-XXX、CON-XXX、旧版 3 段式 ADR.NN.xxxx、数字类型代码段，以及 3 位数的 ADR-NNN。

创建流程

  1. 确认主题——一项决策，追溯至 PRD §14 的起始主题和 BRD §8 的驱动因素。
  2. 预留 ID——下一个可用的 ADR-NN（两位数，仅在需要时扩展： ADR-01、ADR-99、ADR-102）。 按层独立（CLEANUP-PR-F 条目 18）： 在你所在层的索引中选取下一个可用编号——上游的编号不是你的编号 （文档编号按层依次递增且相互独立；参见 framework/governance/ID_NAMING_STANDARDS.md §Cross-layer cardinality）。
  3. 创建嵌套文件夹——每个 ADR 都存放在 docs/05_ADR/ADR-NN_{slug}/ 中。单文件形式：其中的 ADR-NN_{slug}.md； 分章节形式（>25 KB）：ADR-NN.S_{section}.md，并从 ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-00_index.TEMPLATE.md 创建索引。
  4. 先完成文档控制（第 1 节），然后根据模板完成 §2–§10、词汇表和附录末尾内容。
  5. 在所选方案旁评估 2–3 个备选方案（使 options: 包含 3–4 项）——为每个被否决的方案说明否决理由，并指出具体的不合格因素。每个方案的 estimated_cost/fit 均为可选；如果已有更完整的调研，则在 prior_analysis 中引用，而不是重复陈述。明确给出决策及其理由。
  6. 添加必需的上游标签 @ears @bdd；添加 @adr: ADR-NN 自标签及任何 @depends: 交叉链接。
  7. 在同一次更改中更新 ADR 索引 docs/05_ADR/ADR-00_index.md。 8.验证（见下文），并将 ADR 和索引一并提交。

验证

此技能就是验证器（无运行时代码）。针对 ${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md 和 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md 进行检查。

  • Document Control 是第一节；状态为 Proposed/Accepted/Deprecated/Superseded 之一。
  • 10 个章节均存在且非空；恰好有一个决策。
  • 所选方案旁边列出 2–3 个被否决的备选方案，每个方案都包含优点/缺点以及具体的否决因素。成本和适配性可选；应引用已有调研，而非重述。
  • 后果涵盖积极结果和权衡（含严重程度）；仅当决策涉及支出时才提供成本估算。
  • 元素 ID 符合 ADR.NN.SS.xxxx；文档引用使用连字符形式 ADR-NN；不得包含已移除的模式。
  • 存在必需的上游标签 @ears @bdd（依据必要上游契约）；自标签为 @adr: ADR-NN。
  • 若状态为 Accepted，SPEC-Ready 评分 ≥ 90。
  • 图示契约：Architecture-Flow 章节包含决策／交互序列图（@diagram: sequence-*），依据 ${CLAUDE_PLUGIN_ROOT}/framework/governance/DIAGRAM_STANDARDS.md — ADR 是决策桥接层，因此不使用 C4 层级（请使用 ../charts-flow/SKILL.md）；索引已更新；无失效链接。
代码含义严重程度
XDOC-002缺少必需的上游标签error
XDOC-006标签格式无效error
XDOC-008内部链接失效error
XDOC-009缺少可追溯性章节error

**质量门禁（阻断性）：**继续前，SPEC-Ready 评分必须达到 ≥ 90/100。若发现问题，请修复并重新检查；若无法修复，则记录下来以供人工审核。

ADR-REF 文档（ADR-REF-NN_{slug}.md，通过 ../doc-ref/SKILL.md）是自由格式的参考目标，不受 Ready 评分、必需上游标签和质量门禁的约束。

下一个技能

../doc-spec/SKILL.md — SPEC 会通过 @adr: ADR-NN 引用此 ADR，并带上自身必需的上游标签 @ears @bdd，将决策转化为组件接口、数据模型和行为契约。

适配

读取 .aidoc/profile.yaml；仅遵循此技能的配置项 （section_toggles、glossary）。忽略未知键；若无配置文件，则使用框架默认值。依据文件： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

相关资源

  • 模板／编写规则：${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-TEMPLATE.yaml
  • 层 README：${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md
  • 索引模板：${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/ADR-00_index.TEMPLATE.md
  • ID 与标签标准：${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  • 质量门禁：../doc-adr-audit/SKILL.md · 修复：../doc-adr-fixer/SKILL.md
  • 生成流水线：../doc-adr-autopilot/SKILL.md
  • 决策规划：../adr-roadmap/SKILL.md

快速参考

用途记录一项架构决策（Context-Decision-Consequences）
层级5（决策桥接层：PRD → SPEC）
上游标签@ears @bdd（依据必要上游契约）
自引用连字符形式 @adr: ADR-NN（文档级）
元素 IDADR.NN.SS.xxxx（仅限内部元素）
状态Proposed → Accepted → Deprecated → Superseded
必须包含Document Control（第一节）、10 个章节、所选方案旁的 2–3 个备选方案
下一步doc-spec

评论

支持 Markdown