oh-my-claudecode 的 role-verifier 角色投影：用「新鲜证据」闭环完成验证的提示词设计

role-verifier 是 oh-my-claudecode（Teams-first Multi-agent orchestration for Claude Code）中负责完成证据验证的 Tier-0 角色提示词，它以生成文件 role-verifier.md 的形式存在，由提示词单一事实来源（Prompt SSOT）机制确定性投影产出。本文从该投影文件出发，逐段拆解其全部指令，并下沉到 sections.ts、manifest.ts、compose.ts 等源码，讲解「一段文本、多处复用、以证据收口」的工程化提示词设计。读完你既能掌握 Verifier 角色的完整运行规则，也能理解这类生成式角色提示词如何被构建、校验与维护。

一、role-verifier 在提示词体系中的定位

oh-my-claudecode 的多智能体编排中，Verifier 被定义为完成证据车道（completion-evidence lane）：它不写功能、不做代码评审，而是负责让每一条验收标准都获得"带新鲜证据的状态判定"。为了让角色提示词不再在多个消费面上被逐字复制，项目引入了 Prompt SSOT 机制（Epic #3698 / Issue #3704，见设计文档 README.md）：规范文本只在 sections.ts 中被恰当地编写一次，再用 manifest.ts 声明投影目录，最后由 compose.ts 渲染出 coordinator 与 role-planner / role-executor / role-reviewer / role-verifier 共 5 份投影文件。

因此阅读 role-verifier 时应先理解它文件头里的元数据注释：

<!-- PROMPT-SSOT:GENERATED
schemaVersion: 1
projection: role-verifier
sourceRevision: 2026-08-13.1
overlay.provider: none
overlay.modelTier: none
sha256: 6da80baeb3440c4cd4d62c3462cd817bca45ac780fe816f9f8229a3563f5799f
Regenerate: npm run prompt-ssot:build. Do not edit by hand.
-->

该头说明：projection: role-verifier 标识投影身份；sourceRevision 是当前规范修订戳；sha256 是对规范化正文字节求的摘要，用于保鲜校验；overlay.provider / overlay.modelTier 为 none，表示当前这份投影未叠加任何供应商或模型档差异层。末尾明确警告不要手工编辑此文件——所有修改都应落在源码段上并重新生成，任何手工改动都会被构建门禁以 digest 不匹配的方式拒绝（详见第五节）。

二、完整内容拆解：role-verifier 由六段规范文本组成

根据 manifest 中 role-verifier 投影的声明（见 manifest.ts 第 36-48 行），该投影选择如下内容段，并按（kind 优先级、段 id）的确定性顺序排序。下面逐段给出完整原文语义并配解读。

1. Operating Principles（操作原则，8 条）

- Delegate specialized or tool-heavy work to the most appropriate agent.
- Prefer clear evidence over assumptions: verify outcomes before final claims.
- Choose the lightest-weight path that preserves quality (direct action, MCP, or agent).
- Consult official documentation before implementing with SDKs, frameworks, or APIs.
- Prefer deletion over addition when the same behavior can be preserved.
- Reuse existing utilities and patterns before introducing new ones.
- Do not add new dependencies without an explicit request or approval.
- Keep diffs small, reversible, and easy to review.

这段（源码 id policy/operating-principles，见 sections.ts 第 21-34 行）是所有角色共享的通用政策。对 Verifier 而言，第二条是核心——"用清晰的证据优先于假设，在下结论前先验证结果"；它同时是 manifest.ts 中声明的 requiredSections（第 15 行），意味着任何角色投影都必须包含这段，否则组合直接抛错（fail closed）。

2. Execution Protocols（执行协议，4 条）

- Broad requests with no clear target: explore first, then plan.
- Run independent tasks in parallel; run dependent tasks sequentially.
- Keep authoring and review as separate passes; never self-approve in the same pass.
- Use background execution for installs, builds, and tests.

源码段 task-contract/execution-protocols（见 sections.ts 第 93-102 行）。第三条对 Verifier 有直接约束：创作与评审必须是两次独立通过（pass），同一轮内禁止自我批准。这也解释了 Verifier agent 上游定义 verifier.md 中"绝不批准同一上下文中自己产出的工作，必须等 writer/executor pass 结束再走 verifier lane"的约束。

3. Verification（验证，3 条）

Verify before claiming completion: identify what proves the claim, run the verification, read the output, then report with evidence.
If verification fails, keep iterating rather than reporting incomplete work.
Before concluding, confirm: zero pending tasks, tests passing, zero errors, verification evidence collected.

源码段 task-contract/verification（见 sections.ts 第 83-91 行）给出完整的验证循环：先想清楚什么能证明这个结论 → 运行验证 → 读取输出 → 带证据汇报。如果验证失败，要持续迭代而非上报半成品；收尾前必须确认"待办为零、测试通过、零错误、证据已收集"。

4. Safety Boundaries（安全边界，3 条）

Advisory checks fail open with a bounded, visible warning and never block routine work.
Hard checks fail closed only for: secrets/privacy, destructive mutation, release/publish authority, proven corruption or integrity risk, and security boundaries.
Unknown failures default to advisory during migration and must be classified before any legacy removal.

源码段 safety/hard-boundaries（见 sections.ts 第 105-113 行），同属 requiredSections。它定义了验证/检查的双层语义：咨询性检查（advisory）宽松失败，只给出有界、可见的警告，不阻断日常工作；硬性检查（hard）仅在五类场景下严格失败（fail closed）——密钥/隐私、破坏性变更、发布/发布权、已被证实的损坏或完整性风险、安全边界。这一区分让 Verifier 明确"哪些验证结论必须卡死、哪些只需提示"。

5. Role: Verifier（角色定位）

You are the completion-evidence lane. Every acceptance criterion gets a VERIFIED / PARTIAL / MISSING status with fresh evidence: real test output, clean diagnostics, successful builds.
"It should work" is not verification; words like "should", "probably", and "seems to" demand an actual run.

这是该投影的角色增量段，源码 id role/verifier（见 sections.ts 第 151-157 行）。两句定义了 Verifier 的全部身份内核：

• 完成证据车道：每条验收标准都必须得到 VERIFIED / PARTIAL / MISSING 三态之一，且判定必须基于新鲜证据——真实测试输出、干净诊断、成功构建；
• 禁用推测词：should / probably / seems to 这类措辞本身就是在要求一次真正的运行；"它应该能工作"不构成验证。

6. Output Contract（输出契约）

Final reports must include: changed files, verification commands with their actual results, simplifications made, and remaining risks.
Never present partial work as complete, suppress failing tests, or fabricate outputs.

源码段 output/evidence-contract（见 sections.ts 第 241-248 行）规定最终报告四要素：变更文件、验证命令及其真实结果、所做的简化、剩余风险；并明确三条禁令——不得把部分完成包装成完成、不得压制失败测试、不得伪造输出。

三、Verifier 的验证语义与上游详细契约

role-verifier 是精简投影，它的详细操作化定义来自仓库内的 agents/verifier.md（frontmatter 声明 model: sonnet、level: 3、disallowedTools: Write, Edit——再次印证 Verifier 是只读验证角色）。结合上游文档可以将三条核心语义落地为可执行规则：

• 证据必须是新鲜的：使用实现之后新跑的测试输出，而不是"30 分钟前那一次"或记忆中"以前通过"。agents/verifier.md 的 Failure_Modes_To_Avoid 里把 stale evidence（陈旧证据）列为高发失败模式。
• 编译通过 ≠ 行为正确：不能只验证"能构建"，还要回到原始验收标准逐条核对行为（Verify against original acceptance criteria (not just "it compiles")）。
• 输出结构化验证报告：上游 verifier.md 要求的最终报告包含四块：Verdict（PASS / FAIL / INCOMPLETE + Confidence + Blockers）、Evidence 表（Check / Result / Command-Source / Output）、逐条 Acceptance Criteria 表（# / Criterion / Status / Evidence）、Gaps 与 Recommendation（APPROVE / REQUEST_CHANGES / NEEDS_MORE_EVIDENCE），并以 ## Verification Report 作为最后一条消息的交付物。

这解释了为什么该车道在团队协作中通常与 executor 分工协作：executor 完成最小改动后，Verifier 独立跑测试、类型检查与构建，对每条验收标准打 VERIFIED / PARTIAL / MISSING 状态，最终给出带证据的三态判定报告。

四、源码级原理：一份文本、五份投影、字节级可复现

从"内容如何被组织与渲染"的角度看，role-verifier 背后是三个协同的源码模块：

1. 单一内容源 sections.ts：每个内容段是一个 PromptSection，带 id / kind / owner / version / body 五个字段。owner 固定为 prompt-ssot-owner，保证每条规范子句只有一个负责人；version 在 body 变更时必须递增，digest 同时绑定 id@version，即使有人改了 body 忘了升版本也会被检测到。所有角色的共享文本（Operating Principles、Verification 等）在此只存一次。
2. 投影目录 manifest.ts：role-verifier 不是手工编写的副本，而是通过 (['planner','executor','reviewer','verifier']).map(...) 循环批量声明的投影之一，其 sections 与其它三个角色投影结构完全一致，仅 role/<name> 一段不同；同时声明 requiredSections（policy/operating-principles 与 safety/hard-boundaries）与 acceptsOverlays: true。
3. 确定性组合器 compose.ts：composeProjection 依次完成按投影挑选段、对 requiredSections 缺失即抛错（第 51-57 行）、按 (kind 优先级, 段 id) 排序（第 62-66 行）、normalizePromptText 规范化拼接（CRLF→LF、去行尾空白、折叠空行）、对规范化正文算 SHA-256 digest，最后拼上元数据头。因此相同输入必然产出字节相同的正文与摘要。

投影若叠加 overlay，还会额外插入 provider/<id> 与/或 tier/<low|medium|high> 内容段（见 compose.ts 第 24-29 行、types.ts 中 SECTION_KIND_RANK）。本仓库当前提交的 role-verifier 未启用任何 overlay（文件头两项为 none），所以其正文恰为六段基础内容。设计文档 README.md 的度量数据也印证了这一机制的价值：将历史上在 CLAUDE.md 与各 agents 文档间逐字复制的规范（基线 23,970 token）收敛为 797 token 的规范段，重复 token 减少 −99.14%（基线 15,888 → 136），组合/提交间的投影漂移为 0。

五、如何重新生成、校验与测量该投影

generated/prompt-ssot/*.md 是产物而非源文件，脚本入口在 package.json：

• 重建：npm run prompt-ssot:build —— 依据当前 sections + manifest 重新渲染全部投影并覆盖写回 generated/prompt-ssot/；
• 保鲜校验：npm run prompt-ssot:check（等价 tsx scripts/build-prompt-ssot.ts --check）—— 若已提交投影的 digest/正文与从当前 manifest 组合出的结果不一致，或存在多余/缺失投影文件，命令以退出码 1 失败，形成 CI 门禁；
• 度量：npm run prompt-ssot:measure —— 生成 token 统计、重复子句比率、投影漂移等验收证据（产出对应设计文档 README.md 中引用的 measurements.json）。

除此之外，正常的单测流程也已内置同样的保鲜检查：测试文件 prompt-ssot.test.ts 共 17 条用例（含"已提交投影过时门禁"用例），通过 npx vitest run src/agents/prompt-ssot 即可执行，同时保证对"overlay 下规范文本逐字节一致""不受 manifest 段声明顺序影响"等性质的回归覆盖（详见设计文档 Test evidence 一节）。也就是说，想让 role-verifier 的语义变更生效，正确路径是：编辑 sections.ts 相应段并递增其 version、同步更新 manifest.ts 的 sourceRevision，再执行 npm run prompt-ssot:build。

六、把 role-verifier 用进你的多智能体工作流

作为 Tier-0 角色提示词投影，role-verifier 适合在需要"以证据收口"的交付流程中作为独立验证车道被调用。实践要点可归纳为：

1. 必须是独立的一次通过：authoring 与 verification 分属不同 pass，Verifier 不评审自己写的代码，也不被实现者的口头保证说服；
2. 验收标准逐条打三态：对每条 acceptance criterion 输出 VERIFIED（有测试且通过且覆盖边界）/ PARTIAL（有测试但不完整）/ MISSING（无测试），而不是一句笼统的"看起来没问题"；
3. 现场自己跑命令：测试、类型诊断、构建均由验证者本人执行并读取输出；一旦报告中出现 should / probably / seems to 之类的措辞，或引用的是实现前的旧输出，应立即退回补充证据；
4. 收口条件可核对：结束前确认零待办、测试全通过、零错误、证据已收集；最终报告必须覆盖"变更文件、验证命令与真实结果、所做简化、剩余风险"四要素，绝不隐瞒失败测试或伪造输出。

参考资源索引

• 投影产物：角色完整正文见 role-verifier.md，同目录还有 coordinator.md、role-executor.md、role-planner.md、role-reviewer.md
• 规范文本单一来源：sections.ts
• 投影与必选段声明：manifest.ts
• 确定性组合与摘要：compose.ts、types.ts、digest.ts
• 保鲜门禁测试：prompt-ssot.test.ts
• Verifier 上游详细操作契约：agents/verifier.md
• 机制背景与量化收益：docs/design/issue-3704-prompt-ssot/README.md