SDD 规格工件校验

技能文档

---
name: majiayu000-spec-validator
title: SDD 规格工件校验
description: 自动校验规格驱动开发（SDD）工件的完整性、一致性与质量，覆盖 spec.md、plan.md、tasks.md 三类工件与项目宪章，输出结构化校验报告与改进建议。当用户需要校验规格文档、检查功能规格是否完整、审查 SDD 工件、实现前确认规格就绪、规格质量检查时触发。
category: 开发工具
---

# SDD 规格工件校验

在动手实现之前，自动校验规格驱动开发（SDD）工件是否完整、一致并符合项目约定，提前发现规格、计划与任务拆解中的问题。

## 触发场景

- 「校验我的规格」「检查规格是否完整」
- 「这个功能可以开始实现了吗」
- 「审查一下我的 SDD 工件」「规格质量检查」

## 技能工作流

### 步骤1：确定功能目录

优先从当前 git 分支自动识别，否则扫描 `specs/` 目录：

```bash
BRANCH=$(git branch --show-current 2>/dev/null)
ls -d specs/*/
```

存在多个功能或上下文不明确时，询问用户要校验哪一个。

### 步骤2：检查文件齐备性

**必需文件：**

- `specs/{feature}/spec.md` - 功能规格
- `specs/{feature}/plan.md` - 实现计划
- `specs/{feature}/tasks.md` 或 `specs/{feature}/tasks/` - 任务拆解

**可选但推荐：**

- `specs/constitution.md` - 项目宪章
- `specs/{feature}/acceptance.md` - 验收标准（已完工功能）

缺失时逐项报告，例如：`❌ 缺失: specs/001-user-auth/plan.md`。

### 步骤3：校验 spec.md

**必备章节：** 功能名称/标题、功能描述或概述、用户故事或需求、成功标准或验收标准、范围外说明（可选但推荐）。

**校验点：**
- [ ] 有清晰的功能名称（H1 标题）
- [ ] 描述功能「做什么」而非「怎么做」
- [ ] 至少包含一条用户故事
- [ ] 定义了可度量的成功标准
- [ ] 用户故事符合「作为……我希望……以便……」格式（如适用）

**质量检查：** 是否聚焦用户价值？成功标准是否具体可度量？范围是否清晰？

### 步骤4：校验 plan.md

**必备章节：** 对 spec.md 的引用、技术方案或架构、实现阶段或拆解、依赖（内部与外部）、待修改/新建的文件。

**校验点：**
- [ ] 引用了功能规格
- [ ] 描述「怎么实现」而非「做什么」
- [ ] 列出全部依赖
- [ ] 拆解为逻辑阶段
- [ ] 指明具体要改动的文件/模块

**质量检查：** 计划是否对齐规格目标？技术决策是否有依据？是否识别了风险与挑战？

### 步骤5：校验任务拆解

**tasks.md 单文件形态：**
- [ ] 按用户故事或阶段组织
- [ ] 每个任务有唯一编号（WP01、T001 等）
- [ ] 任务列明要修改的具体文件
- [ ] 标注依赖关系
- [ ] 含工作量估计（可选）

**tasks/ 目录（看板形态）：**
- [ ] 有泳道目录：`planned/`、`doing/`、`for_review/`、`done/`
- [ ] 工作包文件使用规范 frontmatter
- [ ] 每个工作包有标题、阶段、依赖
- [ ] 有活动日志

**质量检查：** 任务粒度是否够细（每个 1–4 小时）？是否覆盖规格的方方面面？依赖是否现实？

### 步骤6：宪章合规检查

存在 `specs/constitution.md` 时：

- 阅读宪章原则
- 检查规格/计划是否符合既定价值
- 核对技术选型是否符合治理规则
- 标记潜在冲突

### 步骤7：交叉引用校验

检查工件之间的一致性：

**规格 ↔ 计划：**
- 规格中所有用户故事在计划中有对应处理
- 计划的技术方案能支撑规格目标
- 成功标准在计划实现下可达成

**计划 ↔ 任务：**
- 计划的每个阶段都有对应任务
- 计划中的依赖都反映在任务中
- 任务中的文件路径与计划的架构一致

**任务 ↔ 规格：**
- 任务合起来满足全部用户故事
- 没有超出规格范围的任务

### 步骤8：生成校验报告

```markdown
# 校验报告：{feature-name}

## 摘要
✅ 通过：12/15 项
⚠️ 警告：2
❌ 失败：1

## 文件齐备性
[逐文件 ✅/❌ 清单]

## 规格质量 / 计划质量 / 任务拆解
[各维度逐项校验结果]

## 交叉引用检查
[一致性核对结果]

## 改进建议
1. [可执行的具体建议]

## 总体评估
**状态：就绪（含轻微改进项）**
[一句话结论与说明]
```

## 输出语言

- 跟随用户提问语言作答
- 代码块与技术术语保持原文

## 错误处理

无法校验时：

1. 说明缺失或阻塞的原因
2. 给出下一步建议（如「先创建 spec.md」）
3. 部分工件存在时，提供部分校验

## 注意事项

- 本技能**只读**：只校验，不修改文件
- 校验标准随项目类型上下文调整
- 警告是建议，不是阻塞项
- 在开始实现前使用，尽早暴露问题

使用说明

# SDD 规格工件校验

自动校验规格驱动开发（SDD）工件的完整性、一致性与质量，实现前提前暴露规格问题。

## 能做什么

- 检查 spec.md / plan.md / tasks.md 三类必需工件与项目宪章的齐备性
- 逐维度内容校验：规格聚焦用户价值、计划对齐目标、任务粒度合理
- 规格 ↔ 计划 ↔ 任务三方交叉引用一致性核对
- 宪章合规检查（存在 constitution.md 时）
- 输出结构化校验报告（通过/警告/失败 + 可执行改进建议）

## 何时使用

- 校验规格文档、检查功能规格是否完整
- 审查 SDD 工件质量
- 开始实现前的最终就绪检查

## 快速上手

```text
校验 specs/001-user-auth 的规格工件
```

```text
检查一下我的规格能不能开始实现了
```

本技能只读不改文件；警告是建议而非阻塞项。

## 目录结构

- `SKILL.md`：八步校验工作流与报告模板

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。