requesting-code-review Agent Skill 实战教程:安装配置与 5 个核心用法
requesting-code-review Agent Skill 实战教程:安装配置与 5 个核心用法
活干完了就合入主干,是编码代理最危险的习惯之一——SKILL.md 把「实施完成后请求评审」这件事拆成了可以照抄的三步:取两个 SHA、按模板派一个评审子代理、按严重度处置反馈。这篇教程覆盖 obra/superpowers 仓库(GitHub 29.8 万 star,MIT 协议)里 requesting-code-review 技能的安装挂载、评审时机、SHA 提取、评审模板四大板块逐段讲解,配一套在干净 git 仓库里跑通的实测记录,末尾是官方文档里白纸黑字的 Red Flags 清单。
相关背景可参考 AI 编程总纲,工具档案见 Superpowers 产品页。同仓库的 brainstorming、diagnosing-superpowers、finishing-a-development-branch、receiving-code-review 实战已在站内上线,其中 receiving-code-review 管的是「收到评审反馈怎么接」,本篇管的是「怎么主动把评审要过来」,两篇正好凑成一对。
这套技能管住的是哪一步
先看它管的是哪一段。SKILL.md 第一句给的是定性:
Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history.(派发一个代码评审子代理,在问题级联之前抓住它。评审者拿到的是精心构造的评审上下文——绝不是你的会话历史。)
两句话各管一件事。前半句说时机:问题要「before they cascade」,在滚雪球之前拦住,所以官方口号是 Review early, review often。后半句说方式:评审子代理不该继承你的会话历史。你想让代理写完代码自查一遍,它往往把自己的代码再读一遍然后说没问题——带着同样的上下文看同样的东西,看不出新问题。派一个只拿到 diff 和需求描述的新代理,视角才是干净的。
什么时候必须请求评审,SKILL.md 用 Mandatory 和 optional but valuable 分了两档。强制档三个时机:子代理驱动开发的每个任务完成之后、大功能完成之后、合并回 main 之前。可选档三个时机:卡住的时候(换个视角)、重构之前(先留个基线)、修完复杂 bug 之后。强制档没得商量,可选档官方原话是「有价值但非强制」。
安装与挂载
这个技能是 obra/superpowers 仓库 skills/ 目录下的一个文件夹,总共只有两个文件:SKILL.md(95 行的技能定义)和 code-reviewer.md(评审子代理的提示词模板)。它不是独立安装的包——你得把整个 superpowers 仓库克隆到本地,再让编码代理把技能目录挂进搜索路径:
git clone https://github.com/obra/superpowers.git # Claude Code:技能放 ~/.claude/skills/ 或项目 .claude/skills/ 下 # 其他代理:把 skills/ 目录加进代理的技能搜索路径即可
挂载成功的标志是代理能报出技能名 requesting-code-review。仓库当前 297,537 star、MIT 协议,最近一次推送在 2026 年 10 月 10 日,仍在活跃维护——技能文件会随仓库更新,本文截图均取自 main 分支当前版本。
用法一:取基线和终点两个 SHA
请求评审的第一步是把「评什么」圈出来。官方给的是两条命令:
BASE_SHA=$(git rev-parse HEAD~1) # 或者: git merge-base origin/main HEAD HEAD_SHA=$(git rev-parse HEAD)
BASE_SHA 是评审起点,HEAD_SHA 是终点,评审范围就是这两个提交之间的 diff。两个写法有讲究:如果改动就一个提交,HEAD~1 够用;如果分支上攒了一串提交,起点应该用 git merge-base origin/main HEAD——从主干分叉的那个点,这样才不会漏评中间的提交。
SKILL.md 的示例里还有第三种取法,按提交信息找:`BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | cut -d' ' -f1)`——从日志里捞出上一个任务的提交号当起点。下面是在一个双任务演示仓库里跑这三条命令的真实输出:

requesting-code-review 第一步的 SHA 提取命令在演示仓库的真实输出,右下角的 review-package 复用见用法四
图里能看到一个细节:`grep "Task 1"` 抓到的短 SHA 是 5c9c970,而最后一条命令用的 BASE 是 2798e33——前者是 Task 1 的提交(Task 2 的评审起点),后者是分支起点(终审范围),两条路径对应两种评审口径,别混用。
用法二:按模板派评审子代理
SHA 到手,第二步是派子代理。SKILL.md 的指令只有一行:派一个 general-purpose 子代理,填 code-reviewer.md 里那个模板。模板要填四个占位符:`{DESCRIPTION}` 你做了什么的简述、`{PLAN_OR_REQUIREMENTS}` 它应该做什么(计划文件路径、任务原文或需求描述)、`{BASE_SHA}` 起点、`{HEAD_SHA}` 终点。
code-reviewer.md 这个模板本身值得展开。它给评审子代理立了一套相当细的规矩,几条关键的原文如下:
Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way.(你的评审对当前检出只读。不得以任何方式改动工作区、索引、HEAD 或分支状态。)
Do all of this review yourself. Never spawn a subagent to review part of the diff, and never spawn another reviewer for a second opinion.(全部评审自己做。绝不派子代理评审 diff 的一部分,也绝不另派一个评审者要第二意见。)
还有一条对中文开发者很实用:模板要求评审者「Declined to judge」——裁决之前,把它考虑过但判定为超出计划范围的行为逐条列出来,一行一条写明理由,空的也要说明。评审范围里每一项要么有裁决、要么明确挂起,不许悄悄漏掉。
模板的输出格式也是定死的:Strengths(先讲做得好的)、Issues 按 Critical / Important / Minor 三级分类、每条要带 文件:行号、最后 Assessment 给出 Ready to merge 的 Yes / No / With fixes 三选一裁决。格式固定的好处是结果可比较——同一套模板跑十次评审,产物长一个样,能不能合并一眼可判。
用法三:按严重度处置反馈
评审回来了怎么接,SKILL.md 给的处置矩阵相当干脆:

Critical 立即修、Important 修完再走、Minor 记账、评审有误带理由反驳——四级处置各有着落
Critical 对应 bug、安全问题、数据丢失风险,官方要求 Fix Critical issues immediately。Important 是架构问题、缺功能、测试缺口,要求在继续下一步之前修掉。Minor 允许挂账,但要记录下来以后处理。第四级最容易被忽略:如果你判断评审意见本身是错的,SKILL.md 明确允许反驳,且给出了反驳的三件套——技术理由、能证明它工作的代码或测试、请求澄清。注意方向别搞反:和「有效的技术反馈」争吵才是 Red Flags,带着理由推翻「错误的反馈」是官方鼓励的。
用法四:把 diff 装进一个文件再评审
模板里评审子代理要跑 `git diff --stat [BASE]..[HEAD]` 和 `git diff [BASE]..[HEAD]`。superpowers 仓库把这个动作标准化成了一个脚本——subagent-driven-development 技能目录下的 scripts/review-package,一条命令把提交清单、stat 汇总、带上下文的全量 diff 写进一个文件:
bash review-package PLAN_FILE BASE HEAD # 产物: .superpowers/sdd/<plan>/review-<base7>..<head7>.diff
要说明的是,这个脚本不在 requesting-code-review 自己的目录里——该技能只有 SKILL.md 和 code-reviewer.md 两个文件,打包动作官方文档明确放在隔壁 subagent-driven-development 技能的 scripts/ 目录下,属于两个技能的配套关系,单装前者用不到它。另外脚本注释里白纸黑字提醒过一个坑:BASE 要用派发实现者之前记录的提交号,不要用 HEAD~1——多提交任务会被它静默截掉只剩最后一个提交,评审范围凭空变窄。
这个脚本在隔壁 subagent-driven-development 技能目录下,和本技能的评审流程是配套设计:评审者一次读完一个文件,而不是自己在会话里拼 git 命令。下面是它在演示仓库里真实生成的评审包全文:

一个真实评审包全文:两个提交、两个文件、18 行新增,评审子代理要读的就是这一个文件
脚本自带两道保险:BASE 不是 HEAD 的祖先会直接报错退出(评错分支的情况),空提交范围也报错。文件名按范围命名,评审过后再修再评,新范围会生成新文件,不会覆盖旧的。
官方点名的两类自我合理化
SKILL.md 末尾有一张 Common Rationalizations 表,专治「我绕过流程的理由」。两条原文翻译过来:
第一条:「我就自己在会话里看一遍 diff,不派评审子代理了」。官方回应:你是协调者,inline 看 diff 烧掉的是你继续推进工作需要的上下文窗口——派个评审子代理,diff 和评估都活在它的上下文里,回来的只有结论。
第二条:「评审者需要我完整的会话历史才能理解这个改动」。官方回应:给它精心构造的上下文,永远不给会话历史。这让它聚焦在工作产物上,而不是你的思考过程。
两条其实是同一个原则的两面:上下文隔离不是省钱技巧,是评审有效性的来源。
Red Flags:四个绝不
最后是 Never 清单,四条都是代理最常犯的:
绝不因为「改动很简单」跳过评审——简单恰恰是最容易藏 bug 的地方;绝不无视 Critical 问题;绝不带着未修的 Important 问题往下走;绝不和无端反驳有效技术反馈的行为纠缠。四条对照着处置表看,前两条违反处置矩阵,后两条违反协作契约,条条都能落到具体动作上。
写在最后
requesting-code-review 是 superpowers 体系里最短的一个技能,95 行 SKILL.md 加一个 198 行的模板文件,但它卡的位置很关键:所有上游产物(实现、计划)在这里接受第一次外部检验,所有下游动作(合并、收尾)以它的裁决为前提。把 SHA 取对、把模板填全、把反馈按级处置,这三件事做到位,评审就不是走过场。
本文步骤与配图依据 obra/superpowers 仓库 skills/requesting-code-review 目录的 SKILL.md 与 code-reviewer.md(main 分支,2026 年 10 月)整理,实测部分来自作者本地环境,版权归原作者所有。