requesting-code-review

requesting-code-review 技能概览

requesting-code-review 技能是一套轻量级工作流，用来在合适的时机、基于合适的 diff 范围，并带着足够的实现上下文发起一次聚焦的代码审查，让 reviewer agent 能给出真正有用的反馈。它不是让你笼统地说一句“帮我 review 一下代码”，而是要求你明确提供 commit range、变更摘要，以及这次实现对应的目标和要求。

requesting-code-review 技能到底做什么

从核心机制看，requesting-code-review 会指导你使用 code-reviewer.md 里的预设模板，调用 superpowers:code-reviewer 这个 subagent。它真正的价值不在于复杂自动化，而在于review framing：reviewer 看到的是这次工作的产物和预期计划，而不是你整个会话历史。这样审查范围更聚焦，结论也更容易落地执行。

谁适合安装 requesting-code-review

这个技能特别适合以下开发者和 AI agent 使用者：

• 以 commit 为边界推进开发流程
• 习惯把功能拆成多个步骤交付
• 想要建立可重复执行的“继续开发前先 review”检查点
• 正在使用 subagent，希望交接方式比通用 prompt 更清晰

如果你经常等到太晚才发起 review，导致多个任务堆成一个巨大的 diff，这个技能会尤其有帮助。

这个技能真正解决的需求是什么

用户安装 requesting-code-review，并不只是为了“拿到一次 review”，更是为了减少本可避免的返工：

• 在 merge 前提前发现问题
• 对照原始计划验证实现是否偏离
• 拿到按严重程度排序的反馈
• 在 reviewer agent 独立审查代码时，保留主任务上下文不被打断

为什么它比普通 review prompt 更有用

requesting-code-review skill 提供了很多临时写 prompt 时常常缺失的结构化约束：

• 明确的 review 时机建议：每个任务后、重大功能完成后、merge 前
• 显式要求传入 BASE_SHA 和 HEAD_SHA
• 内置 review 模板，覆盖代码质量、架构、测试、需求符合度和生产可用性
• 按严重级别输出问题，便于后续处理

所以它产出的结果，通常会比一句“帮我看看最近改动”更可执行。

在决定采用前，最需要看重什么

采用这个技能时，最大的问题不是“能不能用”，而是“适不适合你的工作方式”。它最适合这样的场景：你的工作能被整理成一个清晰的 git range，而且你能简要说清楚预期行为。如果你的分支历史很乱、计划本身不明确，或者本次改动混入了无关编辑，review 质量就会明显下降。

一开始就要知道的重要限制

requesting-code-review for Code Review 本身并不是一个完整的 review 系统。它不自带脚本、强制规则，也没有针对特定仓库的检查器。它本质上是一种更有纪律的 prompting 和交接模式。这本身很有价值，但你也要预期：最终质量会高度依赖 commit range 是否准确，以及需求描述是否清楚。

如何使用 requesting-code-review 技能

在你的 skills 环境中安装 requesting-code-review

如果你使用的是这个仓库里通用的 Skills CLI 模式，可以这样安装：

npx skills add https://github.com/obra/superpowers --skill requesting-code-review

如果你的环境里已经有 obra/superpowers 这套 skill collection，那就直接启用或引用其中的 requesting-code-review 即可。

先读这两个文件

想快速判断值不值得用，建议先看：

1. skills/requesting-code-review/SKILL.md
2. skills/requesting-code-review/code-reviewer.md

SKILL.md 说明了应该在什么时机触发 review。
如果你更关心输出质量，那更关键的是 code-reviewer.md，因为它清楚写明了 reviewer 会按哪些维度来评估你的改动。

先理解这个技能预期的触发时机

这个技能设计出来就是为了在以下时点使用：

• 在 subagent 驱动开发中，每完成一个任务后
• 重大功能完成后
• merge 到 main 之前

另外几个虽然可选，但价值也很高的时机包括：

• 你卡住了，想让系统从新角度帮你看问题
• 做高风险重构前
• 修完复杂 bug 之后

如果你总是等到一个大型分支开发快结束时才用，那这个技能最有价值的部分基本就损失掉了。

调用前先准备最少必要输入

这个技能在你提供以下信息时效果最好：

• 实际实现了什么
• 原始计划或需求
• BASE_SHA
• HEAD_SHA
• 简短的变更说明

常见的 git 命令如下：

BASE_SHA=$(git rev-parse HEAD~1)
HEAD_SHA=$(git rev-parse HEAD)

如果是 feature branch，且你希望 review 的窗口更完整，那么用 origin/main 作为 base，通常会比 HEAD~1 更合适。

用清晰的 diff 范围，不要只说“最近改动帮我看下”

这是 requesting-code-review usage 模式里最能拉开效果差距的一环。把 review 锁定在 BASE_SHA..HEAD_SHA 上，远比让 agent 从 working tree 或聊天上下文里猜“你到底改了什么”有效。

更好的写法：

• “Review commits from feature start to current head against the signup flow requirements.”

较弱的写法：

• “Can you review my recent auth changes?”

前者能显著收缩范围，减少 reviewer 的猜测成本。

把模糊目标变成高质量的 review 请求

像下面这种请求就太薄弱了：

Please review my new feature.

更符合这个技能设计方式的强请求，可以像这样：

Review the password reset implementation for production readiness.

What was implemented:
- Added reset token generation and validation
- Added reset email endpoint
- Added UI flow for requesting and completing reset

Plan/requirements:
- Tokens expire after 30 minutes
- Single-use tokens only
- No user enumeration from the request endpoint
- Existing login flow must remain unchanged

Base SHA: abc1234
Head SHA: def5678
Description:
Task 2 of auth hardening. Main changes are in API handlers, email service, and reset form.

这样 reviewer 才有足够上下文去判断实现是否正确，而不是只能点评代码风格。

按技能预期的方式派发 reviewer subagent

仓库中的指导写得很明确：应使用 Task tool，并指定 superpowers:code-reviewer 类型，同时按 code-reviewer.md 模板填写内容。这个模板会要求 reviewer：

• 对比实现与原始计划是否一致
• 检查 git diff
• 评估质量、架构、测试和生产可用性
• 按严重程度返回发现的问题

如果你的 agent 平台支持 subagent，最好把 review 放在独立上下文中执行，而不是混进当前正在工作的同一个对话里。

reviewer 模板最擅长发现什么问题

内置 checklist 最强的地方在于帮你暴露这些问题：

• 需求遗漏
• 明显的生产可用性缺口
• 测试覆盖不足
• 架构层面的隐患
• 危险的边界条件
• 向后兼容或迁移步骤遗漏

但如果你需要的是行业合规、仓库特定约定，或者更深入的运行时验证，这个模板就没那么专门了，除非你额外补充这些要求。

真实项目里推荐的使用流程

一个实用的 requesting-code-review guide 通常是这样的：

1. 完成一个边界清晰的任务
2. 确定准确的 diff 范围
3. 总结目标意图和验收标准
4. 用模板派发 reviewer
5. 修复 critical 和 important 问题
6. 如果修复改动不小，再跑一轮 review
7. 继续开发或执行 merge

这个技能最有效的用法，是把它当作实现步骤之间的检查点，而不是最后的一道形式化关卡。

哪些小技巧能明显提升输出质量

想拿到更好的 review 结果，可以这样做：

• 让 diff range 只包含一个逻辑变更
• 不要只写功能名，要给出 acceptance criteria
• 主动指出高风险区域，比如 migration、auth、concurrency、caching、API contracts
• 说明是否补了测试，以及补的是哪类测试
• 明确告知 breaking change 是预期内还是绝对不能出现

这些信息会帮助 reviewer 区分“有意的取舍”和“无意的遗漏”。

常见误用会怎样拉低价值

如果你的团队平时就是下面这种方式在工作，那 requesting-code-review install 的收益会明显打折：

• 把很多互不相关的改动塞进同一个 commit range
• 没有书面的需求说明
• git 边界基本不可用
• 指望这个技能直接取代人工审批或 CI

如果是这种情况，最好先把流程整理干净，否则 review 结果大概率会更嘈杂。

requesting-code-review 技能 FAQ

requesting-code-review 适合新手吗？

适合，但前提是你已经理解 commit、SHA 这类基础 git 概念。这个技能本身不复杂，但它默认你有能力说明“改了什么”和“本来应该实现什么”。如果新手跳过这部分上下文，依然能得到反馈，只是可靠性会下降。

这个技能会 review 未提交的改动吗？

按设计来说，不是。整个工作流是围绕 BASE_SHA 和 HEAD_SHA 搭建的，所以它最适合 review 已提交的工作。你当然可以把它改造到 unstaged 或未提交改动上，但那就偏离了这个技能的核心结构，通常也会让 review 更难复现。

requesting-code-review 和直接让 AI 帮我 review 代码，有什么不同？

普通 prompt 往往会产出比较泛的 review，因为模型需要自己猜范围、意图和验收标准。requesting-code-review 通过强制要求以下信息来改善这个问题：

• 明确的 diff
• 清楚的实现摘要
• 原始计划或需求
• 按严重级别组织的输出格式

通常这样拿到的结果会更容易信任，也更容易转化为后续动作。

什么情况下不该用 requesting-code-review？

以下情况建议先别用：

• 改动还太不完整，根本没法评估
• diff 里混了多个无关功能
• 你自己都还不清楚预期行为是什么
• 你更需要 repo-specific 的静态检查，而不是偏判断型的 review

另外，如果你的团队根本不会按 git commit range 来组织工作，这个技能也不太适合。

它能取代人工 code review 吗？

不能。最理想的定位，是把它作为正式 review 之前的预检查，或者开发步骤之间的质量闸门。它可以帮助你提前发现问题，也能让后续人工 review 更顺畅，但它不能替代领域知识、团队约定或组织层面的审批要求。

requesting-code-review 只适合大型功能吗？

不是。恰恰相反，越小的 diff 越能发挥这个技能的优势。它明确鼓励你更早、更频繁地发起 review，而这通常比等到最后做一次大而全的审查更有效。

它适合什么样的生态和工作流？

这个技能最适合放在 obra/superpowers 工作流里使用，尤其适合已经在用 subagents 的团队。它比完整的 review framework 更轻，也比自建 review 自动化更容易上手；但反过来说，这也意味着它提供的护栏更少。

如何改进 requesting-code-review 技能

给 reviewer 更好的需求信息，而不只是“更好的代码”

这个技能最常见的失效模式，不是代码太差，而是计划上下文太弱。比如你只说“implemented notifications”，reviewer 就很难判断“缺少 retry 路径”到底是 bug，还是本来就不在范围内。最好补充这些具体预期：

• 触发条件
• 出错时的行为
• 向后兼容要求
• 性能或安全要求

需求越具体，review 判断通常越靠谱。

把 review 切成尽可能小但仍有意义的单元

requesting-code-review skill 在面对单个任务或紧密相关的一组改动时表现最好。如果一个 diff 里同时塞了 schema 变更、API 调整、UI 更新和无关清理，最终发现的问题就会变得宽泛且难处理。只要条件允许，尽量把工作拆成可 review 的独立单元。

选对 base commit

错误的 BASE_SHA 会直接带来误导性的反馈。比如一个功能跨了六个 commit，但你用了 HEAD~1，那 reviewer 看到的信息就太少；反过来，如果 base 选得太老，又会把大量噪音一起带进来。正确做法是：让 base 对应你真正希望被评估的那一段逻辑工作单元。

不要用含糊占位符，换成 reviewer 能在脑中验证的具体信息

模板里有这些占位符：

• {WHAT_WAS_IMPLEMENTED}
• {PLAN_OR_REQUIREMENTS}
• {BASE_SHA}
• {HEAD_SHA}
• {DESCRIPTION}

如果改动本身有风险，就不要只用一句话把它们糊过去。要明确写出预期行为。比如，“prevents user enumeration and invalidates token after first successful reset” 就比 “added password reset” 强得多。

主动告诉 reviewer 风险在哪里

如果你知道哪些位置最危险，就直接说：

• “Please pay special attention to race conditions around token reuse.”
• “Check backward compatibility for existing API consumers.”
• “Focus on whether tests cover the error path and expiry boundary.”

这样可以把注意力集中到关键点上，更容易得到真正有价值的发现。

第一轮 review 之后继续强化结果

拿到第一轮输出后，可以这样处理：

1. 先修复那些明显正确的 critical 问题
2. 对看起来不对的结论提出质疑
3. 补充缺失的需求信息
4. 如果改动更新较大，再基于新 diff 做第二轮 review

这个技能本身就鼓励你在 reviewer 判断错误时提出反驳，这是好事：它的设计目标是辅助判断，而不是替代判断。

需要时加入 repo-specific 的 review 标准

默认的 code-reviewer.md 已经能较好覆盖通用 review 维度，但很多团队还需要更多。要提升 requesting-code-review for Code Review 的实际效果，可以加入项目特有的检查项，比如：

• migration rollout 规则
• observability 要求
• accessibility 预期
• 安全审查要点
• 特定语言或框架的约定

如果你想减少“泛泛而谈”的输出，这是最值得做的一项升级。

注意这些反复出现的失败模式

review 质量下降，最常见的原因通常是：

• 需求缺失或描述模糊
• commit range 噪音太多
• 没有说明预期的非功能性行为
• 任务积累太多之后才一次性发起 review
• 把次要建议当成必须修改，却漏掉真正关键的设计问题

如果你觉得输出太浅，先回头检查输入，通常比怀疑模型本身更有用。

想提高输出质量，就让 reviewer 做决策判断，而不只是找 defect

更强的 requesting-code-review usage 方式，是要求 reviewer 连权衡取舍一起评估。比如：

• “Flag any unnecessary complexity.”
• “Call out if this should be split before merge.”
• “Assess whether current tests justify production readiness.”

这样就能把 review 从类似 lint 的评论，推进到更接近发布质量判断的层面。

在你自己的环境里迭代这个技能的实用做法

如果你准备认真采用这个技能，最先值得自定义的是这三件事：

1. 你们偏好的 base commit 选择规则
2. 一套统一的 requirements 和 acceptance criteria 格式
3. 针对你们技术栈和发布流程的额外 checklist 项

这些补充既能保留 requesting-code-review 的轻量特性，又能让它在日常交付里真正变得更好用。