requesting-code-review

requesting-code-review 快速入门

让 AI 提交代码后主动喊“我需要 review”——这个 Skill 用 3 步让 Agent 学会自检 + 主动请审。

这是什么?解决什么问题?

requesting-code-review 是 obra/superpowers 项目下的代码审查流程 Skill,关注的是 “谁来发起 review” 这个常被忽略的环节。
通常团队的 code review 是由人发起的——开发者 push 代码,开 PR,@ 同事。但在 AI 协作开发场景下,Agent 写完一段代码后往往不会主动停下来说“请帮我 review 一下”,而是继续往下做,导致质量问题被掩盖。
requesting-code-review Skill 反过来要求 Agent 主动触发 review,其核心理念来自 obra/superpowers 的 Plan-Compliance 思想:

1. 任务完成 ≠ 工作完成,还要对照原始计划做“计划符合性检查”;
   
2. 严重性分级:blocker / critical / major / minor / nit,blocker 必须先解决;
   
3. 关键问题可阻断:遇到 blocker / critical,Agent 必须停下,等用户确认;
   
4. 报告结构化:每条问题带文件:行号、原因、建议、改动示例。
   适合使用 Claude Code / Cursor / Aider 等 Agent 工具开发的工程师、Tech Lead,以及想给团队立“AI 协作代码审查规范”的人。
   

准备工作

1. AI 编程 Agent:Claude Code 最完整,Cursor 次之。
   
2. Git 仓库:Skill 会用 git diff 评估变更。
   
3. Node.js ≥ 18:可选,Agent 自己会跑命令。
   
4. 项目原始 plan / spec:Skill 强调要先有 plan 才能 review,没有 plan 的话,先写一份。
   

3 步快速上手

第 1 步:克隆 superpowers 仓库

git clone https://github.com/obra/superpowers.git<br>
cd superpowers<br>
ls skills/requesting-code-review<br>
```<br>
### 第 2 步:让 Agent 加载 Skill<br>
`CLAUDE.md`:<br>
```markdown<br>
# CLAUDE.md<br>
After completing any non-trivial code change, invoke the<br>
requesting-code-review skill from obra/superpowers before claiming<br>
the task is done. Report findings in the prescribed severity table.<br>
```<br>
### 第 3 步:跑一次完整 review 流程<br>
假设你刚让 Agent 实现了一个新功能:
> Agent,你刚才完成了“订单导出 CSV”功能,请按 requesting-code-review Skill 跑一次自检 + 请求 review。

Agent 会:

1. 调 `git status` / `git diff` 看到本次变更涉及哪些文件;

2. 调出原始 plan / spec(本项目是 `docs/order-export.md`);

3. 逐条对照 plan 检查实现是否完整;

4. 按严重性输出报告:

Review Report — order export CSV

Blocker

(none)

Critical

• src/services/OrderExportService.java:88

未实现 plan 中要求的“按时间区间过滤”,目前导出全表。

Fix: 在 SQL 中加 created_at BETWEEN ? AND ?,并接 controller 参数。

Major

• src/services/OrderExportService.java:120

导出 100 万行时未分页,容易 OOM。Plan 要求 batch size 1000。

Fix: 用 Stream + JDBC fetchSize 分批。

Minor

• src/main/resources/application.yml:15

CSV 编码未配置,中文会乱码。建议加 spring.servlet.encoding.charset=UTF-8。

## 常见踩坑

1. **没有 plan / spec**:Skill 强调没有 plan 就不存在 plan-compliance,review 会流于形式。建议每个 feature 先有 `docs/<feature>.md`。

2. **报告没有 file:行号**:Skill 强制要求 `path:line` 格式,否则 review 完没法落实。

3. **把 nit 标成 critical**:会让 reviewer 疲劳。Skill 提供 `severity 决策表`,例如“拼写错误 = nit,空指针风险 = critical”。

4. **blocker 没真正阻断流程**:有些 Agent 写完 review 报告就接着跑下一个任务,违反 Skill 规则。CLAUDE.md 里要写明“blocker 不解除则停止”。

5. **跳过 positive feedback**:Skill 提示也要报告“做得好的部分”,但很多人忘了加。

6. **没区分人类 review 与 AI 自检**:AI 自检可能漏掉 UX / 业务语义,Skill 建议最后必须有一次人类 review。

## 初级用法

**1. 单文件改动**

> 我刚把 `user.service.ts` 改了一下,请用 requesting-code-review Skill 走一遍 review。

**2. 一次完整 PR**

> 我要提一个 PR 包含 `auth/login.ts`、`auth/jwt.ts`、`tests/auth.test.ts` 三个文件,请帮我做一次完整 review。

**3. 对照原 issue**

> 这是 #142 修复,需求在 `docs/issues/142.md`,请用 Skill 做 plan-compliance 检查。

## 高级玩法

**1. CI 集成自动 review**

```yaml

- name: AI Code Review

run: |

claude --skill requesting-code-review --diff origin/main..HEAD > review.md

gh pr comment --body-file review.md

2. 团队共享 review 模板

把 Skill 的 severity 决策表抽到 .review-config.yml,团队所有项目共享。

3. 跟 git-hook 配合

# .git/hooks/post-commit

claude --skill requesting-code-review --last-commit

每次 commit 自动跑一次自检。

4. 与 receiving-code-review 联动

别人给你的 review 反馈,用 obra 的另一个 receiving-code-review Skill 处理回复节奏,形成完整闭环。

小技巧

• 每次 review 前先看 plan:没 plan 不 review。

• severity 用全大写:BLOCKER / CRITICAL / MAJOR / MINOR / NIT,易于 grep。

• 报告模板化:用 Markdown 表格,贴 PR 评论更易读。

• review 完别忘了 +1 commit:Agent 修复 blocker 后要明确标“fixed in ”,方便追溯。

• 人类最后过一遍:AI review 抓不到业务语义,人是兜底。

参考链接

• obra/superpowers 仓库:https://github.com/obra/superpowers

• requesting-code-review 子目录:https://github.com/obra/superpowers/tree/main/skills/requesting-code-review

• 配套的 receiving-code-review:https://github.com/obra/superpowers/tree/main/skills/receiving-code-review

• 配套的 verification-before-completion:https://github.com/obra/superpowers/tree/main/skills/verification-before-completion

• Conventional Comments(类似严重性分级思路):https://conventionalcomments.org/

• GitHub PR 审查最佳实践:https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests

• Claude Code 官方文档:https://docs.claude.com/en/docs/claude-code/overview

• Anthropic Skills 总览:https://github.com/anthropics/skills