Superpowers 代码评审子代理提示词模板：如何用 code-reviewer.md 派发出可靠的代码审查

本文解析 Superpowers 技能框架中 skills/requesting-code-review/code-reviewer.md 提示词模板的完整结构与逐项设计意图，说明如何填充四个占位符、派发 general-purpose 审查子代理，并解读其"只读审查 + 分级问题清单 + 明确合并裁决"的输出契约，帮助你在 Agent 协作开发流程中建立可复用的代码评审闸门。该模板是 requesting-code-review 技能的核心组件，也是 subagent-driven-development 流程中"最终整分支评审"节点的唯一模板来源。

一、模板定位：审查子代理的完整任务书

code-reviewer.md 是一份"派发代码审查子代理时使用的提示词模板"（Use this template when dispatching a code reviewer subagent）。其声明目的是：在已完成的工作进一步"级联放大"之前，对照需求和代码质量标准审查它（Review completed work against requirements and code quality standards before it cascades into more work）。

值得注意的是，这不是一个普通的"帮我看看代码"提示，而是一份自包含的 Task 派发模板：

• 文件开头直接给出派发块，形如 Subagent (general-purpose)，说明该技能不再依赖任何具名 agent，而是向通用子代理注入完整人设与检查清单；
• 模板内部完整定义了审查者角色（"Senior Code Reviewer with expertise in software architecture, design patterns, and best practices"）、审查范围（git diff 区间）、只读约束、检查维度、校准原则、输出格式和硬性规则；
• 模板之后附有占位符说明表和一份完整的示例输出（Example Output），让模型在填充后即可派发。

从 RELEASE-NOTES.md 的 v5.1.0 变更记录（PR #1299）可以看到这一设计的演进背景：此前仓库同时存在 agents/code-reviewer.md 具名 agent 和占位模板两份人设/检查清单，且"drifted independently"（各自独立漂移）。v5.1.0 移除了 superpowers:code-reviewer 具名 agent，将其人设与检查清单合并进本模板，形成单一事实来源（single source of truth），并要求所有派发 Task (superpowers:code-reviewer) 的使用方切换为 Task (general-purpose) 加提示模板。这也解释了为什么模板首行明确写的是 Subagent (general-purpose)。

二、模板全文与逐段解析

以下按模板原始结构逐段展开，每一段都对应一个具体的工程决策。

2.1 派发块与角色定义

模板的开头是标准子代理派发语法：

Subagent (general-purpose):
  description: "Review code changes"
  prompt: |
    You are a Senior Code Reviewer with expertise in software architecture,
    design patterns, and best practices. Your job is to review completed work
    against its plan or requirements and identify issues before they cascade.

角色定义同时包含两件事：人设（资深代码审查者）与目标（对照计划或需求审查已完成的工作，在问题级联之前发现它们）。"before they cascade" 与 SKILL.md 中"Dispatch a code reviewer subagent to catch issues before they cascade"的核心原则一一对应——评审的价值在于越早发现，返工成本越低。

2.2 审查上下文：三个必填段落

派发 prompt 要求填入三段上下文，对应三个占位符：

What Was Implemented（[DESCRIPTION]）——实现了什么的简要总结，即"你构建了什么"。

Requirements / Plan（[PLAN_OR_REQUIREMENTS]）——这段代码"应该做什么"，可以是计划文件路径、任务文本或需求描述。没有这一段，审查者只能做纯代码质量评审，无法判断实现是否与计划对齐。

Git Range to Review——用两个 SHA 界定审查范围，并给出可直接执行的命令：

git diff --stat [BASE_SHA]..[HEAD_SHA]
git diff [BASE_SHA]..[HEAD_SHA]

先 --stat 后全量 diff 的顺序是有意的：stat 摘要让审查者先建立变更规模的心智地图，再深入逐行 diff。

2.3 只读审查约束（Read-Only Review）

模板中一段完整的只读约束值得逐句理解：

Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like git show, git diff, and git log to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. git worktree add /tmp/review-[SHA] [SHA]) — never move HEAD on this checkout.

这段约束针对的是 Agent 审查场景的典型风险：子代理拥有 shell 权限，可能顺手"修复"工作区、git checkout 移动 HEAD、或改动 index。模板将其显式禁止，并给出唯一的合法逃生通道——如需另一个修订版本的工作副本，用 git worktree add /tmp/review-[SHA] [SHA] 检出到独立临时目录。这条约束与同仓库 task-reviewer-prompt.md 中"Your review is read-only on this checkout"的表述一脉相承，是 Superpowers 各审查模板共享的底线规则。

2.4 五个审查维度（What to Check）

模板把审查面组织成五个维度，每个维度下是若干具体判问：

Plan alignment（计划对齐）

• Does the implementation match the plan / requirements?（实现是否匹配计划/需求？）
• Are deviations justified improvements, or problematic departures?（偏离是合理的改进，还是有问题的跑偏？）
• Is all planned functionality present?（计划中的功能是否全部就位？）

注意第二问的措辞：偏离计划不自动等于缺陷，审查者需要判断偏离的性质——这正是"对齐审查"与"逐行挑刺"的区别。

Code quality（代码质量）

• Clean separation of concerns?（关注点是否分离干净？）
• Proper error handling?（错误处理是否恰当？）
• Type safety where applicable?（适用场景下类型安全吗？）
• DRY without premature abstraction?（去重了但没有过早抽象？）
• Edge cases handled?（边界情况处理了吗？）

"DRY without premature abstraction" 是 DRY 原则与 YAGNI 的平衡表述：既不放过复制粘贴，也不奖励无谓的抽象层。

Architecture（架构）

• Sound design decisions?（设计决策是否合理？）
• Reasonable scalability and performance?（可扩展性与性能是否合理？）
• Security concerns?（有安全顾虑吗？）
• Integrates cleanly with surrounding code?（与周边代码是否集成干净？）

Testing（测试）

• Tests verify real behavior, not mocks?（测试验证真实行为而非 mock？）
• Edge cases covered?（边界情况覆盖了吗？）
• Integration tests where they matter?（该有集成测试的地方有吗？）
• All tests passing?（测试全部通过吗？）

Production readiness（生产就绪度）

• Migration strategy if schema changed?（schema 变更有迁移策略吗？）
• Backward compatibility considered?（考虑了向后兼容吗？）
• Documentation complete?（文档完整吗？）
• No obvious bugs?（没有明显 bug 吗？）

从 RELEASE-NOTES.md 的历史记录看，这套清单不是纸面文章：仓库曾添加过一个行为测试，在微型项目中埋入真实缺陷（SQL 注入、明文密码处理、凭据日志），断言派发的审查者会把每个埋设问题都标记为 Critical/Important 严重度并拒绝批准该 diff。这说明五个维度的设计目标就是让"安全问题、数据丢失风险"必然落入 Critical 档。

2.5 校准规则（Calibration）

Calibration 一节解决审查者最典型的三类行为失准：

1. 严重度通胀："Categorize issues by actual severity. Not everything is Critical."——按实际严重度分级，不是所有问题都是 Critical；
2. 反馈可信度："Acknowledge what was done well before listing issues — accurate praise helps the implementer trust the rest of the feedback."——先讲清楚做得好的地方，准确的表扬能让实现者信任后续反馈；
3. 计划本身的缺陷要分开指认：发现实现相对计划有重大偏离时，要明确标记出来让实现者确认偏离是否有意为之；发现的是计划本身的问题而非实现问题时，要明说。

第 3 点在 Agent 工作流中尤其重要：控制器持有计划文本，审查者指认"这是计划缺陷"后，冲突才会上交人类裁决，而不是被静默消化。

2.6 输出格式（Output Format）

模板强制五段式报告结构：

### Strengths
[What's well done? Be specific.]

### Issues

#### Critical (Must Fix)
[Bugs, security issues, data loss risks, broken functionality]

#### Important (Should Fix)
[Architecture problems, missing features, poor error handling, test gaps]

#### Minor (Nice to Have)
[Code style, optimization opportunities, documentation polish]

For each issue:
- File:line reference
- What's wrong
- Why it matters
- How to fix (if not obvious)

### Recommendations
[Improvements for code quality, architecture, or process]

### Assessment

**Ready to merge?** [Yes | No | With fixes]

**Reasoning:** [1-2 sentence technical assessment]

设计要点有四：

• 三级严重度有明确的定义边界：Critical 只收"bug、安全问题、数据丢失风险、功能损坏"；Important 收"架构问题、缺失功能、错误处理差、测试缺口"；Minor 收"代码风格、优化机会、文档打磨"。这让控制器可以机械地映射后续动作——SKILL.md 中"Fix Critical issues immediately / Fix Important issues before proceeding / Note Minor issues for later"正是按这三档处理的；
• 每条问题必须四要素齐全：file:line 引用、错在哪、为什么重要、如何修（不明显时）。"File:line reference" 让下游实现者无需重新搜索即可定位；
• 裁决是三值枚举 Yes | No | With fixes，不允许模糊表述；
• Reasoning 限定 1-2 句，逼迫审查者给出凝练的技术判断而非冗长叙述。

2.7 硬性规则（Critical Rules）

模板收尾的 DO/DON'T 清单把"审查者行为"从建议升格为禁令：

DO：

• Categorize by actual severity（按实际严重度分级）
• Be specific (file:line, not vague)（具体到 file:line，不许含糊）
• Explain WHY each issue matters（解释每个问题为什么重要）
• Acknowledge strengths（承认优点）
• Give a clear verdict（给出明确裁决）

DON'T：

• Say "looks good" without checking（没检查不许说"看起来不错"）
• Mark nitpicks as Critical（不许把吹毛求疵标为 Critical）
• Give feedback on code you didn't actually read（不许对没读过的代码给反馈）
• Be vague ("improve error handling")（不许含糊其辞，如"改进错误处理"）
• Avoid giving a clear verdict（不许回避明确裁决）

这条 DON'T 清单实际上是在对抗 LLM 审查者的四种典型失败模式：幻觉性通过（没读就说 good）、严重度通胀、含糊反馈、回避裁决。

三、占位符契约与返回契约

模板在派发块之外给出两张"契约表"。

Placeholders（填充契约）：

占位符	含义
[DESCRIPTION]	brief summary of what was built（构建了什么，简要总结）
[PLAN_OR_REQUIREMENTS]	what it should do (plan file path, task text, or requirements)（应该做什么：计划文件路径、任务文本或需求）
[BASE_SHA]	starting commit（起始提交）
[HEAD_SHA]	ending commit（结束提交）

Reviewer returns（返回契约）：Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment——审查者必须且只需返回这四类内容。这对控制器（调度审查的那个 Agent）至关重要：控制器的 prompt 中拿到的是结构固定的报告，可以直接解析出 Assessment 的裁决值来决定"立即修 / 继续前修 / 记录待办"。

示例输出（Example Output）

模板附带的示例展示了一份符合契约的真实形态报告，要点摘录如下：

• Strengths 给出具体证据："Clean database schema with proper migrations (db.ts:15-42)"、"Comprehensive test coverage (18 tests, all edge cases)"、"Good error handling with fallbacks (summarizer.ts:85-92)"——每条优点都带 file:line；
• Important 档示例："Missing help text in CLI wrapper"（File: index-conversations:1-31，Issue: No --help flag, users won't discover --concurrency，Fix: Add --help case with usage examples）；"Date validation missing"（File: search.ts:25-27，Issue: Invalid dates silently return no results，Fix: Validate ISO format, throw error with example）；
• Minor 档示例：长操作缺少 "X of Y" 进度计数（indexer.ts:130），Impact: 用户不知道要等多久；
• Assessment：Ready to merge: With fixes，Reasoning 为"Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality."——1-2 句、直接可执行。

这个示例同时也是对"severity 分级"的教学：CLI 帮助文本缺失归 Important（用户无法发现功能），进度指示器归 Minor（体验问题），没有一条被虚标为 Critical。

四、与 requesting-code-review 技能的完整工作流

code-reviewer.md 不是孤立文件，它的调用方是 SKILL.md。技能的完整流程是"取 SHA → 派发 → 处置反馈"三步，模板是第二步的核心载荷。

第一步：取 git SHA

BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
HEAD_SHA=$(git rev-parse HEAD)

基线取法按场景不同：单任务用 HEAD~1，整分支评审则应对应分支起点（如 origin/main 或 git merge-base main HEAD）。

第二步：派发 general-purpose 子代理，用上面的四个占位符填充模板。SKILL.md 的示例演示了一次真实派发：

DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
BASE_SHA: a7981ec
HEAD_SHA: 3df7661

并展示了子代理返回后被压缩的结论形态（Strengths / Issues / Assessment），控制器据此修复后继续下一个任务。

第三步：按严重度处置反馈——Critical 立即修，Important 在继续推进前修，Minor 记录后延后；若审查者错了，用技术推理反驳（Push back if reviewer is wrong, with reasoning）。

触发时机分为两档。强制（Mandatory）：subagent-driven development 中每个任务之后、完成重要功能之后、合并到 main 之前。可选但有价值（Optional but valuable）：卡住时（新视角）、重构前（基线检查）、修完复杂 bug 之后。

SKILL.md 还专门用"Common Rationalizations"表拆解了两条最常见的偷懒借口：

借口	现实
"我自己看看 diff 就行了，不派审查者"	你是协调者——内联审查 diff 会烧掉你继续推进工作所需的上下文窗口。派发审查子代理：diff 和评估留在它的上下文里，回到你这里的只有结论。
"审查者需要我的整个会话历史才能理解这次变更"	给它精心构造的上下文，而不是你的会话历史。这让审查者聚焦在工作产物上，而不是你的思考过程。

第二条正是本模板存在意义的另一半：审查者拿到的是 [DESCRIPTION] + [PLAN_OR_REQUIREMENTS] + diff 区间这三样精确构造的输入，而非会话记录。

Red Flags（绝对红线）：不许因为"太简单"跳过审查；不许忽略 Critical 问题；不许带着未修的 Important 问题继续；不许与站得住的技术反馈争论。若审查者错了，用技术推理反驳、出示能证明其有效的代码/测试、或请求澄清。

五、在 subagent-driven-development 中的最终评审角色

从 skills/subagent-driven-development/SKILL.md 的流程图可以看到，本模板在 SDD 流程中承担"最终整分支评审"（final whole-branch review）节点：每个任务有自己的 task reviewer（使用 task-reviewer-prompt.md，输出 Spec Compliance 与 Task quality 双裁决），而所有任务完成后，SDD 派发 "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)"——即本模板，作为宽范围的整分支评审。

两个模板的分工边界在 docs/superpowers/specs/2026-06-09-sdd-task-scoped-review-dispatch-design.md 中有明确论述：本模板问的是架构、可扩展性、安全、生产就绪度，并以"Ready to merge?"收尾，是一个合并就绪度评审（merge-readiness review）；而单任务评审需要的是任务作用域的闸门（task-scoped gate）。设计文档指出，若让单任务评审委托给本模板，"That frame licenses branch-level breadth on a one-task diff"（合并就绪的框架会授权对单个任务 diff 做分支级的宽泛审查），因此 SDD 后来为单任务评审改用了独立的 task-reviewer-prompt.md，而本模板的职责被收敛为明确的整分支终审。SDD 对该终审还规定了两点使用细节：

• 用 scripts/review-package PLAN_FILE MERGE_BASE HEAD 生成整分支 diff 包，MERGE_BASE 用 git merge-base main HEAD 求得，把打印出的文件路径放进派发 prompt，让最终审查者读一个文件而不是自行用 git 命令重新推导分支 diff；
• 派发时显式指定最强可用模型（而非会话默认模型），并指向 ledger 中记录的 deferred-minor 与 parked 条目，让它分诊哪些必须在合并前修复。

此外，using-superpowers 的 Gemini 工具映射参考 给出了跨 harness 的派发对照：凡引用 superpowers:requesting-code-review 的 ./code-reviewer.md 的场景，在 Gemini CLI 上应映射为 invoke_agent（agent_name: "generalist"）加填充后的评审模板——进一步印证模板已完全脱离对具名 agent 的依赖。

六、可复用的填充范式

把模板用起来的最小步骤：

1. 确定审查区间：BASE_SHA（任务/分支起点）与 HEAD_SHA（当前 HEAD）；
2. 复制 skills/requesting-code-review/code-reviewer.md 中 ``` 块内的完整 prompt；
3. 替换四个占位符：[DESCRIPTION]（一段话讲清构建了什么）、[PLAN_OR_REQUIREMENTS]（计划文件路径或任务原文）、[BASE_SHA]、[HEAD_SHA]；
4. 以 general-purpose 子代理派发，等待其返回 Strengths / Issues / Recommendations / Assessment；
5. 解析 **Ready to merge?** 的三值裁决，按 Critical → Important → Minor 的顺序处置 Issues 中带 file:line 的条目。

一个容易踩的坑在 SDD 文档中被特别点出：BASE 要用记录在案的起点，"never HEAD~1, which silently drops all but the last commit of a multi-commit task"（绝不用 HEAD~1，它会在多提交任务中悄悄丢掉除最后一次提交外的全部提交）。对单提交任务 HEAD~1 恰好用，但多提交任务必须显式取任务开始前的 SHA。

七、模板设计的核心原则总结

回看整份模板，Superpowers 的代码审查方法论可归纳为四条可迁移原则：

1. 精确上下文优于会话历史：审查者只拿到 DESCRIPTION、PLAN_OR_REQUIREMENTS 和 diff 区间三样东西，审查质量取决于控制器构造上下文的能力；
2. 只读是硬约束：审查者可以 git show/git diff/git log，可以 git worktree add 到临时目录，但绝不移动被审查 checkout 的 HEAD——这保护了控制器正在推进的工作区；
3. 分级裁决可机械消费：Critical/Important/Minor 三档加三值合并裁决，让上游流程（无论人类还是控制器 Agent）能确定性地把反馈映射为动作，而不是二次解读自然语言；
4. 反幻觉条款显式化：DON'T 清单逐条封死了"没读就说 good""对没读的代码给意见""模糊反馈""回避裁决"这四种 LLM 审查者的典型失效模式。

这些原则与同仓库的 receiving-code-review 技能 构成闭环：本模板约束审查者"给出什么"，receiving 技能约束实现方"如何接收"——先验证再实现、有技术分歧就反驳、逐条修复并逐条测试。两者合起来，就是 Superpowers 对"Agent 时代代码审查"这一问题的完整回答：审查不再是会话里的寒暄，而是一个有输入契约、输出契约和行为红线的子代理任务。