vibe-coding-harness

# 质检 Agent：产出物合规检查

**这不是一个独立使用的 Skill，而是其他 Skill 的"守门员"**——在任何 Skill 声称"完成"后，用它来验证产出物是否真正符合规范。

> 治理规则来自项目根目录的 `harness.json`（唯一真实来源）和 `CLAUDE.md`（人类可读宪法）。
> 本 Skill 把这些规则变成逐条可执行的检查项。

---

## 检查流程

### Step 1：确定检查范围

先确认用户想检查什么：
- 如果用户指定了 Skill（如"检查 PRD"），只检查那个 Skill 的产出
- 如果用户说"全量检查"或没说具体，检查 `docs/` 下所有已有产出物
- 如果 `docs/` 不存在或为空，直接报告"没有可检查的产出物"

### Step 2：加载规则

读取项目根目录的 `harness.json`，提取：
- 目标 Skill 的 `produces`（该产出什么文件）
- 目标 Skill 的 `required_sections`（必须包含的章节）
- 目标 Skill 的 `field_requirements`（字段级校验规则）
- 目标 Skill 的 `validation`（内容级校验规则）
- `cross_skill_rules`（跨 Skill 一致性规则，仅在多 Skill 产出共存时检查）
- `quality_gates.before_delivery`（交付前必须通过的门）
- **`workflow`（流程定义：阶段、步骤、entry_gate/exit_gate、账本规则）—— 用于新增的流程一致性检查**
- **`progress_cards`（项目进度卡规则：低上下文读取、总表/模块卡/任务卡同步）**

并读取 `docs/进度账本.md`（流程状态来源）。若不存在，流程检查记为"未启用账本"。
如果项目存在 `.dsu/progress/index.md`，读取该文件并按需抽查相关模块卡和任务卡；如果不存在，项目进度卡检查记为"未启用"。

### Step 3：逐项检查

按以下顺序逐项检查，每项给出通过/不通过/不适用：

#### 3.0 流程一致性检查（最先做 · 这一版新增）

对照 `harness.json.workflow` 和 `docs/进度账本.md`，核对**过程**有没有跑偏（不只是产出物对不对）：

- **阶段按序**：有没有跳过整个阶段而未推进（如账本显示在 S2，但 S1 出口门 ✗）。
- **假完成**：账本标「已完成」的阶段，其 `exit_gate` 是否**真的**过了（防止"账本说完成、产出物却没达标"）。
- **跳步留痕**：被跳过的步骤是否都是 `required:false`、且在账本"跳步留痕"写了理由；`required:true` 的步骤被跳 = 🔴 违规。
- **账本与产出物吻合**：账本当前阶段/步骤，与 `docs/` 下实际存在的产出物对得上。
- **红线**：若项目涉及"动钱 / 动别人隐私"，survival 红线提示是否出现过。

输出：🔴 流程违规（如"S1 未过却已在 S2"）／🟡 跳步未留痕、账本与进度说明书不一致／✅ 流程一致。

#### 3.0.5 项目进度卡检查（开发期上下文治理）

如果项目启用了 `.dsu/progress/`，对照 `harness.json.progress_cards` 检查：

- **总表是否存在**：`.dsu/progress/index.md` 是否存在且非空。
- **总表是否只放索引级信息**：总表应只回答当前阶段、当前主线、完成 DU、进行中 DU、下一步、最大风险，不应堆模块实现细节。
- **读取规则是否清楚**：总表必须说明默认只读 index，按需读取模块卡，复盘才读任务卡。
- **模块卡是否可下钻**：DU 总进度表中的细节卡路径应指向 `.dsu/progress/modules/duXX-xxx.md`。
- **任务 closeout 是否同步**：最近任务更新后，应能在任务卡、模块卡、总表三处看到一致状态。
- **状态枚举是否合规**：只能使用 未开始 / 脚手架 / 进行中 / 已完成 / 阻塞 / 回滚 / 待重构。
- **最小上下文是否可用**：总表中的「下一轮 AI 最小上下文」应控制在 150 到 300 字，且不写历史流水账。

输出：🔴 缺少总表或状态冲突／🟡 总表过细、模块卡缺失、任务 closeout 未同步／✅ 项目进度卡可用。

#### 3.1 文件存在检查
对照 `produces`，确认每个文件是否已创建、是否非空。

#### 3.2 必须章节检查
对照 `required_sections`，在文件中搜索这些章节标题是否存在。

#### 3.3 字段校验
对照 `field_requirements`：
- 字段是否存在且非空
- 是否匹配指定的正则（如版本号格式 `v\d+\.\d+`）
- 是否满足最小长度/最小条目数

#### 3.4 内容校验
对照 `validation`：
- 字数是否在范围内
- 是否包含必须出现的关键词
- 是否为 checklist 格式（如果要求的话）

#### 3.5 全局禁止项检查
对照 `constitution.forbidden` 逐条扫描：
- 搜索 `{` `}` 配对、`TODO`、`TBD` 等占位符模式
- 检查是否有大片英文正文（排除代码块）
- 检查是否有疑似密钥/密码/token 的模式（长随机字符串、`sk-` 前缀等）

#### 3.6 跨 Skill 一致性检查（仅当多 Skill 产出共存时）
- CSR-001：对比 `prd.md` 的「产品结论」与 `项目说明书.md` 的「需求基准描述」
- CSR-002：对比 PRD 的「形态」与项目说明书的「技术栈」
- CSR-003：对比所有产出物中的项目名称
- CSR-004：检查验收标准是否具体可验证

#### 3.7 质量门检查
逐条对照 `quality_gates.before_delivery`。

### Step 4：输出检查报告

按严重程度分组输出：

```
## 质检报告：{Skill 名称 / 全量检查}

### 🔴 错误（必须修复，否则产出不合格）
| # | 文件 | 规则 | 问题 | 修复建议 |
|---|------|------|------|---------|
| 1 | docs/prd.md | 版本格式 | "版本：待定"不符合 v数字.数字 格式 | 改为 "版本：v0.1" |
| 2 | docs/prd.md | 字段非空 | "产品名称"为空 | 填写实际产品名称 |

### 🟡 警告（建议修复，不阻断）
| # | 文件 | 规则 | 问题 | 修复建议 |
|---|------|------|------|---------|
| 1 | docs/prd.md | 边界声明 | "明确不做"为空，缺少边界 | 至少写一条"本版不做什么" |

### 🔵 提示（最佳实践建议）
| # | 文件 | 建议 |
|---|------|------|
| 1 | docs/项目说明书.md | 「目录结构」建议填写，方便后续维护 |

### 流程审计结果（这一版新增）
| 检查 | 状态 |
|------|------|
| 阶段按序推进 | ✅ 一致 |
| 无假完成（出口门真过） | ❌ S1 标完成但 prd 缺验收 |
| 跳步均已留痕 | 🟡 S1.5 跳过未写理由 |
| 账本与产出物吻合 | ✅ 一致 |

### 项目进度卡审计结果
| 检查 | 状态 |
|------|------|
| 总表存在且非空 | ✅ 通过 |
| 总表只放索引级信息 | ✅ 通过 |
| 模块卡按需下钻 | 🟡 DU02 指向的模块卡不存在 |
| 任务 closeout 三处同步 | ✅ 通过 |
| 状态枚举合规 | ✅ 通过 |
| 下一轮 AI 最小上下文可用 | ✅ 通过 |

### 质量门结果
| 门 | 状态 |
|----|------|
| QG-001 文件存在 | ✅ 通过 |
| QG-002 无占位符 | ❌ 未通过 |
| QG-003 无敏感信息 | ✅ 通过 |
| QG-004 版本号 | ❌ 未通过 |
| QG-005 验收可验证 | ✅ 通过 |
| QG-006 语言检查 | ✅ 通过 |

### 总结
- 错误 X 项，警告 Y 项，提示 Z 项
- 质量门：A/B 通过
- 判定：❌ 不合格，需要修复后重新质检
```

**如果全部通过：**
```
## 质检报告：全部通过 ✅

所有产出物符合治理规范：
- 文件齐全、章节完整、字段合规
- 质量门 6/6 通过
- 跨 Skill 一致性检查通过

可以交付。
```

---

## 修复与重试

1. **首次不通过**：输出违规清单 + 每条的具体修复指令（用户可直接复制给 AI）
2. **让用户把违规清单发给执行原任务的 AI**，说"请按这些修复建议修正产出物"
3. **修正后再次质检**：只重新检查上次未通过的项
4. **重试上限**：最多 3 次。3 次后仍有错误未修复，标记为"⚠️ 需人工介入"，列出剩余问题

---

## 使用方式

- **Claude Code**：在 Skill 产出后直接说"帮我质检"或"检查一下产出"
- **ChatGPT/Codex**：复制本文件内容，粘贴后说"请按上面的方法检查 docs/ 下的文件"
- **自动化**：配合 `.claude/settings.json` 中的 hooks，每次写入关键文件后自动提醒

---

## 速查：各 Skill 的检查要点

| Skill | 关键检查项 |
|-------|-----------|
| vibe-coding-prd | prd.md 必须章节齐全 / 版本号格式 / 产品名称非空 / 验收标准可验证 |
| vibe-coding-requirements | 需求基准描述 80-300 字 / 覆盖四要素 |
| vibe-coding-architecture | 选定技术栈含"选定"和"否决" |
| vibe-coding-production | 安全清单逐条确认 / 验收清单是 checkbox 格式 |
| vibe-coding-survival | 以后再说清单存在 |
| （流程）进度账本 | 阶段按序、无假完成、跳步留痕、账本与产出物吻合 |
| （开发期上下文）项目进度卡 | 默认只读 index、模块按需下钻、任务 closeout 三处同步、状态枚举合规 |

---

## 与 CLAUDE.md 的关系

- `CLAUDE.md` 是**事前预防**——在 AI 开始工作前就告诉它规则
- 本 Skill 是**事后校验**——在 AI 声称完成后逐条验证
- 两者都从 `harness.json` 派生，保持规则一致
- 如果质检发现 CLAUDE.md 的规则没被遵守，修复产出 + 提醒用户下次开新对话时 CLAUDE.md 会生效