hany-verify-project

name	hany-verify-project
description	项目级验证。触发：/hany:verify-project。针对大功能、架构调整、多文件改动的完整验证：多视角并行审查+功能测试+回归验证+边界检查+修复循环+质量清单+根因分析。
author	hany
version	1.0

hany-verify-project — 项目级完整验证

触发方式：/hany:verify-project

调用方：可独立触发 /hany:verify-project，也可由 hany-auto Step 4 自动调用。

适用场景：大功能实现、架构调整、多文件改动、版本发布前检查。小改动请用 /hany:verify-small

核心原则：没有证据就不说完成。运行命令看到输出才能下结论。不允许猜测。发现问题立即展示给用户，后台继续排查。可优化必须反馈。

质量模式

详见 hany-common/procedures/quality_modes.md

强制交互规则

禁止跳过验证直接说"测试通过"，禁止不运行就声称代码能工作，禁止忽略失败的测试/检查。所有结论必须附带证据。

编码约束：读取 hany-common/rules/rules.md，11 条规则全程生效。

概览（按需加载）

[按需加载] 执行时：

1. 启动阶段：仅读快速参考卡和"Step 0"即可开始
2. 执行阶段：用 Read(offset/limit) 跳读到对应 Step 章节（参考下方行号区间）
3. 已完成阶段：用 3 行摘要替代详细内容

行号参考（offset 跳读用）：Step 0 约第 68 行 | Step 1 约第 81 行 | Step 2 约第 95 行 | Step 3 约第 120 行 | Step 4 约第 132 行 | Step 5 约第 146 行 | Step 6 约第 183 行 | Step 7 约第 197 行 | Step 8 约第 208 行 | Step 9 约第 243 行 | Step 10 约第 271 行 | Step 11 约第 277 行 | Step 12 约第 315 行 | Step 13 约第 321 行

快速参考卡

阶段	核心动作	确认节点
Step 0	先想想看，输出思路	—
Step 1	检查前置条件 + Agent 结果独立验证	—
Step 2	生成质量清单	—
Step 3	3D 验证（完整性+正确性+一致性）	AskUserQuestion（需求模糊时）
Step 4	多视角并行审查（架构+安全+代码质量）	—
Step 5	功能验证（边找边报）	AskUserQuestion（阻塞时）
Step 6	回归验证（Red-Green 测试）	—
Step 7	边界/异常检查	AskUserQuestion（不确定时）
Step 8	发现问题立即修复（根因分析+错误→规则）	—
Step 9	验证/修复循环 + 质疑审查	AskUserQuestion（循环耗尽时）
Step 10	优化反馈	AskUserQuestion
Step 11	输出验证报告	—
Step 12	完成归档到 docs/hany/archive/	AskUserQuestion
Step 13	最终确认	AskUserQuestion

前置条件

必须满足才能开始：

1. docs/hany/plans/ 下存在已确认的计划文档
2. docs/hany/requirements/ 下存在已确认的需求文档

前置条件不满足时，提示用户先执行 /hany:implement。

概览工作流程

见上方快速参考卡（按顺序从 Step 0 到 Step 13）。

---

Step 0：先想想看 [进度 2%]

⚠️ 若由 hany-auto 调用，跳过此步（auto 已完成初步思考）。

触发后，先思考再执行。

1. 实现了哪些功能，改动了哪些文件？
2. 验证重点应该放在哪里？
3. 有没有高风险区域需要重点关注？
4. 哪些检查可以并行执行？

思考完后输出思路再进入 Step 1。

Step 1：检查前置条件 & Agent 结果独立验证 [进度 5%]

1. 检查 docs/hany/plans/ 和 docs/hany/requirements/ 下是否有确认的文档
2. 如果没有，提示用户先执行 /hany:implement
3. 如果有，读取需求文档和实现代码

Agent 结果独立验证（不信任 Agent 报告）：

1. 检查 git diff — 实际改了哪些文件，和 Agent 报告是否一致
2. 检查文件内容 — 改动是否真的存在，不是空壳
3. 检查语法 — 改动后的代码能否通过编译

铁律：Agent 报告"完成" ≠ 真的完成。必须独立验证。

Step 2：生成质量清单 [进度 10%]

### 需求覆盖
- [ ] [需求N] 已实现并验证

### 功能验证
- [ ] 语法/编译检查通过
- [ ] 构建通过
- [ ] 测试通过
- [ ] 核心功能走查通过

### 安全检查
- [ ] 密钥管理无硬编码
- [ ] 输入验证全覆盖
- [ ] 无注入风险

### 边界检查
- [ ] 空值处理
- [ ] 极端值处理
- [ ] 错误处理

清单项目在后续步骤中逐项打勾。未打勾的项目必须说明原因。

Step 3：需求一致性检查（3D 验证） [进度 15%]

3.1 完整性 — 需求文档中的每个需求项是否都被实现。

3.2 正确性 — 实现是否匹配需求的意图，不只是字面意思。

3.3 一致性 — 设计决策是否在代码中落地：技术栈、架构图对应、模块接口一致。

3.4 模糊需求反问

需求有歧义 → 用 AskUserQuestion 反问，多轮验证直到明确。

Step 4：多视角并行审查 [进度 25%]

同时启动 3 个独立审查视角，team 并行执行。全部必须通过。

审查视角	Agent	审查内容
架构审查	Architect-Agent	功能完整性、设计模式合理性、模块划分
安全审查	Security-Agent	10项安全检查（密钥/注入/XSS/CSRF/认证...）
代码质量	Reviewer-Agent	命名/重复/复杂度/可读性/性能

安全检查 10 项

详见 hany-common/procedures/security_checklist.md

Step 5：功能验证（team 并行排查 + 边找边报） [进度 40%]

实际运行验证，不能只看代码。

边找边报机制

后台并行排查，阻塞级问题立即打断，其余批量汇报。

1. 启动多个 Agent 并行排查（语法/构建/测试/功能走查）
2. 阻塞级问题（崩溃/编译失败/核心功能不可用）→ 立即汇报并暂停，用 AskUserQuestion 确认：立即修复 / 暂停排查
3. 非阻塞问题（功能异常/代码质量/边界问题）→ 后台继续排查，攒一批后批量汇报
4. 每轮排查完后汇总，用 AskUserQuestion（multiSelect）让用户选择：哪些立即修 / 哪些暂不修 / 哪些跳过

汇总汇报格式

[排查汇总 第X轮] 发现 N 个问题

高严重程度（阻塞）：
  1. [问题] 位置：[文件:行号]

中严重程度：
  2. [问题] 位置：[文件:行号]

低严重程度：
  3. [问题] 位置：[文件:行号]

验证项

检查项	命令
语法/编译	tsc --noEmit / python -m py_compile / go vet / cargo check
构建	npm run build / go build / cargo build
测试	npm test / pytest / go test / cargo test
功能走查	正常输入→预期输出，关键路径通顺，数据流完整

Step 6：回归验证 [进度 50%]

写一个针对 bug 的测试用例，确认测试能捕获该问题。

1. 写一个能通过的测试
2. 还原 bug 修改
3. 运行测试 → 必须失败
4. 恢复修改
5. 运行测试 → 必须通过

如果测试在 bug 存在时仍通过，说明测试无意义，必须重写。

降级方案：项目无测试框架时，用"手动验证步骤"替代。或直接跳过此步并在报告中标注原因。

Step 7：边界/异常检查 [进度 55%]

检查项	验证方式
空输入/空值	null/undefined/空字符串处理
极端值	超大数字、超长字符串、空数组
并发/竞态	多线程/异步竞态风险
错误处理	异常捕获，错误信息友好

不确定的检查项，用 AskUserQuestion 问用户。

Step 8：发现问题立即修复（系统调试协议 + 根因分析） [进度 65%]

8.1 系统调试协议

阶段	动作
1. 根因调查	不急着改代码。先看报错、日志、堆栈。找到根本原因。
2. 模式分析	偶发还是必现？新引入还是老问题？类似 pattern 在其他地方？
3. 假设验证	写最小复现用例。修之前确认能复现。修之后确认不再出现。
4. 实施修复	最小改动。修完后回归测试。

铁律：没有根因调查就不修。3 次修复失败 → 停下来质疑架构。

8.2 根因分析

问题	根因（为什么出现）	修复方式	验证
[描述]	[根本原因，不是表象]	[怎么修的]	[验证命令+输出]

8.3 严重程度处理

严重程度	处理方式
高（阻塞/崩溃）	立即修复，修完继续
中（功能异常）	立即修复
低（代码风格）	立即修复或标记为可选优化（由用户决定）

8.4 错误→规则抽象（防止再犯）

详见 hany-common/procedures/error_backoff.md 的反复错误强制记录规则。

8.5 反复出现错误的强制记录

详见 hany-common/procedures/error_backoff.md 的"反复出现错误的强制记录"章节。

Step 9：验证/修复循环 + 质疑审查 [进度 75%]

错误回退规则见 hany-common/procedures/error_backoff.md

不是单次验证，而是 verify→fix→re-verify 循环，直到全部通过。每轮结束必须质疑。

验证 → 发现问题 → 修复 → 重新验证 → 全部通过？
  ├── 是 → 质疑审查 → 真的全部通过？→ 进入下一步
  └── 否 → 继续循环（最多 N 轮，standard 默认 3 轮）

循环规则：

• 每轮汇报：[验证循环 第X轮] 通过：X项，失败：Y项，新增：Z项
• 同一错误连续出现 3 次 → 停止循环，质疑架构
• 达到最大轮数仍未全部通过 → 用 AskUserQuestion 汇报剩余问题，让用户决定

9.1 质疑审查（每轮验证通过后必须执行）

"你确定这真的对吗？" — 不要轻信通过的结果。

1. 测试覆盖质疑：通过的测试是不是只测了 happy path？边界情况测了吗？
2. 隐性 bug 质疑：代码能跑 ≠ 逻辑对。有没有静默失败的情况？
3. 回归风险质疑：这次修改有没有可能影响到其他功能？
4. "看起来对"质疑：输出结果"看起来对"但有没有实际验证数据正确性？

质疑审查发现新问题 → 回到 Step 8 修复 → 继续循环。

Step 10：优化反馈 [进度 80%]

发现可优化的地方必须反馈：性能优化 / 代码简化 / 架构优化 / 安全隐患。

格式：[优化建议] 位置：[文件:行号]。当前：[X]。建议：[Y]。理由：[Z]。是否优化？

Step 11：输出验证报告 [进度 85%]

## 项目级验证报告

### 质量清单
[Step 2 清单逐项打勾结果]

### 3D 验证
- 完整性：✅/❌
- 正确性：✅/❌
- 一致性：✅/❌

### 多视角审查
| 视角 | 结果 | 发现问题数 |
|------|------|-----------|
| 架构 | ✅/❌ | X |
| 安全 | ✅/❌ | X |
| 代码质量 | ✅/❌ | X |

### 功能验证
- 语法：✅/❌ / 构建：✅/❌ / 测试：✅/❌ / 功能走查：✅/❌

### 回归验证
- Red-Green：✅/❌

### 发现并修复的问题
| # | 严重程度 | 描述 | 位置 | 根因 | 修复方式 | 验证 |
|---|---------|------|------|------|---------|------|

### 验证/修复循环记录
| 轮次 | 通过项 | 失败项 | 新增问题 | 状态 |
|------|--------|--------|---------|------|

### 结论
[通过 / 有条件通过 / 不通过]

Step 12：完成归档 [进度 90%]

路径：docs/hany/archive/YYYY-MM-DD-<主题>-verify-project.md

用 AskUserQuestion 确认：确认归档 / 跳过。

Step 13：最终确认 [进度 95%]

用 AskUserQuestion：

• 全部通过 + 无优化建议 — 任务完成
• 全部通过 + 有优化建议 — 问用户是否执行优化
• 有问题需修复 — 已在 Step 8/9 修复，展示修复结果
• 不通过 — 告知哪些环节失败，建议重新执行 /hany:implement