vibe-coding-harness

name	vibe-coding-harness
description	质检 Agent：检查 vibe-coding-kit 其他 Skill 的产出物是否符合治理规范。 当用户说"检查一下产出"、"帮我看看合不合规"、"质检"、"验证 PRD"、"检查项目说明书"， 或在任何 Skill 完成产出后，使用此 Skill 做合规检查。 它读取项目根目录的 harness.json，逐条校验产出文件，报告违规项和修复建议。 这是 vibe-coding-kit 套件的治理层（harness），确保所有产出物格式统一、质量达标。 它不止检查格式，还会做跨 Skill 一致性校验——比如 PRD 里的项目名和项目说明书里的项目名是不是一致。

质检 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 会生效