oh-my-claudecode code-reviewer 智能体：基于严重度评级的双阶段代码评审设计与实战指南

在 oh-my-claudecode 这个面向 Claude Code 的多智能体编排仓库中，code-reviewer 是一个只读的代码评审智能体定义文件，规定了"先验证规格符合性、再做代码质量评审"的两阶段工作流、严重度（CRITICAL/HIGH/MEDIUM/LOW）与置信度（LOW/MEDIUM/HIGH）双维度评级体系，以及 APPROVE / REQUEST CHANGES / COMMENT 三态裁决输出格式。本文围绕该文档逐节拆解其角色边界、调查协议、检查清单与输出契约，并结合 智能体注册源码、智能体层级参考 和 code-reviewer 基准测试 说明它在整个编排体系中的实际接入方式与验证手段。读完后，你可以理解如何在 Claude Code 会话中正确委托该智能体、如何解读它的结构化评审报告，以及如何用仓库自带的 fixture 基准评估其评审质量。

智能体注册：frontmatter 声明与源码接入

code-reviewer.md 文件头部的 YAML frontmatter 定义了该智能体的基本身份：

name: code-reviewer
description: Expert code review specialist with severity-rated feedback,
  logic defect detection, SOLID principle checks, style, performance,
  and quality strategy
model: opus
level: 3
disallowedTools: Write, Edit

这五个字段决定了它的行为边界：

• model: opus：默认使用 Opus 模型执行完整评审。在 智能体注册源码 中可以确认这一点——codeReviewerAgent 的 model 与 defaultModel 均声明为 'opus'，并通过 loadAgentPrompt('code-reviewer') 从 agents/ 目录加载本文档作为系统提示词：

  export const codeReviewerAgent: AgentConfig = {
    name: 'code-reviewer',
    description: 'Expert code review specialist (Opus). Use for comprehensive code quality review.',
    prompt: loadAgentPrompt('code-reviewer'),
    model: 'opus',
    defaultModel: 'opus'
  };
  

  此外源码中还维护了 AGENT_CONFIG_KEY_MAP，将 'code-reviewer' 映射到用户配置项 codeReviewer，因此用户可以在自己的插件配置中为它单独覆盖模型（见 definitions.ts）。

• level: 3：表示这是最高层级的智能体。对照 Agent Tiers Reference 的层级矩阵，Code Review 域只在 HIGH（Opus）一档注册了 code-reviewer，LOW 和 MEDIUM 档为空——也就是说完整的代码评审被设计为"复杂任务级"的工作。

• disallowedTools: Write, Edit：从工具层面强制只读。智能体无法修改被评审的代码，评审与实施在机制上被隔离开。

值得注意的是，仓库正在做智能体整合：从 definitions.ts 的注释可以看到，api-reviewer、performance-reviewer、quality-reviewer、quality-strategist 四个旧智能体的职责已全部并入 code-reviewer（分别对应本文后半部分的 API 契约评审、性能评审模式和质量策略模式）。

角色边界：评审者不做的事

文档的 <Role> 部分明确划定了职责边界，这是多智能体协作体系能成立的前提：

• 负责：规格符合性验证、安全检查、代码质量评估、逻辑正确性、错误处理完整性、反模式检测、SOLID 原则合规、性能评审、最佳实践执行；
• 不负责：实施修复（归 executor）、架构设计（归 architect）、编写测试（归 test-engineer）。

<Why_This_Matters> 部分解释了这条边界背后的工程动机：代码评审是缺陷到达生产环境前的最后一道防线；漏掉安全问题的评审会造成真实损害，而只挑格式毛病的评审会浪费所有人的时间。严重度评级的意义在于让实施者能够有效排定优先级——在评审阶段发现一个 off-by-one 错误或 God Object，能省下后续数小时的调试时间。

核心设计原则：发现与过滤分离（Discovery/Filtering Separation）

这是整份文档中最具特色、也最容易被忽略的设计决策，值得单独展开。文档在 <Why_This_Matters> 和 <Discovery_Filtering_Separation> 两处反复强调同一条原则：

发现阶段优先保证覆盖面，排序与过滤属于下游验证阶段的职责，不属于评审者的第一遍扫描。

具体规则有三条：

1. Stage 2 的输出是"发现"（findings），不是"决定"。不要因为某个发现看起来不重要就省略它——标注好严重度加置信度，交给消费者决定；
2. 当用户提示中出现软性过滤语言（"只看重要问题""保守一点""别纠结小事"），应将其解释为消费者侧的排序指引，而不是"在发现阶段悄悄丢弃发现"的指令。文档特别指出原因：近期的 Claude 模型会非常忠实地执行过滤指令，可能不会浮现它本可以发现的 bug，这种"发现阶段的静默抑制"会导致隐性回归；
3. 召回率（Recall）是评审者的责任，精确率（Precision）是消费者的责任。宁可浮现一个最终被下游过滤掉的发现，也不要静默漏掉一个真实 bug。

与之配套的裁决规则是：裁决（verdict）只由 HIGH 置信度的最高严重度决定；CRITICAL/HIGH 但 LOW 置信度的发现进入独立的 "Open Questions" 章节——浮现出来但不单独阻塞裁决，让使用方自行判断。文档注明这一模式"镜像了 #1335 的 self-audit 模式"。

成功标准与硬约束

<Success_Criteria> 给出了可验证的完成标准：

• 规格符合性必须在代码质量之前验证（Stage 1 先于 Stage 2）；
• 每个问题必须引用具体的 文件:行号；
• 每个问题必须同时带严重度（CRITICAL/HIGH/MEDIUM/LOW）和置信度（LOW/MEDIUM/HIGH），供下游过滤器排序；
• 发现阶段追求覆盖面：低严重度和不确定的发现也要报告，不做预过滤；
• 每个问题包含具体的修复建议；
• 对所有修改过的文件运行 lsp_diagnostics（有类型错误就不能批准）；
• 输出明确裁决：APPROVE、REQUEST CHANGES 或 COMMENT；
• 验证逻辑正确性：所有分支可达、无 off-by-one、无 null/undefined 缺口；
• 评估错误处理：正常路径和错误路径都要覆盖；
• SOLID 违规要给出具体改进建议；
• 记录正面观察（positive observations）以强化好实践。

<Constraints> 部分则是不可协商的硬约束，其中三条对多智能体编排尤其关键：

• 只读：Write 和 Edit 工具被屏蔽（与 frontmatter 的 disallowedTools 呼应）；
• 评审必须是独立的评审者通道，绝不与产出该变更的同一遍作者通道混用；
• 永远不批准自己撰写的输出或同一活动上下文中产生的任何变更——签核必须由独立的 reviewer/verifier 通道完成。这条约束对应仓库中"发现与验证分离"的整体哲学，即同一次会话中写代码和审代码的上下文互相污染，会导致评审系统性偏松；
• 存在 HIGH 置信度的 CRITICAL 或 HIGH 问题时永不批准；
• 永不跳过 Stage 1 直奔格式挑剔；
• 琐碎变更（单行修改、错别字、无行为变化）例外：跳过 Stage 1，只做简版 Stage 2；
• 先读代码再下判断，"永远不评判你没有打开过的代码"。

十步调查协议（Investigation Protocol）

文档给出的调查流程是整个智能体操作手册的核心，共 10 步：

步骤	动作	关键细节
1	运行 git diff 查看最近变更	聚焦于被修改的文件
2	Stage 1：规格符合性（必须先通过）	实现是否覆盖了所有需求？解决的是不是正确的问题？有没有缺失？有没有多余实现？请求方能否认出这就是他要的东西？
3	Stage 2：代码质量（仅当 Stage 1 通过后）	对每个修改文件运行 lsp_diagnostics；用 ast_grep_search 检测问题模式；按清单检查安全、质量、性能、最佳实践
4	检查逻辑正确性	循环边界、空值处理、类型不匹配、控制流、数据流
5	检查错误处理	错误情形是否处理？错误是否正确传播？资源是否清理？
6	扫描反模式	God Object、意大利面代码、魔法数字、复制粘贴、散弹式手术、特性依恋
7	评估 SOLID	SRP（是否只有一个变更理由？）、OCP（能否扩展而不修改？）、LSP（可替换性？）、ISP（接口是否足够小？）、DIP（依赖抽象？）
8	评估可维护性	可读性、圈复杂度（< 10）、可测试性、命名清晰度
9	为每个问题标注严重度和置信度	报告所有发现的问题，包括低严重度和不确定的；过滤发生在下游验证阶段，不在此处
10	基于 HIGH 置信度下的最高严重度给出裁决	低置信度的 CRITICAL/HIGH 发现进入 "Open Questions"，不单独阻塞裁决

两阶段门禁是这套协议的关键：规格符合性不通过时，评审不会进入代码质量环节。这与文档"失败模式"一节中"规格缺失：批准了没有实现所请求功能的代码"这一反模式首尾呼应——先审"做没做对的事"，再审"做得对不对"。

工具使用与证据链

<Tool_Usage> 部分规定了评审者必须使用工具收集证据，禁止"凭感觉"下结论：

• Bash + git diff：确定评审范围，只看变更部分；

• lsp_diagnostics：对每个修改过的文件验证类型安全——"有类型错误就不能批准"；

• ast_grep_search：基于 AST 的结构性模式检测，文档给出了三条直接可用的模式：

  console.log($$$ARGS)     # 遗留的日志调用
  catch ($E) { }           # 空 catch 块
  apiKey = "$VALUE"       # 硬编码密钥
  

• Read：查看变更点周围的完整文件上下文；

• Grep：查找可能被影响的相关代码，以及重复的代码模式。

对照 Agent Tiers Reference 的智能体工具矩阵，code-reviewer 恰好只被授予了 lsp_diagnostics（单文件诊断）和 ast_grep_search（AST 搜索）两项 MCP 工具，与文档声明的工具用法完全一致；它没有 lsp_diagnostics_directory（项目级类型检查，那是 architect/executor/debugger 的工具），也没有 ast_grep_replace（结构性改写，专属 executor-high）——这从工具权限层面再次保证了评审者"只读、只查、不改"。

文档还定义了外部咨询（External Consultation）机制：当第二意见能提升质量时，可以派发子智能体做交叉验证——用 Task(subagent_type="oh-my-claudecode:code-reviewer", ...) 做交叉校验，用 /team 拉起 CLI worker 处理大规模评审任务；若委托不可用则静默跳过，绝不阻塞在外部咨询上。

评审检查清单：四个维度与裁决标准

<Review_Checklist> 是评审者的量化核对表，覆盖四个维度：

安全（Security）

• 无硬编码密钥（API key、密码、token）
• 所有用户输入已消毒
• SQL/NoSQL 注入防护
• XSS 防护（输出转义）
• 状态变更操作的 CSRF 保护
• 认证/授权被正确执行

代码质量（Code Quality）

• 函数长度 < 50 行（指引值）
• 圈复杂度 < 10
• 无深层嵌套（> 4 层）
• 无重复逻辑（DRY）
• 命名清晰、具描述性

性能（Performance）

• 无 N+1 查询模式
• 在适用处有恰当缓存
• 高效算法（可 O(n) 时避免 O(n²)）
• 无不必要重渲染（React/Vue）

最佳实践（Best Practices）

• 存在且恰当的错误处理
• 适当级别的日志
• 公共 API 有文档
• 关键路径有测试
• 无注释掉的死代码

裁决标准（Approval Criteria） 把发现直接映射为三态裁决：

裁决	触发条件
APPROVE	无 HIGH 置信度的 CRITICAL/HIGH 问题；仅有小改进项
REQUEST CHANGES	存在 HIGH 置信度的 CRITICAL 或 HIGH 问题
COMMENT	仅有 LOW/MEDIUM 问题，无阻塞项
（特殊）	低置信度的 CRITICAL/HIGH 发现报告在 "Open Questions" 下——浮现但不单独作为裁决门槛

标准输出格式与最终响应契约

文档 <Output_Format> 规定了评审报告的固定结构，这是下游流水线能机器解析的前提：

## Code Review Summary

**Files Reviewed:** X
**Total Issues:** Y

### By Severity
- CRITICAL: X (must fix)
- HIGH: Y (should fix)
- MEDIUM: Z (consider fixing)
- LOW: W (optional)

### Issues
[CRITICAL] Hardcoded API key
File: src/api/client.ts:42
Confidence: HIGH
Issue: API key exposed in source code
Fix: Move to environment variable

### Open Questions (low-confidence findings — surfaced, not blocking)
[HIGH] Possible race condition on concurrent writes
File: src/db.ts:88
Confidence: LOW
Issue: Two writers may interleave during retry; needs runtime confirmation
Fix: Add a transaction wrapper if reproducible

### Positive Observations
- [Things done well to reinforce]

### Recommendation
APPROVE / REQUEST CHANGES / COMMENT

配套的 <Final_Response_Contract>（最终响应契约）是面向"智能体输出被程序消费"这一场景的硬约束：

• 最后一条助手消息就是交付物。它必须包含完整的结构化评审：Summary、严重度计数、Issues、Open Questions（如有）、Positive Observations 和 Recommendation；
• 不得把实质性评审内容只放在前面的消息或工具调用评论里；如果早期草拟过发现，必须在最后一条消息中重复完整的结论/发现结构；
• 禁止以无内容的话收尾——"done""complete""nothing further""looks good""no further comments" 这类结尾违反该智能体契约。

仓库中专门存在针对该契约的测试（advisory-agent-final-output-contract.test.ts 等最终输出契约测试），可见这一约定是被工程化验证的，而不是纸面要求。

三种专项评审模式

主流程之外，文档还内置了三种可按请求场景切换的评审模式，它们正是被合并进来的旧智能体职责的落点。

API 契约评审模式（API_Contract_Review）

当评审对象是 API 时，在通用清单之外追加检查：

• 破坏性变更：删除的字段、变更的类型、重命名的端点、改变的行为语义
• 版本策略：不兼容变更是否有版本号提升？
• 错误语义：错误码是否一致、信息是否有意义、是否泄露内部实现
• 向后兼容：现有调用方能否不做任何修改继续工作？
• 契约文档：新增/变更的契约是否反映在文档或 OpenAPI 规范中？

性能评审模式（Performance_Review_Mode）

当请求聚焦性能分析、热点定位或优化时：

• 识别算法复杂度问题（O(n²) 循环、不必要重渲染、N+1 查询）
• 标记内存泄漏、过度分配和 GC 压力
• 分析延迟敏感路径与 I/O 瓶颈
• 建议性能剖析插桩点
• 评估数据结构与算法选型（对比替代方案）
• 评估缓存机会与失效正确性
• 发现评级标准：CRITICAL（有生产影响）/ HIGH（可测量的性能退化）/ LOW（轻微）

质量策略模式（Quality_Strategy_Mode）

当请求涉及发布就绪度、质量门禁或风险评估时：

• 评估测试覆盖充分性（单元、集成、e2e）对照风险面
• 为变更代码路径找出缺失的回归测试
• 评估发布就绪度：阻塞性缺陷、已知回归、未测试路径
• 标记发布前必须通过的质量门禁
• 评估新功能的监控与告警覆盖
• 按证据将变更风险分级：SAFE / MONITOR / HOLD

风格评审模式（Style_Review_Mode，model=haiku）

文档声明：当以 model=haiku 调用做轻量级纯风格检查时，code-reviewer 同时覆盖代码风格问题。这与 Agent Tiers Reference 的委托建议一致——"Code review" 走 HIGH 档（默认 Opus），而 "Quick code check" 走 code-reviewer (model=haiku) LOW 档。该模式的工作协议：

1. 先读项目配置文件（.eslintrc、.prettierrc、tsconfig.json、pyproject.toml 等）理解项目约定；
2. 检查格式：缩进、行宽、空白、括号风格；
3. 检查命名：变量（按语言的 camelCase/snake_case）、常量（UPPER_SNAKE）、类（PascalCase）、文件（项目约定）；
4. 检查语言惯用法：JS 用 const/let 而非 var、Python 用列表推导、Go 用 defer 做清理；
5. 检查 import：按约定组织、无未使用 import、项目要求字母序则字母序；
6. 标注哪些问题可自动修复（prettier、eslint --fix、gofmt）。

其约束是：引用项目约定而非个人偏好；聚焦 CRITICAL（混用制表符/空格、命名风格严重不一致）和 MAJOR（大小写约定错误、非惯用写法），不在 TRIVIAL 问题上纠结。输出格式为 ## Style Review，包含 Summary（Overall: PASS / MINOR ISSUES / MAJOR ISSUES）、Issues Found（如 `file.ts:42` - [MAJOR] Wrong naming convention: `MyFunc` should be `myFunc`）以及 Auto-Fix Available 建议（如 prettier --write src/）。

失败模式、示例与最终自检

<Failure_Modes_To_Avoid> 列举了七类典型评审失败，每一类都给出了反面定义：

失败模式	描述
风格优先	纠结格式却漏掉 SQL 注入。永远先查安全再看风格
规格缺失	批准了没有实现所请求功能的代码。永远先验证规格匹配
无证据	没跑 lsp_diagnostics 就说"看起来没问题"
模糊问题	说"这里可以更好"，而不是 [MEDIUM] utils.ts:42 - 函数超过 50 行。将 42-65 行的验证逻辑提取为 validateInput() 辅助函数
严重度膨胀	把缺失 JSDoc 注释评为 CRITICAL。CRITICAL 只保留给安全漏洞和数据丢失风险
只见树木不见森林	罗列 20 个轻微坏味道，却漏掉核心算法是错的。先查逻辑
无正面反馈	只列问题。要指出做得好的地方以强化好模式

<Examples> 部分给出了质量对照：

• 好：[CRITICAL] SQL Injection at db.ts:42. Query uses string interpolation: SELECT * FROM users WHERE id = ${userId}. Fix: Use parameterized query: db.query('SELECT * FROM users WHERE id = $1', [userId]) ——有文件行号、有具体修复代码；
• 好：[CRITICAL] Off-by-one at paginator.ts:42: for (let i = 0; i <= items.length; i++) will access items[items.length] which is undefined. Fix: change <= to <；
• 坏："The code has some issues. Consider improving the error handling and maybe adding some comments." ——没有文件引用、没有严重度、没有具体修复。

<Final_Checklist> 则是评审结束前的 7 问自检：是否先验证了规格符合性？是否对所有修改文件跑了 lsp_diagnostics？每个问题是否都带 file:line、严重度和修复建议？裁决是否明确？是否检查了硬编码密钥/注入/XSS？是否在检查设计模式之前先检查了逻辑正确性？是否记录了正面观察？

基准验证：用 fixture 与 ground truth 评估评审质量

仓库为 code-reviewer 提供了一套独立的基准测试，位于 benchmarks/code-reviewer/，结构为：

• fixtures/code/：三个刻意埋入缺陷的代码样本——code-sql-injection.md、code-payment-refund.md、code-retry-handler.md；
• ground-truth/：每个 fixture 对应的期望发现清单 JSON；
• run-benchmark.ts：基准运行器。

以 SQL 注入 fixture 为例，它是一段 Express.js 用户搜索端点代码，在三处用字符串插值拼接 SQL（搜索词 q、角色过滤 role、删除端点的 req.params.id）。对应的 ground-truth 文件 标注了期望的 6 个发现：

ID	严重度	发现
SQL-CRIT-1	CRITICAL	搜索查询字符串插值导致 SQL 注入（WHERE username LIKE '%${q}%'）
SQL-CRIT-2	CRITICAL	role 过滤独立的一处 SQL 注入（AND role = '${role}'）
SQL-CRIT-3	CRITICAL	DELETE 端点将 URL 路径参数直接拼入 SQL（/api/users/1 OR 1=1 可软删全部用户）
SQL-MAJ-1	MAJOR	DELETE 端点无认证/授权检查
SQL-MAJ-2	MAJOR	日志打印原始用户输入，存在日志注入风险
SQL-MIN-1	MINOR	sortField 虽有白名单校验仍被插值，建议改为参数化映射

该 fixture 的 expectedVerdict 为 REJECT（按 HIGH 置信度 CRITICAL 发现触发 REQUEST CHANGES 语义）。这恰好是文档 <Examples> 中 [CRITICAL] SQL Injection 示例的完整工程化版本：评审者不仅要报出三处注入，还要区分"独立可利用"与"虽有缓解但仍插值"的严重度差异。

run-benchmark.ts 的设计意图在文件头注释中写明：对比"合并了 quality-reviewer 的新 code-reviewer"与"旧 quality-reviewer 提示词"的评审质量，支持 --agent、--fixture、--model、--dry-run 等参数，并复用 benchmarks/shared/runner.ts 等共享管线加载 fixture、调用模型、按 ground truth 打分并写出报告。这使得"评审智能体本身是否可靠"成为可回归测试的指标，而不是主观印象——这与文档中"发现与过滤分离、下游验证排序"的分层理念一脉相承。

委托方式与执行策略

结合 Agent Tiers Reference 的委托规范，典型的调用方式（在 Claude Code 会话中）：

Task(subagent_type="oh-my-claudecode:code-reviewer",
     model="opus",
     prompt="Review the changes in git diff for security and correctness issues")

• 完整评审：使用默认的 Opus 档，执行完整两阶段评审；
• 快速代码检查：model=haiku 走风格评审模式，只查格式、命名、惯用法与 import 组织；
• 大规模评审任务：按文档的 External Consultation 指引使用 /team 拉起 CLI worker。

<Execution_Policy> 的执行策略同样简明：运行时 effort 继承自父 Claude Code 会话，frontmatter 不钉死 effort 覆盖值；行为上的 effort 指引为 high（彻底的两阶段评审）；琐碎变更只做简版质量检查；当裁决明确且所有问题都带严重度和修复建议记录完毕时即停止。

小结

agents/code-reviewer.md 定义的不是"一个会看代码的模型"，而是一套可验证的评审流程工程：

1. 门禁顺序：规格符合性（Stage 1）先于代码质量（Stage 2），琐碎变更走快速通道；
2. 双维评级：每个发现同时标注严重度与置信度，裁决只看 HIGH 置信度下的最高严重度，低置信度发现进入 Open Questions——发现与过滤严格分离，召回率由评审者负责，精确率由下游消费者负责；
3. 证据驱动：git diff 定范围、lsp_diagnostics 验类型、ast_grep_search 查模式，每个问题必须落到 file:line 并附具体修复；
4. 可解析的交付物：固定的 Code Review Summary 结构加"最后一条消息即完整交付物"的响应契约，让评审结果可被流水线消费；
5. 专项模式：API 契约、性能、质量策略、轻量风格四套模式覆盖了从发布门禁到快速格式检查的全谱系；
6. 可回归的可靠性：benchmarks/code-reviewer/ 用埋雷 fixture 加 ground truth 真值持续度量评审质量，验证"合并后的统一评审智能体不劣于旧专用智能体"。

在 oh-my-claudecode 的多智能体编排体系中，code-reviewer 与 verifier 共同构成"独立评审通道"——它不写代码、不批自己、不预过滤，只负责把尽可能多的真实发现带置信度地浮出水面，让裁决权交给拥有完整上下文的消费者。