验证协议与质量门控——7 维检查与证据时效

学习目标

• 理解 OMC 的 7 维度验证标准设计
• 掌握证据新鲜度约束的原理与实现
• 设计自己的验证循环与质量门控
• 识别假阳性通过和验证疲劳的陷阱

前置知识

多维度验证标准与证据驱动的门控设计已在通用知识中介绍：

• 验证协议与质量门控

下文假设你已理解标准门控、降级门控、循环门控等基础模式，直接聚焦 OMC 的 7 维检查与证据时效约束 的具体实现。

项目实践

OMC 的 7 维度验证标准

OMC 定义了一组标准化的验证检查项，用于确认工作完成的质量：

检查项	验证内容	证据形式	OMC 实现
BUILD	编译通过，无语法错误	构建命令输出（exit code 0）	npm run build / tsc
TEST	所有测试通过	测试运行输出	npm run test:run
LINT	无代码风格错误	Linter 输出	eslint src
FUNCTIONALITY	功能按预期工作	功能测试截图/日志	Agent 主观验证
ARCHITECT	架构设计评审通过	Opus-tier Agent 评审意见	oh-my-claudecode:architect 审查
TODO	所有待办任务已完成	Task 状态	TaskList 全 completed
ERROR_FREE	无未解决的错误	错误日志为空	控制台无 error 级消息

证据新鲜度约束

OMC 的验证协议要求证据必须在有限时间窗口内生成：

• 证据时效要求：验证证据必须在 5 分钟内生成
• 过时的证据被视为无效：如果测试运行结果超过 5 分钟，需要重新运行

SubagentStop 验证流水线

OMC 在 SubagentStop 事件上注册了两个 Hook：

1. subagent-tracker.mjs：记录 Agent 停止状态
2. verify-deliverables.mjs：验证 Agent 产出是否满足交付标准

// hooks/hooks.json 中 SubagentStop 的注册
"SubagentStop": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "node .../subagent-tracker.mjs stop",
        "timeout": 5
      },
      {
        "type": "command",
        "command": "node .../verify-deliverables.mjs",
        "timeout": 5
      }
    ]
  }
]

这意味着每个 Agent 完成工作时，OMC 自动验证其产出——不依赖 Agent 自行声明”已完成”。

Ralph 的 PRD 驱动验证

在 Ralph 持久循环中，验证更为严格：

• PRD 模式：prd.json 定义了用户故事和验收标准
• 逐故事验证：每个故事完成后，Reviewer Agent 对照验收标准独立验证
• 验证通过后标记：只有 Reviewer 确认通过，故事的 passes 才设为 true
• 全部通过才退出：所有故事的 passes 都为 true 后，Ralph 循环才能退出

Team 的五阶段质量门

Team 编队使用 team-plan → team-prd → team-exec → team-verify → team-fix (loop) 的五阶段流水线：

• team-verify：独立验证阶段，运行构建、测试、lint
• team-fix：验证失败时自动进入修复循环
• 循环约束：最大修复次数有限制，防止无限循环

问题与规避

问题 1：假阳性通过

Agent 声称”测试全部通过”，但实际跳过了某些测试文件。

规避策略：验证命令必须显式指定全部测试文件，检查测试输出中的实际运行数量。

问题 2：验证疲劳

过多的检查项导致 Agent 跳过部分验证。

规避策略：OMC 根据任务类型动态选择检查项子集——简单任务用精简门控（BUILD + TEST），大任务用完整门控。

问题 3：跨 Agent 状态不一致

多个 Agent 并行工作时，一个 Agent 的验证结果被另一个 Agent 的修改污染。

规避策略：OMC 通过工作树隔离（git worktree）确保每个 Agent 在独立的环境中验证。

设计取舍

为什么设置 5 分钟时效约束？

时间窗口	优点	缺点
1 分钟	证据极其新鲜	验证命令频繁执行，浪费资源
5 分钟	平衡新鲜度与效率	可能错过 5 分钟内的中间状态变更
30 分钟	减少验证频率	证据可能已不代表当前状态

OMC 的选择：5 分钟是经验上的平衡点——足够短以保证证据新鲜，足够长以避免频繁验证的资源浪费。

为什么用独立 Hook 验证而非 Agent 自行验证？

维度	Hook 独立验证	Agent 自行验证
可靠性	高——独立于 Agent 的判断	低——Agent 可能高估自己的工作质量
一致性	高——所有 Agent 使用同一验证标准	低——每个 Agent 的验证标准不同
成本	低——Hook 是轻量级脚本	高——需要额外的 LLM 调用

OMC 的选择：使用独立的 Hook 脚本（verify-deliverables.mjs）进行自动验证，而非依赖 Agent 自行声明。

参考来源

• OMC Architecture - Verification Protocol — 验证协议的官方文档
• Claude Code /goal 文档 — 原生目标循环与验证