使用验证分级体系为 Oh My ClaudeCode 配置按任务复杂度伸缩的 LIGHT / STANDARD / THOROUGH 验证策略

导读

在 Oh My ClaudeCode（OMC）这类以多 Agent 编排为内核的项目中，"验证"（verification）的质量与成本之间存在天然矛盾：每次都做全量深度评审既昂贵又拖慢迭代，每次都做轻量检查又容易放走回归。verification-tiers.md 文档给出的答案是一套**三级验证分级（Verification Tiers）**机制，让验证强度随任务复杂度伸缩——小型、有测试覆盖的改动走低成本快速通道，涉及架构或安全的改动无条件升级到全量深度评审。阅读本文后，你将完整掌握 LIGHT / STANDARD / THOROUGH 三级判定的规则、阈值与优先级、触发升级的关键词与文件路径模式、配套的证据（Evidence）要求，以及它在源码中的实际实现（tier-selector.ts）与 ralph 持久化模式下的验证流水线集成方式，从而在自己的 Claude Code 工作流中复现"既省成本又不失质量"的验证策略。

为什么需要分级验证：成本与质量的权衡

原文对分级验证的出发点给了一句精准概括：Verification scales with task complexity to optimize cost while maintaining quality（验证强度随任务复杂度伸缩，以在优化成本的同时守住质量）。

在 Oh My ClaudeCode 的 Agent 编排体系里，验证并非一次"顺便的检查"，而是一次独立的、由专职 Agent 承担的审查行为。从 agents/verifier.md 的约束可以看到，验证 Agent 被明确要求"使用独立 reviewer 通道、不能自我批准"，且没有新鲜证据一律拒绝通过——例如出现 "should / probably / seems to" 等措辞、没有新鲜的测试输出、对 TypeScript 改动没有做类型检查等情况，直接 reject。这种"验证必须独立、必须取证"的原则如果一律套用最重的方式执行，Token 成本会线性膨胀。

分级验证正是为了解决这个矛盾：把验证任务按"改动规模 + 影响面"拆分成三档，每一档匹配不同强度的验证 Agent、模型与证据要求，让每一分 Token 都花在刀刃上。

三级验证体系（Tier Definitions）

verification-tiers.md 用一张对照表给出了三级验证的完整定义，这是整套机制的核心骨架：

Tier	判定条件（Criteria）	验证 Agent	模型	所需证据（Evidence Required）
LIGHT	<5 个文件、<100 行变更、测试覆盖完整（full test coverage）	architect-low	haiku	lsp_diagnostics clean
STANDARD	默认档（既不满足 LIGHT 也不满足 THOROUGH）	architect-medium	sonnet	diagnostics + build pass
THOROUGH	>20 个文件 或 涉及架构/安全改动	architect	opus	Full review + all tests

三个层级分别对应 Agent 能力、模型算力与证据标准的逐级抬升：

• LIGHT 面向"单文件 bug 修复且已有测试覆盖"这类低风险改动，使用最低配的 architect-low + haiku，只要求 lsp_diagnostics 干净即可；
• STANDARD 是默认档，面向多文件功能新增，使用 architect-medium + sonnet，要求类型诊断干净且构建通过；
• THOROUGH 面向大规模重构、架构调整与安全相关改动，使用最高配 architect + opus，要求完整架构评审 + 全部测试通过。

从实现看，这三档配置被编码在 tier-selector.ts 的 TIER_AGENTS 常量表中，每个 tier 对应 { agent, model, evidenceRequired[] } 三元组，其中 THOROUGH 的证据要求是 ['full architect review', 'all tests pass', 'no regressions'] 三条。这里的 architect-low / architect-medium / architect 三个验证 Agent 与 agent-tiers.md 中 Analysis 领域的 LOW（Haiku）/ MEDIUM（Sonnet）/ HIGH（Opus）三档能力矩阵一一对应，可视为同一套 Agent 分级机制在"验证"场景下的复用。

选择接口：ChangeMetadata 数据契约

分级选择不是靠"感觉"，而是靠结构化元数据驱动。verification-tiers.md 给出了选择函数的输入接口 ChangeMetadata 与输出类型 VerificationTier：

interface ChangeMetadata {
  filesChanged: number;
  linesChanged: number;
  hasArchitecturalChanges: boolean;
  hasSecurityImplications: boolean;
  testCoverage: 'none' | 'partial' | 'full';
}

type VerificationTier = 'LIGHT' | 'STANDARD' | 'THOROUGH';

在 tier-selector.ts 中，这两个类型原样落地，并额外补充了一个 VerificationAgent 接口来承载选定 tier 的 { agent, model, evidenceRequired } 产出。testCoverage 是区分"能否进入 LIGHT"的关键开关——它只有 none | partial | full 三态，其中只有 full 才有资格申请轻量验证。

选择逻辑：判定的优先级顺序

文档用一段类似决策树伪代码完整描述了选择函数的核心判定流程：

IF hasSecurityImplications OR hasArchitecturalChanges:
  → THOROUGH (always for security/architecture)
ELIF filesChanged > 20:
  → THOROUGH (large scope)
ELIF filesChanged < 5 AND linesChanged < 100 AND testCoverage === 'full':
  → LIGHT (small, well-tested)
ELSE:
  → STANDARD (default)

这四步逻辑在 tier-selector.ts 的 selectVerificationTier 函数中被逐行实现。需要注意两点设计意图：

1. 安全与架构改动无条件优先，即便改动只有 1 个文件 5 行，只要涉及安全或架构，也会直接进入 THOROUGH——这是整套机制中最硬的约束；
2. LIGHT 是"末位竞逐"：它必须同时满足"文件少、行数少、测试全覆盖、且不触碰架构/安全"，任何一项不满足都会被降级为 STANDARD。

选择函数是纯函数，易于单测。其测试覆盖见 tier-selector.test.ts，包括：2 文件/50 行/全覆盖 → LIGHT；1 文件/5 行但 hasSecurityImplications → THOROUGH；25 文件 → THOROUGH；10 文件/200 行/部分覆盖 → STANDARD 等。

边界条件的精确判定（值得注意的临界值）

selectVerificationTier 中的比较运算全部是开区间，边界值行为容易误判，而源码测试对此做了精确固化。从 tier-selector.test.ts 的 boundary values 测试组可以提炼出以下事实：

输入	结果	原因
恰好 5 个文件、50 行、full coverage	STANDARD	LIGHT 要求 filesChanged < 5，5 恰好在边界外
恰好 100 行、3 个文件、full coverage	STANDARD	LIGHT 要求 linesChanged < 100，100 恰好在边界外
恰好 21 个文件	THOROUGH	THOROUGH 要求 > 20，21 满足
恰好 20 个文件	STANDARD	20 未超过 > 20 阈值
0 文件 0 行、full coverage	LIGHT	同时满足三个小于条件即落入 LIGHT

另有 edge cases 测试组（tier-selector.test.ts）补充了两条边界语义：testCoverage: 'none' 时必然落在 STANDARD（无测试就不可能轻量放行）；空文件列表也能安全构造元数据（buildChangeMetadata([], 0) 不抛异常）。

Override Triggers：用自然语言关键词覆盖自动判定

纯自动判定无法覆盖所有场景，因此文档定义了用户关键词对自动检测结果的覆盖（override）规则：

Keyword	Forces Tier
"thorough", "careful", "important", "critical"	THOROUGH
"quick", "simple", "trivial", "minor"	LIGHT
Security-related file changes	THOROUGH (always)

这意味着在交付 prompt 中携带"请谨慎处理（careful）/ 这是关键路径（critical）"等信号时，验证会自动升档；反之说"简单改一下（simple/minor）"则会请求降档。注意安全类文件路径属于无条件强制 THOROUGH，不依赖关键词即可触发，关键词与路径检测共同构成两条互补的升档通道。

架构变更检测（Architectural Change Detection）

verification-tiers.md 明确了会令 hasArchitecturalChanges 置真的文件清单：

• **/config.{ts,js,json}
• **/schema.{ts,prisma,sql}
• **/definitions.ts
• **/types.ts
• package.json
• tsconfig.json

其实现位于 tier-selector.ts 的 detectArchitecturalChanges。值得注意的一个工程细节：正则模式并不完全等价于文档中的 glob。源码中 types.ts 使用 /(?:^|\/)types\.ts$/i 锚定在路径段的起点或分隔符之后，而 definitions.ts 使用 /definitions\.ts$/i 不做段级锚定，config 与 schema 亦不做锚定——这意味着在源码的规则下，改动清单里只要出现任意名为 config.ts/schema.sql 的文件（无论所在目录层级）都会触发架构升档。配套测试（tier-selector.test.ts）验证了 prisma/schema.prisma、db/schema.sql、src/definitions.ts、package.json、tsconfig.json 均会被检出，而普通源文件 src/utils/helper.ts、src/components/Button.tsx 不会被误报。

这类路径之所以被归类为"架构级"，是因为改动它们会牵动整个项目的契约面：配置与 tsconfig.json/package.json 影响构建与运行环境，schema 与 types/definitions 影响跨模块的数据契约，一旦出错往往不是局部问题，而是系统性回归。

安全影响检测（Security Implication Detection）

安全检测的路径模式在文档中列出如下：

• **/auth/**
• **/security/**
• **/permissions?.{ts,js}
• **/credentials?.{ts,js,json}
• **/secrets?.{ts,js,json,yml,yaml}
• **/tokens?.{ts,js,json}
• **/passwords?.{ts,js,json}
• **/oauth*
• **/jwt*
• **/.env*

对应的实现位于 tier-selector.ts 的 detectSecurityImplications。实现将文档模式翻译为正则时做了更工程化的收紧：例如对 auth/、security/ 目录要求目录段分隔（\/auth\/），对 permissions/credentials/secrets/tokens/passwords 要求词边界（(^|[\/-]) 前缀），并把 .env、.pem、.key 文件收敛为 \.(env|pem|key)(\.|$) 一条规则，从而避免把大量含子串的文件误判为安全文件。

防误报工程：正则模式的反面测试

文档只给出了"会命中"的正向模式，但真实项目中正则匹配最怕的是误报。源码测试对此专门设计了 false-positive prevention 测试组（tier-selector.test.ts），它们是由文档模式在实现时演化出的关键反例：

安全检测的防误报：

• src/utils/tokenizer.ts 不命中（含 token 子串但不是安全文件）
• src/lexer/StringTokenizer.ts 不命中
• src/admin/secretariat.ts 不命中
• src/blockchain/permissionless.ts 不命中
• 而 src/auth/token.ts、config/secrets.yaml、.env.local、src/permissions.ts、src/auth/oauth2.ts、src/oauth2-client.ts、src/jwt_utils.ts 均正确命中

架构检测的防误报：

• src/components/index.ts（barrel 聚合导出）不命中
• src/utils/helpers/index.ts（嵌套 barrel）不命中
• 而 src/config.ts、package.json、tsconfig.json 仍正确命中

这组反例说明：分级机制真正落地时要经受"安全文件必须 100% 升档、普通文件名不得误伤"的双向校验，任何一边失衡都会导致成本失控或安全漏检。

证据类型与所需证据（Evidence Types）

分级不只是"派谁去查"，更是"拿什么来证明"。verification-tiers.md 按声明的类型规定了所需证据：

Claim（声明的完成类型）	Required Evidence（必须证据）
"Fixed"	Test showing it passes now（测试证明现在能通过）
"Implemented"	lsp_diagnostics clean + build pass（诊断干净 + 构建通过）
"Refactored"	All tests still pass（全部测试仍然通过）
"Debugged"	Root cause identified with file:line（定位到 file:line 的根因）

这四种 claim 是验证 Agent 在收到"任务已完成"声明时需要核对的四种典型话术。与之呼应的是 agents/verifier.md 中 Verifier 角色的硬性约束——拒绝"应该能跑（should work）"这类无证据的措辞，要求自己运行测试、类型检查与构建命令获取新鲜输出，并以 VERIFIED / PARTIAL / MISSING 三态对每条验收标准标注证据状态，最终给出 PASS / FAIL / INCOMPLETE 的明确裁决。也就是说：验证分级决定"用多大的力度去查"，而验证 Agent 契约决定"查到什么程度才算查完"。

成本对比与收益估算

文档给出了三档的量化成本模型：

Tier	Relative Cost	Use Case
LIGHT	1x	Single-file bug fixes with tests
STANDARD	5x	Multi-file feature additions
THOROUGH	20x	Major refactoring, security changes

成本差异主要来自两个维度：模型单价（haiku → sonnet → opus 逐级上升）与验证 Agent 的审查工作量（单文件诊断 → 诊断+构建 → 全量评审+全量测试）。按文档估算，相对"一律使用 THOROUGH"的做法，分级验证体系可带来约 40% 的验证成本削减——这既是 LIGHT/STANDARD 档"降配"节省的算力，也是高风险改动"保底升档"避免的返工成本。需注意该 40% 为文档中给出的估算结论，实际节省比例取决于工作负载中低风险改动的占比。

在持久化模式中的接入方式：ralph / autopilot 集成

文档明确要求所有持久化模式（ralph、autopilot）在派生验证 Agent 之前先调用 tier-selector，并给出了集成示例：

import { selectVerificationTier, getVerificationAgent } from '../verification/tier-selector';

const tier = selectVerificationTier(changeMetadata);
const { agent, model } = getVerificationAgent(tier);

// Spawn appropriate verification agent
Task(subagent_type=`oh-my-claudecode:${agent}`, model, prompt="Verify...")

其中 selectVerificationTier(changeMetadata) 负责决策，getVerificationAgent(tier)（实现于 tier-selector.ts）负责把决策映射为具体的 { agent, model }，最终通过 Claude Code 的 Task(subagent_type, model) 原语按选中档位派生验证子 Agent。

这一设计与 ralph 模式的真实验证流水线是自洽的。从 src/hooks/ralph/verifier.ts 可以看到 ralph 的验证流程骨架：ralph 声称任务完成 → 系统进入验证模式 → 派生 architect（或按模式切换为 critic/codex）等审查 Agent 核查工作 → 若通过则真正完成，若发现缺陷则携带评审反馈回到 ralph 继续修复。分级选择逻辑（选 architect-low / architect-medium / architect 中的哪一个、配什么模型）正是在这个"派谁去验证"的岔路口发挥作用。从仓库结构看，tier-selector 以独立模块形式存在于 src/verification/ 目录，其当前的主要消费方即 ralph、autopilot 等持久化模式，以及后续其他需要"先分级再验证"的 Agent 流水线。

落地实践建议：如何把分级验证用起来

综合文档与源码，接入这套机制的关键步骤可以归纳为四点：

1. 构建变更元数据：改动完成后，通过 buildChangeMetadata(files, linesChanged, testCoverage)（tier-selector.ts）汇总文件清单与行数，让架构/安全检测自动完成；testCoverage 参数默认 'partial'，务必在测试确实覆盖时显式传入 'full'，否则无法进入 LIGHT 档。
2. 始终尊重硬性升档：凡改动清单命中 auth/、security/、secrets、.env 等安全模式，或命中 config/schema/types/package.json/tsconfig.json 等架构模式，无条件接受 THOROUGH 判定，不要用关键词试图压档。
3. 在派生前分级：把 selectVerificationTier 放在验证 Agent 派生语句（Task(...)）之前执行，用 getVerificationAgent 的返回值动态拼装 subagent_type 与 model，即可让验证成本随风险自动伸缩。
4. 证据对号入座：验证 Agent 报告验收结果时，按文档的 Evidence Types 表区分 claim——"Fixed" 必须有能证明"现在通过"的测试，"Debugged" 必须给出 file:line 级别的根因定位，避免口头确认代替实证。

小结

verification-tiers.md 所定义的 LIGHT / STANDARD / THOROUGH 三级验证机制，本质上是为"验证"这一昂贵动作引入的风险分诊器：用可量化的变更元数据（文件数、行数、测试覆盖）+ 路径模式（架构、安全）+ 用户关键词共同决策验证强度，再通过 TIER_AGENTS 表把决策翻译成具体的 Agent 与模型组合。它的价值不只在于"省钱"——文档估算的约 40% 成本削减源于对低风险改动的降配处理；更在于把 THOROUGH 这种 20 倍成本的深度评审无保留地留给真正值得它的架构与安全改动。这套模式在 Oh My ClaudeCode 中已有完整落地：决策逻辑在 tier-selector.ts，边界行为与防误报规则由 tier-selector.test.ts 固化，验证的执行语义由 agents/verifier.md 的"证据优先"契约约束，并与 ralph 的 verifier.ts 验证流水线衔接——是"按复杂度伸缩验证强度、以成本换质量与质量换成本之间的工程平衡"的可直接复用的参考实现。