oh-my-claudecode 的 verify 技能实战：用证据取代"应该没问题"的完成声明

导读

本文讲解 oh-my-claudecode 项目中内置的 verify 技能（skills/verify/SKILL.md）——一套把"我觉得应该没问题"这类口头完成声明，转变成可验证、可复现证据的标准化验证流程。它适用于功能开发、缺陷修复、重构等任何需要向用户交付"确实能工作"结论的场景。读完本文，你将掌握 verify 技能的 5 步工作流、4 级验证优先级、硬性规则与输出契约，并通过仓库内的验证模块源码（src/features/verification/index.ts）、Verifier 专属 Agent（agents/verifier.md）与分层验证策略（docs/shared/verification-tiers.md）理解其底层实现与落地方式。

verify 技能是什么

verify 是 oh-my-claudecode 内置技能之一，其 frontmatter 定义如下：

name: verify
description: Verify that a change really works before you claim completion

技能的唯一目标（Goal）被定义为一句话：

Turn vague "it should work" claims into concrete evidence. （把含糊的"应该能工作"声明，转化为具体的证据。）

在 oh-my-claudecode 中，用户可以通过斜杠命令 /oh-my-claudecode:verify <target> 触发该技能（参见 docs/REFERENCE.md 与 docs/REFERENCE.md）。这一命令由 commands/verify.md 兼容性命令承载：它并不重复加载完整技能描述，而是保持 /oh-my-claudecode:verify 可用，并在被调用时去读取活动 OMC 插件安装中的 skills/verify/SKILL.md，把用户参数作为 $ARGUMENTS 交由技能处理。若从当前工作目录无法直接读取该文件，则定位到 CLAUDE_PLUGIN_ROOT / OMC_PLUGIN_ROOT、包根目录或已安装的 OMC 插件目录后继续执行。

技能触发词被注册在斜杠命令自动识别列表中（见 src/hooks/auto-slash-command/constants.ts），并在迁移文档中替代了旧的 ultraqa 命令（见 docs/MIGRATION.md）。

五步工作流：从"要证明什么"到"只报告已验证的"

SKILL.md 定义了严格的执行顺序，每一步都在缩小不确定性的范围：

1. 识别必须被证明的确切行为（Identify the exact behavior that must be proven） —— 不是笼统的"做完功能"，而是明确"哪个行为、在什么输入下、应该产生什么结果"。
2. 优先使用已有测试（Prefer existing tests first） —— 已有回归测试是最廉价、最可靠的证据来源。
3. 若覆盖缺失，运行现有最窄的直接验证命令（run the narrowest direct verification commands available） —— 选择范围最小、针对性最强的命令，避免全量构建/全量测试造成噪音。
4. 若直接自动化仍不足，描述手动验证步骤并收集具体可观察证据（describe the manual validation steps and gather concrete observable evidence） —— 手动验证不等于口头断言，必须产出可观察的现象。
5. 只报告实际已验证的内容（Report only what was actually verified）

这套"由自动到手动、由宽到窄"的思路，与仓库中验证分层策略（Verification Tiers）的取舍逻辑一脉相承：验证强度应随任务复杂度伸缩，以控制成本同时保证质量。

四级验证优先级

SKILL.md 明确规定了验证手段的优先级顺序，任何一层都不应跳过直接跳到下一层：

1. 已有测试（Existing tests）
2. 类型检查 / 构建（Typecheck / build）
3. 窄范围直接命令检查（Narrow direct command checks）
4. 手动或交互式验证（Manual or interactive validation）

这一顺序在 Verifier Agent 的 Investigation Protocol 中有更细的落地（见 agents/verifier.md）：

• DEFINE（定义）：哪些测试能证明它能工作？哪些边界情况重要？什么可能回归？验收标准是什么？
• EXECUTE（并行执行）：用 Bash 运行测试套件；用 lsp_diagnostics_directory 做类型检查；运行构建命令；用 Grep 搜索应当一并通过的相关测试。
• GAP ANALYSIS（缺口分析）：对每个验收标准标记 VERIFIED（测试存在且通过且覆盖边界）/ PARTIAL（测试存在但不完整）/ MISSING（无测试）。
• VERDICT（裁决）：PASS（全部标准验证通过、无类型错误、构建成功、无关键缺口）或 FAIL（任一测试失败、类型错误、构建失败、关键边界未测、无证据）。

类型检查/构建被放在第二优先级，与其在源码中的"必须"属性一致：在验证模块的 STANDARD_CHECKS 中，BUILD（build_success，对应 npm run build）与 TEST（test_pass，对应 npm test）均为 required 检查项（见 src/features/verification/index.ts）。

四条硬性规则：不许在无证据时宣布完成

SKILL.md 的 Rules 部分是对 Agent 行为的约束底线：

• 没有证据就不要说变更已完成（Do not say a change is complete without evidence）
• 检查失败必须明确包含失败信息（If a check fails, include the failure clearly）
• 如果不存在现实的验证路径，要明确说明，而不是虚张声势（If no realistic verification path exists, say that explicitly instead of bluffing）
• 优先给出简洁的证据摘要，而不是嘈杂的日志（Prefer concise evidence summaries over noisy logs）

这些规则在 Verifier Agent 中被强化为 Failure Modes To Avoid（见 agents/verifier.md），列出了最容易踩的坑：

• Trust without evidence（无证据的信任）：只因实现者说"它能工作"就批准。必须自己运行测试。
• Stale evidence（过期证据）：使用 30 分钟前、早于最新改动的测试输出。必须重新运行。
• Compiles-therefore-correct（能编译即正确）：只验证能构建，不验证满足验收标准。要检查行为。
• Missing regression check（缺失回归检查）：验证了新功能，却没有检查相关功能是否仍正常。要评估回归风险。
• Ambiguous verdict（含糊裁决）："基本能工作"。必须给出明确的 PASS 或 FAIL 及具体证据。

Verifier 还明确要求：验证必须是与作者分离的独立检查通道（Never self-approve），且不得出现 should / probably / seems to 这类词汇——一旦出现即视为证据不足而直接拒绝（见 agents/verifier.md 与 agents/verifier.md）。这一要求同样写入了 Prompt SSOT 的 Verifier 角色定义："It should work" is not verification（见 generated/prompt-ssot/role-verifier.md）。

输出契约：四条必答项

验证完成后，输出必须包含以下四项（不可省略）：

• 已验证了什么（What was verified）
• 运行了哪些命令/测试（Which commands/tests were run）
• 哪些通过了（What passed）
• 哪些失败了或仍未验证（What failed or remains unverified）

在仓库中，这一契约被 Verifier Agent 具体化为强制的结构化交付物（见 agents/verifier.md），其最终消息必须包含：

• Verdict：PASS | FAIL | INCOMPLETE，附 Confidence（high/medium/low）与 Blockers 计数；
• Evidence 表格：Check / Result / Command-Source / Output 四列，例如 npm test 的 X passed / Y failed、lsp_diagnostics_directory 的错误数、npm run build 的退出码；
• Acceptance Criteria 表格：每条标准对应 VERIFIED / PARTIAL / MISSING 状态及具体证据；
• Gaps：缺口描述、风险等级（high/medium/low）与关闭建议；
• Recommendation：APPROVE | REQUEST_CHANGES | NEEDS_MORE_EVIDENCE 及一句话理由。

同时有明确的 Final Response Contract：最后一次消息必须承载完整的结构化验证报告，禁止以 "done"、"complete"、"looks good" 之类的空话收尾。Verifier Agent 的前置声明（agents/verifier.md）也界定了其职责边界：负责验证策略设计、基于证据的完成检查、测试充分性分析、回归风险评估与验收标准校验，不负责编写功能（executor）、收集需求（analyst）、代码风格审查（code-reviewer）或安全审计（security-reviewer）。

源码级的证据采集：verification 模块

verify 技能所要求的"证据"，在 oh-my-claudecode 中由独立的验证模块提供统一实现。该模块被抽象为 ralph、ultrawork、autopilot 等工作流共享的单一事实来源（见 src/features/verification/README.md 与 src/features/verification/types.ts）。核心 API 与证据类型如下：

证据类型（VerificationEvidenceType）

源码定义了七种证据类型（见 src/features/verification/types.ts）：

export type VerificationEvidenceType =
  | 'build_success'      // 构建成功
  | 'test_pass'          // 测试通过
  | 'lint_clean'         // 无 lint 错误
  | 'functionality_verified' // 功能已验证
  | 'architect_approval' // 架构师审批
  | 'todo_complete'      // TODO 全部完成
  | 'error_free';        // 无未处理错误

每条 VerificationEvidence 都记录了证据类型、是否通过、运行过的命令、命令输出、错误信息与采集时间戳（timestamp: Date），这正是"只有带输出的命令结果才算证据"的工程化体现。

标准检查项（STANDARD_CHECKS）

模块预定义了七项标准检查（见 src/features/verification/index.ts），对应文档中的验证顺序与证据类型：

检查项	证据类型	对应命令	是否必需
BUILD	build_success	npm run build（TS 编译无错）	是
TEST	test_pass	npm test	是
LINT	lint_clean	npm run lint	是
FUNCTIONALITY	functionality_verified	手动功能验证	是
ARCHITECT	architect_approval	架构师评审	是
TODO	todo_complete	零 pending/in_progress 任务	是
ERROR_FREE	error_free	零未处理错误	是

执行与裁决逻辑

runVerification 支持并行/串行、failFast、skipOptional、超时与自定义工作目录等选项（见 src/features/verification/index.ts）：

await runVerification(checklist, {
  parallel: true,      // 并行运行所有检查
  failFast: false,     // 失败后是否立即停止
  skipOptional: false, // 是否跳过非必需检查
  cwd: process.cwd(),  // 工作目录
  timeout: 60000       // 单检查超时（默认 60 秒）
});

裁决由 generateSummary 给出：若存在跳过项则 verdict 为 incomplete；在 strictMode 下任一失败即 rejected；全部必需项通过则为 approved（见 src/features/verification/index.ts）。checkEvidence 还会执行证据新鲜度校验：超过 5 分钟的证据会被标记为 stale 并要求重新运行（见 src/features/verification/index.ts）——这与 Verifier Agent 对 stale evidence 的拒绝规则完全一致。

无命令的手动检查项会被标记为 requiresManualVerification: true、status: 'pending_manual_review'，不会自动通过，从而避免门禁逻辑误放行（见 src/features/verification/index.ts）。

报告可通过 formatReport 输出为 markdown（人类可读）、json（程序可读）或 text（日志友好）三种格式（见 src/features/verification/index.ts），分别对应 SKILL.md 输出契约在不同场景下的呈现。

分层验证：让验证强度随任务复杂度伸缩

verify 技能强调"用最窄的验证路径"，仓库为此提供了分层验证策略（docs/shared/verification-tiers.md），共三档：

Tier	适用条件	Agent / 模型	所需证据
LIGHT	<5 文件、<100 行、测试全覆盖	architect-low / haiku	lsp_diagnostics 干净
STANDARD	默认档（非 LIGHT 亦非 THOROUGH）	architect-medium / sonnet	诊断 + 构建通过
THOROUGH	>20 文件 或 架构/安全变更	architect / opus	全面审查 + 全部测试

选择逻辑是确定性的：涉安全或架构变更 → THOROUGH；文件数 >20 → THOROUGH；小改动且有全量测试 → LIGHT；其余 → STANDARD。用户关键词可覆盖自动判断：thorough / careful / important / critical 强制 THOROUGH，quick / simple / trivial / minor 强制 LIGHT；安全相关文件变更永远走 THOROUGH。架构变更通过 **/config.{ts,js,json}、**/schema.{ts,prisma,sql}、**/types.ts、package.json 等路径模式检测，安全影响则通过 **/auth/**、**/security/**、**/credentials?.{ts,js,json}、**/.env* 等模式识别。

该文档还给出了不同类型声明的证据要求对照表："Fixed" 需要展示现在能通过的测试；"Implemented" 需要 lsp_diagnostics 干净 + 构建通过；"Refactored" 需要所有测试仍然通过；"Debugged" 需要以 file:line 定位根因。分层设计据其估算可节省约 40% 的验证成本（相对于始终使用 THOROUGH）。

实战落地示例

结合上述全部要素，一次符合 verify 技能的验证流程可以这样组织：

1. 定义待证行为
   - 行为：修复了登录接口在空密码时的 500 错误
   - 验收标准：空密码请求返回 400 + 明确错误信息

2. 按优先级执行验证
   - 已有测试：npm test -- auth（回归套件通过）
   - 类型检查：lsp_diagnostics_directory → 0 errors
   - 构建：npm run build → exit 0
   - 窄命令：针对修复的接口发起空密码请求，观察响应

3. 缺口分析
   - 标准1（空密码→400）：VERIFIED（测试 auth.test.ts 通过）
   - 标准2（错误信息内容）：PARTIAL（测试未校验信息文本）

4. 输出契约
   - 已验证内容 / 运行的命令 / 通过项 / 失败或未验证项
   - Verdict：REQUEST_CHANGES（错误信息内容未覆盖）

若某一环节失败，按规则必须原样呈现失败信息（含命令与输出）而不是掩盖；若确实不存在自动化验证路径，则明说"该变更目前无自动化验证手段"，而非虚报"已验证"。

结语

verify 技能的本质是一套纪律：先定义"什么才算证明"，再按"已有测试 → 类型检查/构建 → 窄命令 → 手动验证"的优先级逐级收敛，最后只报告带有命令与输出的实际证据。在 oh-my-claudecode 中，这一纪律通过 agents/verifier.md 的 Agent 化、src/features/verification/index.ts 的模块化实现、docs/shared/verification-tiers.md 的分层策略以及 generated/prompt-ssot/role-verifier.md 的提示词固化得以系统性落地。对任何使用 Claude Code 或其派生工具的开发者而言，将这套"证据先行"的验证流程引入自己的工作习惯，都能显著降低"声称完成、实则带病上线"的风险。