code-review

代码审查 — 多 Agent 本地审查

概述

并行运行专注于特定领域的审查 Agent，然后由验证器仅保留具有实际影响的问题，提炼出“优先修复”清单，并抑制琐碎问题——最终汇总到仓库根目录的 REVIEW.md。**核心原则：**审查只有发现错误答案时才值得阅读，而不是挑剔风格。各审查领域聚焦正确性和结构健全性；验证器默认将影响较小的问题标记为 DROP，以免掩盖重要信号。此技能负责确定范围、分发任务和整理结果——审查 Agent 与验证器负责判断。

轻量路径。 仅涉及文档的差异（正文和注释，不涉及代码、配置或依赖变更）不会分发任何审查领域；REVIEW.md 会写明 **Lanes:** none — doc-only 和 **Verifier:** not run。对于小到无需架构和测试审查的改动——例如单行修复、配置值或依赖版本升级——会分发正确性审查领域和验证器，并标记为 **Lanes:** correctness (light path)，因为警报背后的单行正则表达式或用于修复 CVE 的版本升级仍需追踪输入。任何增加分支、函数或文件的改动都会分发所有审查领域。除非用户指定模型，否则每次调用审查领域和验证器时都传入 model: "sonnet"。

模式与标志

标志	效果
(无) / path / --staged / --branch <base>	限定差异范围的审查（默认快速路径）
--repo	全仓库审查——检查每个源文件，而不只是差异（符合性审查）
--blueprint <skill>	根据指定的蓝图技能（例如 local-first-app）审查架构和 ui-ux，而非最相近的同类项目。除非同时指定差异范围，否则隐含 --repo
--background	在 git worktree 中以分离模式运行；审查期间可继续工作（见后台模式）
--nits	同时显示被抑制的卫生/琐碎问题类别。默认关闭

流程

detect scope → dispatch reviewers (parallel Agent) → verifier (1 Agent) → synthesize → REVIEW.md

各审查领域（完整提示词见 reference/AGENTS.md——分发任务时加载）：

审查领域	负责范围	是否阻塞？
correctness	错误答案：边界/差一错误（日期、DST、月末）、时区/区域设置分组、金额/费率计算、错误被吞掉、非原子写入、循环未终止、异步结果被丢弃、空值/退化输入	是——最高优先级
architecture	针对代码用途的结构健全性：持久化/幂等语义错误、缺少操作所需的韧性、约束遭破坏、关键上下文丢失、掩盖行为的严重复杂度（嵌套层级达 4 层或更多、圈复杂度约大于 10）。不审查“与同类实现不同”	是
testing	对改动的覆盖情况 + 断言强度（成员检查而非精确匹配、宽松的真值断言、被模拟的预言）	是
ui-ux	对照排版与色彩系统底线检查可读性/a11y（正文小于 16px、对比度 <4.5:1、仅以颜色传达信号、缺少焦点/标签）。仅当范围涉及 UI 时才分发	是（有条件）
hygiene	一轮非阻塞检查：机密信息、死代码、拼写错误、文档/依赖偏差、可读性和中等复杂度方面的琐碎问题	否——除非使用 --nits，否则会抑制；真正的 [Secret] 始终会显示

阶段 1：范围检测

先解析标志。按优先级确定要审查的文件：--repo（仓库下的所有源文件，排除下文所列内容）→ 显式路径参数 → --staged（git diff --cached）→ --branch <base>（git diff <base>...HEAD）→ 默认（已暂存 + 未暂存，git status --porcelain + git diff HEAD）→ 回退（功能分支且没有未提交更改：git diff main...HEAD）。

过滤掉二进制/图片资源、生成文件、构建/依赖/venv 输出。不要过滤锁文件、包清单、环境模板或项目文档——hygiene 需要它们。**检测 UI 范围：**如果文件列表包含组件/模板/样式/设计令牌文件，则加入 ui-ux 通道；否则跳过。

**固定仓库根目录。**将待审查树的 git rev-parse --show-toplevel 解析为绝对路径，并将其放在 共享前置说明 中，置于每个通道和验证器提示词的开头——原因见 Gotchas。

只有在掌握了具体文件列表和差异文本后，才能进行分派（对于 --repo，“差异”是范围内文件当前的完整内容），因为审查子 Agent 启动时没有对话上下文，也无法读取你未提供的内容。先向用户报告范围（“正在审查 N 个文件：…”）。如果差异模式下范围为空，就停止，不要凭空编造工作。（--repo 永远不会为空；这正是它的用途。）

阶段 2：并行分派

在同一条消息中发送审查 Agent 调用，使其并发运行；所有调用的 subagent_type: general-purpose，并通过共享前置说明设为只读。Explore 读取摘录以定位代码，而各通道必须阅读完整函数及其调用方。始终分派 correctness、architecture、testing、hygiene；仅在检测到 UI 范围时加入 ui-ux。每个提示词都包含文件列表 + 差异、通道及忽略事项、输出格式，并要求提供 file:line 级别的具体位置。使用 reference/AGENTS.md 中的确切模板。设置 --blueprint <skill> 时，加载该 skill，并将其名称/规则传入 architecture 和 ui-ux 提示词。

阶段 2.5：验证 + 影响门槛

派遣一名验证者（单个 Agent，general-purpose，共享前置说明），并提供文件列表、差异和合并后的候选项。完整提示词：reference/AGENTS.md#verifier。如果每个通道都返回了 NO FINDINGS，则跳过验证者：标头写明 **Verifier:** skipped — no candidates，并省略 STRENGTHS 块。验证者是信号过滤器，不只是误报过滤器：

• **证据：**重新阅读每条发现所引用的 file:line；如果引用有误，则丢弃。
• 差异锚点（仅差异模式；--repo 没有差异）：如果发现位于差异新增或修改的行上，则保留。若发现位于未改动的行上，只有在某个改动行导致该问题时才保留，并标记为 Outside the diff — caused by path:line；否则丢弃，并计为偏离差异。
• **影响门槛：**每条保留的发现都必须指出它能避免的具体不良后果（错误结果、数据丢失、安全问题、实际回归、真正会误导读者的陷阱）。如果最坏的现实后果只是外观、风格、仅影响文档，或“前后不一致但不会出问题”，则未达到门槛 → 若标记了 [Nit]，则转入小问题类别；否则丢弃。对影响程度有疑问时，丢弃。
• 严重程度以影响范围为准（取代通道给出的严重程度）。
• **另行注明：**最多保留 3 条已丢弃的发现，每条各占一行；这些发现虽有实际但非阻断性的后果（例如部署顺序步骤、值得编写的后续测试）。仅影响较低的发现仍应丢弃。
• **STRENGTHS：**验证者列出 2–4 项经阅读代码确认做得好的地方，每项都关联到检查过的文件或行号——有依据的赞扬能让反馈从挑剔转为评审；没有依据的赞扬则像是在凑数。

验证者返回：STRENGTHS、“what to fix first”提炼结果（3–6 项）、按重新评定的严重程度保留的阻断性发现、ALSO NOTED、NITS 部分（仅当使用了 --nits 时），以及 Verifier summary: kept N blocking of M; dropped J (W wrong-evidence, O off-diff, L low-impact); A also noted; H nits held.

阶段 3：综合

验证者已经判定了证据、影响和优先级——综合阶段只负责排版：

1. 如有 STRENGTHS 块，先呈现 ## What the repo does well。
2. 接着呈现 ## What to fix first，按顺序列出验证者给出的单行 path:line — why it matters。如果返回了 Nothing blocking — only polish remains.，则仅呈现该行。
3. 按重新评定后的严重程度（Critical → Major → Minor）分组保留的发现，再按文件分组。严重程度原样采用验证者的判断；保留任何 Verifier note: 和 Outside the diff 标签。[Secret] 发现始终要列出（Critical）。
4. **另行注明：**如有验证者保留的条目，在 Minor 之后以 ## Also noted 呈现。
5. **小问题：**仅当传入了 --nits 时，才呈现按文件分组的 ## Nit 部分，并使用简短的单行描述。否则完全省略——摘要行仍会报告保留了多少条。
6. 去重：如果多个通道标记了同一行，则只保留最严重的发现，并注明相关通道。
7. 使用 Write 将内容写入仓库根目录（git rev-parse --show-toplevel）下的 REVIEW.md，覆盖原文件。直接运行时，打印一行聊天消息：REVIEW.md written — X Critical, Y Major, Z Minor; H nits held (--nits to show)。

即使没有问题，也始终写入 REVIEW.md（计数均为零的标头 + STRENGTHS 块 + Nothing blocking — only polish remains.）。综合器的职责范围仅限结构排版——不得提出新发现、重新评判或在直接运行时把报告整份发到聊天中。

**调用方的格式要求优先。**当另一个 Agent 或包装技能运行评审时，按其要求返回内容——该交付内容就是报告——同时仍须写入 REVIEW.md。如果调用方指定了自己的严重程度标签（例如 Blocking / Should fix / Nit），则将 Critical、Major 和 Minor 映射为这些标签，并在 REVIEW.md（包括验证者摘要行）中始终使用这些标签，不要混用两套术语。调用方更严格的规则（例如丢弃所有偏离差异的发现）将取代此技能的规则。

后台模式

--background 会在后台分离运行审查，让用户继续工作。请从负责此审查的线程中协调整个流程——通常是主线程；委派的 Agent 也可以，因为子 Agent 最多能再生成三层子 Agent。

1. 协调器确定范围并捕获差异文本（阶段 1），然后打印 Reviewing N files in the background — keep working; REVIEW.md will appear when done.
2. 为每位审查者分派任务，使用 run_in_background: true、isolation: "worktree"，且不指定 name——Gotchas 会解释这两项要求。
3. 协调器交还控制权；每位审查者完成后，运行环境会重新调用协调器。
4. 所有审查者都完成后，分派验证者（后台运行）。
5. 完成后，将 REVIEW.md 写入真实仓库根目录（即审查范围所对应工作树的 git rev-parse --show-toplevel；审查者的工作树会被拆除），以此作为“完成”信号。

--repo --background 是最理想的组合：耗时数分钟的全仓库一致性检查不会阻塞你。

输出格式

仓库根目录中的 REVIEW.md，各部分顺序为：标题（Generated / Scope / Lanes / Verifier: kept N blocking of M; dropped …; H nits held / Total）→ ## What the repo does well → ## What to fix first → ## Critical → ## Major → ## Minor（问题块格式为：[lane] line — 问题、风险/证据及修复方案；重新评定的问题需附带 Verifier note:）→ ## Also noted（如有）→ ## Nit（仅在使用 --nits 时）。完整示例报告：reference/EXAMPLE-REVIEW.md。

示例

✅ **正确：**在一条消息中调用审查者 Agent → 等待 → 调用验证者 Agent → 写入 REVIEW.md → 聊天中只显示 REVIEW.md written — 1 Critical, 2 Major, 0 Minor; 5 nits held (--nits to show)。好的正确性问题描述应具体：[correctness] src/allowance.ts:42 — detail page shows $10/wk but accrual pays $5/wk forever (rate-row shadowing); trigger: any item with a weekly rate; fix: read the rate from the accrual row, not the display row。

❌ **错误：**依次分派审查者；直接运行时，把完整报告输出到聊天中，而不是写入 REVIEW.md；保留的问题类似“考虑重命名此变量”（没有具体的不良后果——本应因未达到影响阈值而被排除）；默认显示细微问题列表，淹没了两条重要问题。

✅ **范围检测，只有后端差异：**列表中没有组件、样式或令牌文件 → 跳过 ui-ux 通道，分派四个通道。差异范围为空 → 停止并说明情况，而不是扩大到 --repo。

❌ **错误：**对只有 CLI 的差异分派 ui-ux 通道，随后又因为其问题在技术上属实而予以保留。

✅ **轻量路径，单行正则修复：**仅运行 correctness 通道和验证者，标题中标明 Lanes: correctness (light path)。

❌ **错误：**同一修复完全没有调用任何 Agent，而 REVIEW.md 仍写着 Verifier: kept 0 blocking of 0——标题声称已通过验证，实际却根本没有运行验证。

✅ 验证者正确丢弃问题：[architecture] src/db.ts:88 — differs from the pattern in src/cache.ts。没有说明后果 → 未达到影响阈值 → 丢弃，并计入 dropped J (L low-impact)。

质量信号

• 在一轮中调用所有审查者 Agent，然后在综合结果前调用一个验证者 Agent。
• 报告开头是 ## What the repo does well + ## What to fix first；除非使用 --nits，否则隐藏细微问题列表。
• 每条保留的问题都指出具体的不良后果；正确性问题要指出触发条件。
• 架构问题应从代码的用途出发论证（说明实际后果），而不是说“同类文件有所不同”。
• 严重性应体现验证者对影响的判断；低影响的事实应被丢弃，而非降级后保留。
• 每条引用的行都必须位于差异中，或标注导致问题的已更改行。
• REVIEW.md 才是交付物（直接运行时，聊天中只输出一行），并应在原位置覆盖写入。

注意事项

• 分派工作流时绝不要传入 name。 为 Agent 命名会使其成为队友，而队友无法创建其他队友——在委派审查中，整个批次都会因 Teammates cannot spawn other teammates 而被拒绝。它会重试并恢复，但每个工作流都会多花一次往返。工作流不会通过名称寻址，因此省略此参数。
• 工作流从会话所在目录启动，而不是从待审查的代码树启动。 如果该目录下有同一仓库的其他检出版本（例如主克隆旁边有十几个 PR 工作树），相对路径或符号搜索就会解析到另一个分支，导致审查引用当前分支中不存在的行，或指出来自其他功能的 Bug。共享前置提示词中的绝对仓库根目录是解决办法；验证器的差异锚点会捕获遗漏之处。
• 拼接输出中的行号不正确。 cat a.py; cat b.py 会对合并后的流编号，因此工作流可能把第二个文件第 72 行标成第 192 行。前置提示词要求对单个文件使用 grep -n、nl 或 Read。
• 工作树审查者看到的是干净的代码树。 isolation: "worktree" 检出版本与 HEAD 共用同一提交，因此在其中运行 git diff 不会返回任何内容。审查者应从提示词中读取差异；绝不要让工作流重新推导差异。
• --repo 模式没有差异。 工作流收到的是完整文件内容，因此如果工作流只搜索 + 行，遇到真实问题时会返回 NO FINDINGS。将模式传入提示词，让工作流审查整个文件。
• 被丢弃的问题是预期结果，不是 Bug。 验证器会有意删除真实但琐碎的问题；--nits 是恢复这些问题的途径。未达到影响门槛的问题会被丢弃或保留为小问题，绝不会以较低严重性保留。
• ui-ux 工作流是有条件触发的。 如果它在后端或 CLI 差异上触发，说明 Phase-1 UI 检测将非 UI 文件误判为 UI 文件——应修复检测逻辑，而不是接受该工作流产生的噪声。
• 复杂度采用双层设计。 严重复杂度（嵌套层级达 4 级以上、圈复杂度约大于 10）会掩盖行为，因此架构工作流会阻止此类问题，并且必须指出陷阱——未来编辑者会漏掉哪条路径，以及会造成什么后果。中等复杂度属于代码整洁度工作流的 [Nit]。复杂度问题若未指出具体陷阱，且未达到影响门槛，则说明门槛正常发挥了作用，并非问题被遗漏。
• 架构问题容易退化成“与同类实现不同”。 未说明后果的问题不算问题；请使用其原始提示词重新分派该工作流。
• 每次运行都会覆盖 REVIEW.md，并将其写入真正的仓库根目录（git rev-parse --show-toplevel，而非工作树）。之前的审查记录会丢失——请将其加入 .gitignore。.gitignore 无法阻止会复制项目根目录的构建：有一次独立的 Next.js 构建将根目录下的 REVIEW.md 打包进了输出，因此还要将其加入 .dockerignore 以及任何构建复制排除项。

故障排除

• 还是太爱挑小毛病——验证器没有执行影响门槛。请逐字使用 reference/AGENTS.md#verifier 提示词重新分派验证器，并附上“默认丢弃；每个保留的问题都必须指出具体的不良后果。”

范围为空、差异过大、未找到蓝图、工作树清理问题：reference/TROUBLESHOOTING.md。

集成

可搭配 /security-review（安全审查）、/review（按编号获取开放的 PR）、track-session（跟踪修复）、typography + color-system（ui-ux 工作流的标准），以及通过 --blueprint 使用的 local-first-app 等蓝图技能。典型工作流：编辑 → /code-review → 阅读 REVIEW.md，先修复排在最前面的问题 → 重新运行（会覆盖）→ 确认无问题后提交。进行大规模审查时，可使用 /code-review --repo --blueprint <skill> --background，然后继续工作。审查传入的 PR： 将每个 PR 检出到各自的工作树中，并在其中运行 --branch <base>；每个 PR 委派一个 Agent——REVIEW.md 会写入相应工作树的根目录，因此多个 PR 可以并行审查而不会互相冲突。将 REVIEW.md 加入 .gitignore。它不能替代 CI 代码检查或人工 PR 审查——这是一个提交前的检查步骤，用于捕获代码检查工具会漏掉的错误答案。