mcpField
D
doc-spec

doc-spec

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

关于 doc-spec

doc-spec 是 SDD 工作流中的技能，用于为单个软件组件编写 YAML 技术规格。它依据上游 ADR、EARS 和 BDD 定义组件接口、数据模型与行为，为 TDD 和实现做准备。

主要功能

  1. 01创建组件级 YAML 规格
  2. 02定义类型化接口和数据模型
  3. 03依据 EARS 与 BDD 描述行为
  4. 04落实必需结构与可追溯标签
  5. 05检查图表和阈值要求

适用场景

  1. 01架构决策确定后编写组件规格
  2. 02将验收契约转为接口与行为
  3. 03编写 TDD 用例前准备规格文档

安装

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

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

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

详细介绍

doc-spec

用途

创建一份技术规格（SPEC）——SDD 流程的第 6 层。SPEC 是针对单个软件组件、可直接用于实现的 C4-L3（组件）契约，描述其接口、数据模型和行为，并在任何下游测试或代码编写之前完成。

层级：6 — 统一规格。SPEC 整合了旧版本中拆分为组件／数据／UX／风险／流程规格的内容；现在每个组件只有一份 SPEC 产物。 上游：EARS、BDD、ADR（遵循必要上游契约；ADR 是主要来源。上游 PRD／BRD 的脉络可通过 @ 标签链传递追溯）。 下游：TDD → IPLAN → Code。

适用场景

在以下情况下使用 doc-spec：

  • 架构决策（ADR）已确定，需要为组件编写规格。
  • 将 EARS／BDD 验收契约转化为具体接口、数据模型和行为规则。
  • 需要在编写 TDD 测试用例前，准备好可直接用于实现的契约。

如需从 BDD／ADR、提示词或 IPLAN 端到端生成，请使用 ../doc-spec-autopilot/SKILL.md。

前置条件

SPEC 位于第 6 层，因此请先确认所需的上游产物（EARS、BDD、ADR）均已存在，再开始编写。只引用已存在的文档；绝不要编造 SPEC-XXX 或 ADR-XXX 之类的占位符。开始编写前，请阅读：

  1. 模板（权威来源）： ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml
  2. 层级 README： ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md
  3. ID 与标签规范： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  4. 编写风格： ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md
  5. **上游 ADR（主要来源）**以及组件必须满足的 BDD／EARS 验收契约。

确认上游产物已存在且没有 ID 冲突： ls docs/05_ADR/ docs/06_SPEC/ 2>/dev/null.

层级指南

C4-L3 范围（保持在组件层级）

SPEC 属于组件层级。描述组件接口和契约，而非架构决策（ADR）或源代码（Code）。

仅限于此（PASS）超出范围（FAIL）
AuthService、UserRepository、NotificationQueueauth_service.py、async def validate_token()
接口签名、类型化数据模型具体 SQL 表、Redis 键格式
行为规则、状态转换、错误契约Kubernetes Pod 配置、部署清单

必需的图表标签：@diagram: c4-l3、@diagram: dfd-l3（使用 ../charts-flow/SKILL.md）。时序图必须用 alt/else 标明错误路径；绝不要嵌入 C4-L4 代码／类图。

必需结构（8 个部分）

document_control 必须置于首位（状态、版本、日期、作者、组件、 tdd_ready_score）。之后依次为：

  1. 文档控制 · 2. 组件概述（描述、@adr 决策、 语言、依赖项）· 3. 接口（导出项：签名、类型、错误）·
  2. 数据模型（类型化字段，不含 SQL／ORM）· 5. 行为（验证规则、 状态转换、错误处理——每项均须注明来源 @ears／@bdd）·
  3. 实现说明（约束、模式、性能考量）·
  4. 下游 TDD 契约（@tdd: TDD-NN、测试文件映射）· 8. 可追溯性。

各部分的具体内容请参阅 SPEC-TEMPLATE.yaml。格式为 YAML。

元素 ID 和标签
  • SPEC 是文档级制品 — 使用短横线形式 SPEC-NN 引用 （两位数字，不添加多余的前导零：SPEC-01、SPEC-99、SPEC-102）。 下游制品使用 @spec: SPEC-12 标记。SPEC 自身没有点分隔的 SPEC.NN.SS.xxxx 元素形式。
  • 必需的上游标签（依据必要上游契约）： 层级引用使用 4 段元素形式 — @ears: EARS.NN.SS.xxxx、 @bdd: BDD.NN.SS.xxxx；文档级引用使用 @adr: ADR-NN。上游 PRD/BRD 沿袭关系可通过 EARS/BDD @ 标签链传递追溯 — 不要在 SPEC 元素上 添加 @brd:/@prd:。
  • **阈值：**绝不硬编码性能/超时/速率限制值 — 使用 @threshold: 注册表引用。
  • 已移除的模式（不要使用）：STEP-XXX、IF-XXX、INT-XXX、DM-XXX、 MODEL-XXX、VR-XXX、3 位数字的 SPEC-NNN、数字元素类型代码表， 以及已删除的 SYS/REQ/CTR 上游层。

创建流程

  1. 阅读上游文档 — ADR 决策以及组件所满足的 BDD/EARS 契约。
  2. 预留 ID — 在 docs/06_SPEC/ 下选择下一个可用的 SPEC-NN。 层间独立性（CLEANUP-PR-F 第 18 项）： 在本层索引中选择下一个可用 编号 — 上游编号不是你的编号（文档编号按层分别顺序递增且互相独立；参见 framework/governance/ID_NAMING_STANDARDS.md §跨层基数）。
  3. 创建嵌套文件夹 — 每个 SPEC 都必须位于 docs/06_SPEC/SPEC-NN_{slug}/SPEC-NN_{slug}.yaml 中，无论文件大小。绝不要 将 SPEC 文件直接放在 docs/06_SPEC/ 下。
  4. 先填写文档控制，然后完成模板中的全部 8 个章节。
  5. 定义接口和数据模型，并使用类型化签名；说明行为，确保每条规则都来源于 @ears/@bdd。
  6. 添加必需的上游标签（依据必要上游契约添加 @ears @bdd @adr）和下游的 @tdd: TDD-NN 契约。
  7. 在同一变更中更新 SPEC 索引 docs/06_SPEC/SPEC-00_index.md。
  8. 进行验证（见下文），并将 SPEC 和索引一并提交。

验证

此技能就是验证器（不含运行时代码）。根据 ${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md 和 ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md 进行检查。

  • YAML 可解析；文档控制是第一个章节。
  • 8 个章节全部存在且非空；格式为 YAML（而非 Markdown）。
  • 仅限组件级内容（不含代码/SQL/部署细节；符合 C4-L3 范围）。
  • 文档 ID 为短横线形式 SPEC-NN；没有点分隔的 SPEC 元素 ID；没有已移除的模式。
  • 存在必需的上游标签（依据必要上游契约添加 @ears @bdd @adr）；存在下游的 @tdd: TDD-NN 契约。
  • 定量值使用 @threshold: 引用（不使用魔法数字）。
  • 图表契约：存在 @diagram: c4-l3 和 @diagram: dfd-l3（使用 ../charts-flow/SKILL.md）。
  • 已创建或更新可追溯性矩阵/索引；没有失效链接。
代码含义严重程度
XDOC-006标签格式无效错误
XDOC-007缺少必需的上游标签错误
XDOC-008内部链接失效错误
XDOC-009缺少可追溯性章节错误

**质量门禁（阻断性）：**进入下一步前，TDD 就绪度评分必须 ≥ 90/100。如果 发现问题，请修复并重新检查；如果无法修复，请记录并交由人工审核。

下一项技能

../doc-tdd/SKILL.md — TDD 会通过 @spec: SPEC-NN 引用此 SPEC， 并添加其自身必需的 @ears @bdd @adr 上游标签，同时为 SPEC 契约定义测试用例、 输入、预期输出和阈值。

适配

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

相关资源

  • 模板 / 编写规则：${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-TEMPLATE.yaml
  • 层级 README：${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/README.md
  • 索引模板：${CLAUDE_PLUGIN_ROOT}/framework/layers/06_SPEC/SPEC-00_index.TEMPLATE.md
  • ID 和标签标准：${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  • 上游决策：../doc-adr/SKILL.md · 下游测试：../doc-tdd/SKILL.md
  • 质量门禁：../doc-spec-audit/SKILL.md · 修复：../doc-spec-fixer/SKILL.md
  • 生成流水线：../doc-spec-autopilot/SKILL.md

快速参考

用途规范组件：接口、数据模型、行为
层级6（C4-L3 组件）
上游标签@ears @bdd @adr（依据必要上游契约）
文档 ID连字符形式 SPEC-NN（文档级；无带点的元素 ID）
必须包含文档控制（首项）、8 个章节，数字需使用 @threshold
格式YAML
下一步doc-tdd

评论

支持 Markdown