规划产物质量校验

技能文档

---
name: drillan-planning-validate
title: 规划产物质量校验
category: 开发工具
description: 校验规划产物（spec.md、plan.md、data-model.md、contracts/）的质量、完整性与一致性：检查必备章节、跨产物术语一致性与项目宪章合规性，输出红黄绿三色质量评定。当用户需要校验规格文档、检查规划产物完整性、任务拆解前质量把关、规格驱动开发流程中做门禁检查时触发。触发词：规格校验、规划产物、质量门禁、一致性检查、spec 审查。
---

# 规划产物质量校验

在规划阶段完成后自动校验规划产物，在任务拆解前拦截规格缺口。输出绿/黄/红三色质量评定（Quality Assessment）。

## 目的

本技能自动校验规划产物，在生成任务前发现规格缺口。检查项：

- **spec.md 完整性**：必备章节齐全且有内容
- **plan.md 可执行性**：技术上下文、项目结构、宪章检查已完成
- **data-model.md 一致性**：实体与规格要求对齐（如存在）
- **契约覆盖**：所需端点均定义了 API 契约（如 contracts/ 存在）
- **宪章合规**：计划遵循项目宪章规则（如 constitution.md 存在）

## 输出评定

- **GREEN**：全部检查通过——可进入任务拆解
- **YELLOW**：存在轻微警告——需复核但可继续
- **RED**：发现阻塞项——必须先解决再继续

## 技能工作流

### 步骤1：定位规划产物

脚本自动定位仓库根目录（`.git` 或 `.specify`）与特性目录，解析 spec.md、plan.md、data-model.md、contracts/ 路径。

### 步骤2：执行校验

```bash
bash scripts/validate.sh
```

脚本按「检查项清单」逐项校验并汇总结果。

### 步骤3：解读退出码与评定

| 退出码 | 状态 | 含义 |
|--------|------|------|
| 0 | GREEN | 全部检查通过 |
| 1 | YELLOW | 存在警告 |
| 2 | RED | 存在阻塞项 |
| 3 | 错误 | 必需文件缺失 |

### 步骤4：整改与复检

RED 或 YELLOW 时：

1. 逐条查看列出的阻塞项或警告
2. 修订受影响的规划产物
3. 重新生成 plan.md（如需）
4. 再次运行校验确认修复

## 检查项清单

### spec.md 检查

1. 文件存在且可读
2. 摘要章节存在且有内容
3. 用户故事章节存在且至少包含一个故事
4. 功能需求章节存在且含 FR-XXX 条目
5. 成功标准章节存在

### plan.md 检查

1. 文件存在且可读
2. 技术上下文章节存在
3. 项目结构章节存在
4. 宪章检查章节存在（除非声明跳过）
5. 门禁结果显示 PASS

### data-model.md 检查（如存在）

1. 实体章节存在
2. 至少定义一个实体
3. 实体命名与 spec.md 术语一致

### contracts/ 检查（如存在）

1. 至少存在一个契约文件
2. 契约文件为有效 Markdown
3. 契约端点与 spec.md 需求匹配

### constitution.md 检查（如存在）

1. plan.md 引用了宪章原则
2. 门禁结果中无宪章违规

## 阻塞项示例

- 「spec.md：缺少用户故事章节」
- 「plan.md：宪章检查章节显示 FAIL」
- 「data-model.md：实体 UserAccount 未在 spec.md 中引用」

使用说明

# 规划产物质量校验

校验规格驱动开发中的规划产物（spec.md、plan.md、data-model.md、contracts/）的质量、完整性与跨产物一致性，输出红黄绿三色门禁评定，在任务拆解前拦截规格缺口。

## 使用

```bash
bash scripts/validate.sh
echo $?   # 0=GREEN 通过 / 1=YELLOW 警告 / 2=RED 阻塞 / 3=文件缺失
```

规格规划完成后运行一次即可；也可接入 CI 作为任务拆解前的质量门禁。

## 工作原理

- **五路检查**：spec 完整性、plan 可执行性、数据模型一致性、API 契约覆盖、宪章合规逐项校验
- **三色门禁**：GREEN 放行、YELLOW 警告、RED 阻塞，退出码可直接驱动流水线卡点
- **整改闭环**：输出逐条阻塞项定位到文件与章节，修订后复检直至 GREEN

如何安装此技能？

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