Superpowers 的 requesting-code-review 技能：调度独立代码评审子代理的完整实战指南

2026-09-04 11:25:18作者：段琳惟

本文基于 superpowers 仓库中的 skills/requesting-code-review/SKILL.md 及其配套模板 skills/requesting-code-review/code-reviewer.md，完整讲解如何为已完成的代码变更调度一个"上下文隔离"的代码评审子代理（code reviewer subagent）：何时必须评审、如何用 git SHA 界定评审范围、如何填充评审提示词模板、如何按严重程度处理评审结论。读完后，你可以在多代理开发流程中把"自我审查"替换为"独立审查"，让问题在扩散（cascade）之前被拦下，而不是烧掉协调者宝贵的上下文窗口。

这个技能解决什么问题

requesting-code-review 的核心原则只有一句话：Review early, review often（尽早评审，频繁评审）。它在 superpowers 技能库中的定位由 frontmatter 直接给出：

name: requesting-code-review
description: Use when completing tasks, implementing major features, or
  before merging to verify work meets requirements

技能开宗明义：调度一个代码评审子代理，在它"精确裁剪"的上下文中完成评估——永远不要把你的会话历史交给它。这一点是整个技能的设计基石：

diff 和评估过程都发生在评审子代理自己的上下文里，只有评审结论（findings）会返回给你；
你作为协调者（coordinator），自己的上下文窗口要留着驱动后续工作，而不是消耗在逐行读 diff 上；
评审者聚焦的是"工作产物"（the work product），而不是你的思考过程。

何时必须请求评审（When to Request Review）

SKILL.md 把触发时机分为"强制"与"可选但 valuable"两档：

强制（Mandatory）：

子代理驱动开发（subagent-driven development）中每完成一个任务之后；
完成一个重大功能（major feature）之后；
合并到 main 分支之前。

可选但价值高（Optional but valuable）：

卡住的时候（stuck）——换一个全新视角；
重构之前（baseline check，建立评审基线）；
修复复杂 bug 之后。

需要注意的是节奏的演进：RELEASE-NOTES.md 记录，早期版本中"每 3 个任务（每批）评审一次"的固定节奏会从 executing-plans 泄漏到 subagent-driven-development，造成不必要的停顿；后来被改为"每个任务之后，或在自然检查点"并配套明确的"连续执行"指令。从当前仓库的 skills/subagent-driven-development/SKILL.md 可以看到执行口径：绝不允许在评审还有未修复、也未按上限裁定搁置（parked-with-ruling）的 Critical/Important 问题时进入下一个任务。

三步完成一次评审调度（How to Request）

第 1 步：确定 git 范围（BASE_SHA / HEAD_SHA）

评审的对象不是一个模糊的"最近改动"，而是一个精确的提交区间。SKILL.md 给出的基础命令：

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

BASE_SHA 是区间的起点提交：单提交场景取 HEAD~1，跨多提交或整分支场景取 origin/main（或 merge-base）；
HEAD_SHA 是区间终点，通常是 git rev-parse HEAD。

对于"从某个任务标记提交到当前"的场景，SKILL.md 的示例中给出了一个实用变体：

BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
HEAD_SHA=$(git rev-parse HEAD)

这个范围会直接写进评审提示词的 Git Range to Review 部分，评审者据此执行：

git diff --stat [BASE_SHA]..[HEAD_SHA]   # 先看改动规模
git diff [BASE_SHA]..[HEAD_SHA]          # 再看完整 diff

第 2 步：调度 general-purpose 子代理并填充模板

调度目标是 general-purpose 子代理（而非任何命名代理），提示词来自模板 skills/requesting-code-review/code-reviewer.md。模板含 4 个占位符，全部填充后发出：

占位符	含义	示例取值
`{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`

模板的完整结构（见 code-reviewer.md）包含以下组成部分，调度前理解这些部分有助于你判断该模板为何有效：

角色设定：一位精通软件架构、设计模式和最佳实践的 Senior Code Reviewer，任务是"对照计划或需求评审已完成的工作，在问题扩散前发现问题"；
What Was Implemented / Requirements / Plan：即 {DESCRIPTION} 与 {PLAN_OR_REQUIREMENTS} 两个占位段，为评审提供"应该是什么样"的对照基准；
Git Range to Review：写明 Base/Head 两个 SHA 并附 git diff --stat / git diff 命令；
Read-Only Review 约束：评审者对本 checkout 严格只读——不得修改工作树、索引、HEAD 或分支状态；用 git show、git diff、git log 检查历史；若需要另一个修订版本的工作副本，用 git worktree add /tmp/review-[SHA] [SHA] 检出到独立临时目录，绝不在本 checkout 上移动 HEAD；
What to Check 五个维度：
- 计划一致性：实现是否匹配计划/需求？偏差是合理的改进还是有问题的问题？计划内的功能是否齐全？
- 代码质量：关注点分离、错误处理、类型安全、"DRY 但不过度抽象"、边界情况；
- 架构：设计决策是否合理、可扩展性与性能、安全顾虑、与周边代码的集成是否干净；
- 测试：测试验证的是真实行为而非 mock？边界覆盖？该有集成测试的地方有没有？全部通过？
- 生产就绪：schema 变更是否有迁移策略、是否考虑向后兼容、文档是否完整、有无明显 bug；
Calibration（校准）指令：按真实严重程度分级，"不是所有问题都是 Critical"；在列问题之前先承认做得好的部分（准确的表扬能帮实现者信任其余反馈）；发现与计划的重大偏差要明确标出，让实现者确认偏差是否有意为之；如果问题出在计划本身而非实现，也要直说；
Output Format：固定为 Strengths → Issues（Critical 必须修 / Important 应当修 / Minor 最好有）→ Recommendations → Assessment（"Ready to merge? Yes | No | With fixes" + 一两句技术理由）。每个 issue 必须给出 File:line 引用、问题是什么、为什么重要、如何修复（若不明显）；
Critical Rules：DO——按真实严重程度分级、给出具体 file:line、解释每个问题为何重要、承认优点、给出明确结论；DON'T——没检查就说 "looks good"、把吹毛求疵标成 Critical、对没实际读过的代码给反馈、含糊其辞（"improve error handling"）、回避明确结论。

一个设计细节值得注意：模板明确要求"先给 Strengths，再列 Issues"。这不是礼貌要求，而是校准机制——准确的正面反馈建立可信度，让实现者（或后续修复者）愿意认真对待后面的问题清单。

第 3 步：按严重程度处置反馈（Act on feedback）

评审返回后，SKILL.md 给定了明确的处置策略：

Critical（bug、安全问题、数据丢失风险、功能损坏）：立即修复；
Important（架构问题、缺失功能、错误处理不足、测试缺口）：继续推进之前修复；
Minor（代码风格、优化机会、文档润色）：记录下来稍后处理；
如果评审者错了：用技术推理据理力争（push back with reasoning），而不是盲从。

SKILL.md 中的完整示例展示了一个"任务 2 完成 → 评审 → 修复 Important → 进入任务 3"的真实循环：

[Just completed Task 2: Add verification function]

You: Let me request code review before proceeding.

BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
HEAD_SHA=$(git rev-parse HEAD)

[Dispatch code reviewer subagent]
  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

[Subagent returns]:
  Strengths: Clean architecture, real tests
  Issues:
    Important: Missing progress indicators
    Minor: Magic number (100) for reporting interval
  Assessment: Ready to proceed

You: [Fix progress indicators]
[Continue to Task 3]

注意这个例子里的处置逻辑：Important 级的"缺少进度指示"被立即修复，Minor 级的魔法数字 100 只是记录，随后才放行进入 Task 3——这正是"Critical 立即修、Important 先修再继续、Minor 记下来"规则的具体落地。

跨平台的调度方式：同一模板，不同 harness

技能文档写的是 Subagent (general-purpose) 的抽象调度形式，具体到不同编码代理（harness）需要映射到各自的子代理机制。以 skills/using-superpowers/references/gemini-tools.md 给出的对照为例：

Skill 调度形式	Gemini CLI 等价做法
参考 `*-prompt.md` 模板（implementer、task-reviewer、code-reviewer 等）	填充模板后，用 `agent_name: "generalist"` 调用 `invoke_agent`
参考 `superpowers:requesting-code-review` 的 `./code-reviewer.md`	用 `agent_name: "generalist"` 调用 `invoke_agent`，带上填充好的评审模板
内联提示词（不参考模板）	用 `agent_name: "generalist"` 调用 `invoke_agent`，带上你的内联提示词

要点是：模板本身就是单一事实来源——它承载角色、评审标准和期望输出格式，子代理会照着执行；你在不同平台上要做的只是"填充占位符 → 以通用代理身份发出"。这与 RELEASE-NOTES.md v5.1.0 的"Code Review Consolidation"一节呼应：requesting-code-review 已完全自包含（persona、checklist、调度模板都在 code-reviewer.md 里），技能直接调度 Task (general-purpose)。

与 subagent-driven-development 的衔接：最终整分支评审

requesting-code-review 不是孤立技能，它是 SDD（subagent-driven-development）流程的收尾环节。从 skills/subagent-driven-development/SKILL.md 的 Final Review 一节可以看到完整的集成方式：

全部任务完成后，运行 scripts/review-package PLAN_FILE MERGE_BASE HEAD（MERGE_BASE 取 git merge-base main HEAD），生成一个打包好的评审材料文件，让最终评审者读一个文件而不必自己用 git 命令重算整个分支 diff；
用可用的最强模型调度最终评审子代理，明确指向 skills/requesting-code-review/code-reviewer.md 模板，并把台账（ledger）中 deferred-minor 与 parked 行交给它分诊——判断哪些必须在合并前修复；
若最终评审有发现：只调度一个修复子代理携带完整发现列表（而不是每个发现一个修复者——按仓库记录，真实会话中"按发现分派"的修复波成本超过了所有任务之和）；随后执行一次范围受限的复审（scripts/review-package PLAN_FILE FIX_BASE HEAD + re-review-prompt.md），残余发现按任务循环的熔断规则裁定，没有第二次修复波。

这里还有一层"宽窄分工"值得理解：docs/superpowers/specs/2026-06-09-sdd-task-scoped-review-dispatch-design.md 明确指出，code-reviewer.md 是合并就绪（merge-readiness）评审——问架构、可扩展性、安全、生产就绪，以 "Ready to merge?" 收尾。这个框架适合整分支的最终评审和临时评审，但不适合单任务 diff 的逐任务质量评审（后者会"许可"在一任务 diff 上施加分支级宽度的审查）。因此 SDD 的逐任务质量评审使用了独立的任务范围模板，而 requesting-code-review/ 目录保持不动，继续作为最终整分支评审与临时评审的宽模板。这也解释了为什么模板里的 checklist 会包含"生产就绪/迁移策略"这类分支级问题。

常见自我开脱与红旗（Common Rationalizations & Red Flags）

SKILL.md 用仓库统一的"Excuse/Reality"表格直面两个最常见的跳过评审的理由：

Excuse	Reality
"我自己审一下 diff 就好，不用调度评审者"	你是协调者——就地读 diff 会烧掉你用来持续驱动工作的上下文窗口。调度评审子代理：diff 和评估都发生在它的上下文里，只有发现会返回给你。
"评审者需要我整个会话历史才能理解改动"	给它精确裁剪的上下文，永远不要给会话历史。这让评审者聚焦工作产物，而不是你的思考过程。

Red Flags——绝不做：

因为"很简单"就跳过评审；
无视 Critical 问题；
带着未修复的 Important 问题继续推进；
与有效的技术反馈争论。

评审者错了怎么办：

用技术推理反驳；
拿出能证明其可用的代码/测试；
请求澄清。

这里的"反驳"不是嘴上说说，而是由姊妹技能 skills/receiving-code-review/SKILL.md 规范化的完整流程：先读完整反馈再反应 → 用自己的话复述需求 → 对照代码库现实验证 → 评估"对这个代码库是否技术成立" → 给出技术性确认或有理有据的反驳 → 逐项实现并逐项测试。它明确禁止"You're absolutely right!"式的表演性附和，要求用技术正确性而不是社交舒适作为回应标准。两个技能合起来构成闭环：requesting 负责"发出一份可信的评审"，receiving 负责"像工程师而不是客服一样消化评审"。

行为验证：这个技能是被测试过的

RELEASE-NOTES.md 记录了两条佐证该技能真实行为的关键事实：

行为测试（drill）：tests/claude-code/test-requesting-code-review.sh 曾在一个微型项目中植入真实 bug（SQL 注入、明文密码处理、凭据日志），断言被调度的评审者把每个植入问题标记为 Critical/Important 级别，并拒绝批准该 diff。该脚本于 2026-05-06 提升为 drill 场景并移出 tests/，现位于 superpowers-evals 克隆到 evals/ 子模块的场景 code-review-catches-planted-bugs.yaml（见 docs/superpowers/plans/2026-05-06-lift-drill-into-evals.md）。这意味着"评审者能抓住安全问题"不是文档修辞，而是可重复执行的断言。
上下文隔离原则：RELEASE-NOTES.md 还记录，所有委派类技能（brainstorming、dispatching-parallel-agents、requesting-code-review、subagent-driven-development、writing-plans）都已内置 context isolation 原则——requesting-code-review 的"只给精确上下文，不给会话历史"是这一体系的组成部分。

在 Superpowers 整体工作流中的位置

README.md 的 "The Basic Workflow" 把七个技能串成一条完整开发流水线，requesting-code-review 位于第 6 位：

brainstorming — 写代码前细化想法，保存设计文档；
using-git-worktrees — 在隔离工作区/新分支上工作，验证干净的测试基线；
writing-plans — 把工作拆成 2–5 分钟的小任务，每个任务有精确文件路径与验证步骤；
subagent-driven-development 或 executing-plans — 每个任务调度新子代理（两阶段评审：规格符合性，然后代码质量）；
test-driven-development — 强制 RED-GREEN-REFACTOR；
requesting-code-review — 在任务之间激活，对照计划评审、按严重程度报告问题，Critical 问题阻塞进度；
finishing-a-development-branch — 验证测试，给出合并/PR/保留/丢弃选项，清理 worktree。

README 同时强调："The agent checks for relevant skills before any task. Mandatory workflows, not suggestions."——包括 requesting-code-review 在内的技能是强制工作流，而非建议项。

速查清单

把整套流程压缩成可执行清单：

触发判断：刚完成任务/重大功能、即将合并 main → 必须评审；卡住、重构前、修完复杂 bug → 建议评审；
定范围：BASE_SHA / HEAD_SHA 用 git rev-parse（或按任务标记的 git log 变体）确定，绝不模糊；
填模板：{DESCRIPTION}、{PLAN_OR_REQUIREMENTS}、{BASE_SHA}、{HEAD_SHA} 四占位符全填，按目标平台映射到 general-purpose / generalist 等通用子代理；
收结论：Strengths → Issues（Critical/Important/Minor，每条带 file:line）→ Recommendations → Assessment；
按级处置：Critical 立即修、Important 先修再继续、Minor 记录、错误结论用技术推理反驳（配合 receiving-code-review 的六步响应模式）；
守红旗线：不因"简单"跳过、不无视 Critical、不带着未修 Important 前进。

核心文件索引：

skills/requesting-code-review/SKILL.md — 技能主体：触发时机、三步流程、示例、Excuse/Reality 表、Red Flags；
skills/requesting-code-review/code-reviewer.md — 评审提示词模板：角色、只读约束、五维 checklist、校准与输出格式、Critical Rules；
skills/receiving-code-review/SKILL.md — 姊妹技能：如何技术性地接收与反驳评审反馈；
skills/subagent-driven-development/SKILL.md — 最终整分支评审如何消费本技能模板；
skills/using-superpowers/references/gemini-tools.md — 跨平台（Gemini CLI）调度映射；
RELEASE-NOTES.md — 行为测试与模板整合（v5.1.0）的演进记录。