cavekit-validation-first

以验证为先的设计

核心原则：如果 Agent 无法验证，就不会满足要求

每项规范要求都必须包含 Agent 可以自动验证的可测试验收标准。这不是可选项，而是 SDD 能够奏效的基础。

为什么？ AI Agent 具有非确定性。没有自动化验证，就无法知道 Agent 的输出是否正确。验证关卡能将“Agent 生成了一些代码”变成“Agent 生成了可证明符合规范的代码”。

验证优先规则适用于各个层面：

• 规范要求必须包含可测试的验收标准
• 计划必须定义哪些关卡用于验证每项任务
• 实现在被视为完成之前，必须通过所有适用的关卡
• 迭代必须通过关卡体现可衡量的进展

---

验证关卡顺序

每项实现都必须依次通过六个检查点。后续关卡的运行成本逐步增加，因此尽早发现失败能节省大量时间。

关卡 1：编译检查

内容： 项目编译或转译时没有错误。

# Generic pattern — substitute your project's build command
{BUILD_COMMAND}

重要性： 如果代码无法构建，其他内容都无法验证。这是成本最低的检查。

可发现的问题：

• 语法错误
• 缺少导入或依赖项
• 类型错误（适用于有类型的语言）
• 配置错误

验收标准模式：

- [ ] `{BUILD_COMMAND}` completes with exit code 0
- [ ] No warnings related to {domain} (warnings in other domains are acceptable)

关卡 2：隔离式单元验证

内容： 所有已更改文件的单元测试均通过。

# Generic pattern
{TEST_COMMAND}

# Or targeted at changed files
{TEST_COMMAND} --filter {changed-files}

重要性： 单元测试会隔离验证各个函数和模块。它们运行快速、结果确定，并能发现逻辑错误。

可发现的问题：

• 函数行为不正确
• 未处理的边界情况
• 更改现有代码导致的回归
• 契约违规（返回类型错误、缺少字段）

验收标准模式：

- [ ] All existing unit tests pass
- [ ] New unit tests cover all acceptance criteria for R{N}
- [ ] No test relies on external services or network access

关卡 3：跨组件集成

内容： 端到端测试和集成测试会验证各组件能否协同工作。

# Generic pattern
{TEST_COMMAND} --e2e

# Or with a specific test runner
{E2E_TEST_COMMAND}

重要性： 单元测试会隔离验证各个组件，集成测试则验证它们能否协同工作。许多错误只会在集成边界处出现。

可发现的问题：

• 组件之间的 API 契约不匹配
• 跨模块边界的数据流错误
• 身份验证或授权集成问题
• 使用真实（或逼真）数据时的数据库查询错误

验收标准模式：

- [ ] User can complete {workflow} end-to-end
- [ ] API endpoint returns correct response for {scenario}
- [ ] Error propagation works correctly from {source} to {destination}

关卡 4：资源与速度基准测试

内容： 性能基准测试达到规定的阈值。

# Generic pattern
{BENCHMARK_COMMAND}

# Or specific checks
{TEST_COMMAND} --performance

重要性： 功能正确是必要条件，但还不够。即使功能输出正确，性能回退也可能导致其无法使用。

可发现的问题：

• 响应时间回退
• 内存泄漏或过度分配
• 阻塞主线程的 CPU 密集型操作
• 数据库查询性能下降

验收标准模式：

- [ ] API response time < {N}ms at p95 under {M} concurrent users
- [ ] Page load time < {N}s on simulated 3G connection
- [ ] Memory usage does not exceed {N}MB during {operation}
- [ ] No operation blocks the main thread for > {N}ms

注意： 并非每项任务都需要性能关卡。在以下情况下应用关卡 4：

• 规范明确规定了性能要求
• 更改涉及已知的热点路径
• 功能涉及大规模数据处理

关卡 5：启动冒烟测试

内容： 应用程序成功启动，且基本冒烟测试通过。

# Generic pattern — start the application
{START_COMMAND}

# Verify it is running
curl -f http://localhost:{PORT}/health

# Or run smoke tests
{SMOKE_TEST_COMMAND}

重要性： 代码可能构建成功且通过所有测试，但仍无法启动。启动验证能够发现配置问题、缺失的环境变量、端口冲突和启动竞态条件。

可发现的问题：

• 缺少环境变量或配置
• 端口冲突或绑定错误
• 启动初始化失败
• 缺少运行时依赖项
• 数据库迁移问题

验收标准模式：

- [ ] Application starts with `{START_COMMAND}` and responds to health check
- [ ] Main screen/page renders without errors
- [ ] No error-level entries in application logs during startup
- [ ] Application shuts down gracefully on interrupt signal

Gate 6：人工审查

内容： 人工审查输出，评估其质量、设计意图，以及难以自动化验证的要求。

重要性： 有些方面无法自动化——UX 质量、架构优雅度、命名一致性、文档清晰度。Gate 6 是人工执行最终质量把关的环节。

可发现的问题：

• 主观质量问题
• 技术上正确、但战略上错误的架构决策
• 过度设计或设计不足
• 自动化工具遗漏的安全问题
• 技术上满足要求、但未体现规范本意的情况

实际工作流程：

1. Agent 完成 Gate 1-5 并报告结果
2. 人工根据规范意图审查实现
3. 人工以问题或规范更新的形式提供反馈
4. 如果反馈要求修改代码，则进入修订循环：
   • 更新规范，补充遗漏的要求
   • 重新运行迭代循环
   • 验证更新后的规范是否能引导修复产生

验收标准模式：

- [ ] Implementation reviewed by human for spec intent alignment
- [ ] No architectural concerns raised
- [ ] Code style consistent with project conventions

---

Gate 汇总表

Gate	用途	命令模式	典型耗时	是否自动化？
1. 编译	代码可顺利编译	{BUILD_COMMAND}	秒	是
2. 单元验证	各个函数行为正确	{TEST_COMMAND}	秒至分钟	是
3. 集成	各模块按预期协同工作	{E2E_TEST_COMMAND}	分钟	是
4. 基准测试	速度和资源使用在预算范围内	{BENCHMARK_COMMAND}	分钟	是
5. 冒烟测试	应用可启动并响应	{START_COMMAND} + 健康检查	秒	是
6. 人工审查	符合设计意图和质量标准	人工检查	不定	否

完整的验证 Gate 参考文档及详细示例，请参阅 references/validation-gates.md。

---

将规范要求映射到 Gate

每项规范要求都必须映射到至少一个验证 Gate。编写规范时（参见 ck:cavekit-writing），每项验收标准都应注明由哪个 Gate 验证。

映射模式

### R1: User Authentication
**Acceptance Criteria:**
- [ ] Valid credentials return session token — **Gate 2** (unit test)
- [ ] Invalid credentials return 401 error — **Gate 2** (unit test)
- [ ] Session token grants access to protected endpoints — **Gate 3** (integration)
- [ ] Login page renders within 2s — **Gate 4** (performance)
- [ ] Application starts with auth module loaded — **Gate 5** (launch)

未映射的要求未经验证

如果某项要求无法映射到任何 Gate，则存在以下两个问题之一：

1. 要求过于模糊——用具体、可测试的标准重写
2. 缺少验证基础设施——添加相应 Gate（例如，如果没有 E2E 测试，则 Gate 3 尚不存在）

无论是哪种情况，Agent 都无法可靠地满足未映射的要求。

---

Hunt 阶段之间的阶段 Gate

阶段 Gate 是 Hunt 各阶段之间强制执行的验证检查点。它们确保上一阶段的输出可靠，然后下一阶段才在此基础上继续工作。

阶段 Gate 定义

转换	Gate 条件	验证方式
规范 → 计划	所有领域都有包含可测试验收标准的规范	审查 cavekit-overview.md；每个 R{N} 都有 AC 条目
计划 → 实现	计划引用规范、定义顺序并包含测试策略	审查计划文件；每项任务都映射到规范要求
实现 → 迭代	代码可构建（Gate 1）、测试通过（Gate 2）、实现跟踪信息为最新	运行 {BUILD_COMMAND} 和 {TEST_COMMAND}；检查实现跟踪信息
迭代 → 监控	检测到收敛：每次迭代的变更逐渐减少	比较最近 3-5 次迭代的差异
监控 → 规范	发现差距或识别出新要求	差距分析识别出未满足的验收标准

阶段 Gate 执行

阶段 Gate 由迭代循环强制执行。当提示词包含阶段 Gate 检查时，Agent 会：

1. 在阶段结束时运行 Gate 检查
2. 报告通过/失败状态
3. 如果 Gate 未通过，Agent 不会进入下一阶段
4. 而是继续迭代当前阶段，直到 Gate 通过

示例：实现 → 迭代 Gate

## Exit Criteria (Phase Gate)
Before reporting completion:
- [ ] `{BUILD_COMMAND}` succeeds with exit code 0
- [ ] `{TEST_COMMAND}` passes with no new failures
- [ ] All files created/modified are listed in impl tracking
- [ ] All dead ends encountered are documented
- [ ] Test health table is updated with current counts

---

合并协议

使用 Agent 团队（通过 Agent 工具以 isolation: "worktree" 派发多个 Agent）时，合并协议可确保整合不同 Agent 的工作不会破坏验证关卡。

协议内容

Agent A completes work in its isolated branch
Agent B completes work in its isolated branch
Agent C completes work in its isolated branch

Merge sequence (one at a time):
1. Merge Agent A's branch → main
2. Run: {BUILD_COMMAND} → must pass
3. Run: {TEST_COMMAND} → must pass
4. Run: Launch verification → must pass
5. If all pass → proceed
6. If any fail → fix before merging next branch

7. Merge Agent B's branch → main
8. Run: {BUILD_COMMAND} → must pass
9. Run: {TEST_COMMAND} → must pass
10. ...repeat for each agent branch

为什么要一次合并一个分支？

同时合并所有 Agent 分支再运行测试，无法判断是哪个合并导致了故障。每次只合并一个分支，并在每次合并后进行验证，就能立即定位故障。

合并协议规则

1. 每次只合并一个 Agent 分支——绝不批量合并
2. 每次合并后运行关卡 1-3——构建、单元测试、集成测试
3. 所有分支合并后运行关卡 5——在完全整合的代码库上进行启动验证
4. 每次合并后清理：移除工作树（git worktree remove <path>），然后删除分支（git branch -D <branch>）。只有当 Agent 未做任何更改时，Claude Code 才会自动清理工作树；如果已提交更改，调用方必须先移除工作树，再删除分支。
5. **如果合并未通过验证，**先修复问题，再继续合并下一个分支

---

完成信号

完成信号是 Agent 在满足任务或阶段的所有退出条件后发出的特定字符串。这些信号可供自动化流程检测 Agent 是否已完成。

完成信号的工作方式

1. 提示词定义信号：

   When ALL exit criteria are met, output exactly:
   <all-tasks-complete>
   

2. Agent 在验证所有退出条件后发出信号

3. 迭代循环检测到信号后停止迭代

完成信号规则

• 信号必须是一个独特的字符串，不会出现在正常输出中
• Agent 必须先验证所有退出条件，然后才能发出信号
• 信号应当是 Agent 在会话中输出的最后内容
• 如果 Agent 无法满足所有条件，则不应发出信号，而应记录阻碍完成的问题

包含完成信号的提示词示例

## Exit Criteria
Complete all of the following before emitting the completion signal:
- [ ] All T- tasks are DONE or BLOCKED with documented blockers
- [ ] `{BUILD_COMMAND}` succeeds
- [ ] `{TEST_COMMAND}` passes with no new failures
- [ ] Implementation tracking is updated
- [ ] All dead ends are documented

When ALL criteria above are met, output:
<all-tasks-complete>

If you cannot meet all criteria, document what is blocking
and do NOT output the completion signal.

---

验证优先设计模式

模式 1：先测试，再实现

在实现功能之前，先编写或生成测试。测试定义了什么是“正确”。

1. Read spec requirement R{N} acceptance criteria
2. Generate test cases that verify each criterion
3. Run tests → all fail (RED)
4. Implement the feature
5. Run tests → all pass (GREEN)
6. Refactor if needed

这是 SDD 中的 TDD。现有的 TDD 技能请参阅 superpowers:test-driven-development。

模式 2：关卡级联

按顺序运行关卡。如果较早的关卡失败，则不要运行后续关卡。

Gate 1 (Build) → FAIL → fix build errors → retry Gate 1
Gate 1 (Build) → PASS → Gate 2 (Unit Tests)
Gate 2 (Tests) → FAIL → fix failing tests → retry Gate 2
Gate 2 (Tests) → PASS → Gate 3 (Integration)
...

较早的关卡成本更低。修复构建错误只需几秒，修复集成错误则需要几分钟。先解决成本低的问题。

模式 3：逐步加深关卡验证

并非每次迭代都需要运行所有关卡。根据所处阶段逐步加深验证：

阶段	必需关卡	可选关卡
初期实现	1（构建）、2（单元测试）	—
中期实现	1、2、3（集成测试）	4（性能）
后期实现	1、2、3、5（启动）	4
发布前	全部 1-6	—

模式 4：防止回归

如果某个之前通过的关卡开始失败，应将其视为 P0 问题：

1. 停止推进——不要实现新功能
2. 找出回归原因——是哪项更改导致了故障？
3. 修复回归——恢复到通过验证的状态
4. 添加测试——确保此类回归不会再次发生
5. 反向反馈——如果回归暴露了规范缺口，则更新规范

---

与其他技能集成

与 superpowers:verification-before-completion 配合使用

现有的 verification-before-completion 技能提供了一个通用框架，用于在将工作标记为完成之前进行验证。验证优先设计则在此基础上，加入 SDD 中使用的特定 6 关卡流水线和分阶段关卡系统。

二者的配合方式：

• superpowers:verification-before-completion 确保 Agent 检查自己的工作
• ck:validation-first 明确规定要运行哪些检查，以及运行顺序

使用 ck:cavekit-writing

每项规格要求都必须有映射到验证门禁的验收标准。规格编写技能定义了如何编写这些标准。验证优先设计定义了如何验证它们。

使用 ck:impl-tracking

验证结果记录在实现跟踪文档的 Test Health 表中。门禁失败会成为问题。与门禁相关的死胡同会记录在 Dead Ends 部分。

使用 ck:methodology

验证门禁在所有 Hunt 阶段持续运行。阶段门禁控制阶段之间的转换。迭代循环使用门禁结果作为收敛信号。

---

总结

1. Agent 无法验证的内容，就不会达成 — 每项要求都需要自动化验证
2. 按顺序执行 6 道门禁： 编译 → 单元验证 → 集成 → 基准测试 → 冒烟测试 → 人工审查
3. 越早执行的门禁，成本越低 — 在构建阶段而非发布时发现问题
4. 每项规格要求至少映射到一道门禁 — 未映射的要求未经验证
5. 阶段门禁控制 Hunt 阶段转换 — 当前阶段未通过门禁前，不要继续
6. 每次只合并一个 — 每次合并后进行验证，以便准确定位故障
7. 完成信号支持自动化 — 所有门禁通过后，Agent 会发出特定字符串
8. 回归属于 P0 — 通过的门禁开始失败时，先停止并修复，再继续