验证协议与质量门控

验证协议与质量门控

学习目标

读完本章后，你将能够：

• 设计多维度验证检查（BUILD/TEST/LINT/FUNCTIONALITY/REVIEW/TODO/ERROR_FREE）
• 实现证据驱动的质量门控，防止假阳性通过
• 应用证据时效约束（Evidence Freshness），避免过时证据误导
• 区分不同角色的质量门：QA 测试、代码审查、架构评审

---

核心概念

多维度验证标准

AI Agent 的验证不能依赖单一指标。一个完整的质量门控应覆盖以下维度：

检查项	验证内容	证据形式
BUILD	代码编译通过，无语法错误	构建命令输出（exit code 0）
TEST	所有测试通过，无回归失败	测试运行输出（pass count）
LINT	无代码风格或静态分析错误	Linter 输出（empty or all clear）
FUNCTIONALITY	功能按预期工作	手动或自动化功能测试截图/日志
ARCHITECT	架构设计评审通过	架构师 Agent 的评审意见
TODO	所有待办任务已标记完成	Task 状态（completed count）
ERROR_FREE	无未解决的错误	错误日志（empty）

重要：不是所有项目都需要全部 7 项检查。根据项目类型选择合适的子集。

证据新鲜度约束

验证证据必须在有限时间窗口内生成（通常 5 分钟）。过时的证据无法代表当前状态：

✅ 有效证据：测试运行于 14:32:00，当前时间 14:34:00（2分钟前）
❌ 过期证据：测试运行于 14:00:00，当前时间 14:34:00（34分钟前）

为什么需要新鲜度约束？

1. Agent 可能在”旧测试通过”后又修改了代码
2. 依赖版本可能在验证后发生了变更
3. 并行 Agent 可能在验证期间引入了冲突

证据驱动的门控设计

质量门控的核心原则是：所有声明必须有证据支撑。

---

质量门控模式

模式一：标准门控（Standard Gate）

最常见的模式——所有检查项必须全部通过。

BUILD ✅ + TEST ✅ + LINT ✅ = 门控通过
BUILD ✅ + TEST ❌ + LINT ✅ = 门控失败

适用场景：常规功能开发、Bug 修复

模式二：降级门控（Degraded Gate）

在特定条件下允许部分检查项跳过。

BUILD ✅ + TEST ⚠️ (已知 flaky) + LINT ✅ = 降级通过

适用场景：紧急修复、已知 flaky 测试不影响本次变更

模式三：角色门控（Role-Based Gate）

不同角色使用不同的验证标准：

角色	必须通过	可选
工程师	BUILD + TEST	LINT
架构师	BUILD + ARCHITECT	TEST
QA	TEST + FUNCTIONALITY	BUILD

模式四：循环门控（Looping Gate）

验证失败时自动触发修复循环，直到通过或达到最大迭代次数：

迭代 1: TEST ❌ → 修复 → 迭代 2
迭代 2: TEST ❌ → 修复 → 迭代 3
迭代 3: TEST ✅ → 门控通过

安全约束：必须设置最大迭代次数（如 5 次），防止无限循环。同一错误连续 3 次未修复时，停止循环并报告根本问题。

---

常见陷阱与规避策略

陷阱 1：假阳性通过

Agent 声称”测试全部通过”，但实际上跳过了某些测试文件或使用了过时的测试结果。

规避策略：

• 验证命令必须显式指定全部测试文件（如 npm test -- --run）
• 检查测试输出中的实际运行数量，而非仅检查 exit code
• 要求证据包含时间戳

陷阱 2：验证疲劳

过多的检查项导致 Agent 跳过部分验证或敷衍执行。

规避策略：

• 根据任务类型动态选择检查项子集
• 小任务用精简门控（BUILD + TEST），大任务用完整门控
• 设置检查项的优先级，必须项不可跳过

陷阱 3：证据伪造

Agent 生成假的测试通过输出或篡改验证结果。

规避策略：

• 使用独立的验证 Agent 而非同一个执行 Agent
• 交叉验证：同一检查由不同 Agent 独立执行
• 验证输出的结构化解析（如解析 JSON 测试报告而非自由文本）

陷阱 4：跨 Agent 状态不一致

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

规避策略：

• 在验证前冻结代码状态（如通过 git stash）
• 每个 Agent 在独立的工作树中验证
• 验证结果与工作树绑定

---

设计权衡

维度	严格门控	宽松门控
安全性	高	低
速度	慢（每次验证都需要时间）	快
适用场景	生产部署、安全修复	原型开发、实验性变更
维护成本	高（需要持续更新验证规则）	低

推荐实践：默认使用严格门控，在明确标注的情况下允许降级。降级决策和理由必须记录在案。

---

参考来源

• Claude Code /goal 文档 — 原生目标循环与验证
• Anthropic Claude Code Changelog — 验证能力更新