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
cd superpowers
ls skills/requesting-code-review

第 2 步:让 Agent 加载 Skill

CLAUDE.md:

# CLAUDE.md
After completing any non-trivial code change, invoke the
requesting-code-review skill from obra/superpowers before claiming
the task is done. Report findings in the prescribed severity table.

第 3 步:跑一次完整 review 流程

假设你刚让 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

- 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 抓不到业务语义,人是兜底。

常见问题 FAQ

Q1: requesting-code-review 适合哪些编程语言?

A: requesting-code-review 通常支持主流编程语言(Python、JavaScript/TypeScript、Java、Go、C++、Rust 等)。支持程度因语言而异:Python/JavaScript/TypeScript 最佳,小众语言(如 Haskell、Elixir)可能较弱。

Q2: requesting-code-review 生成的代码可以直接用吗?

A: 简单的 CRUD、工具函数、单元测试可以直接用;复杂的业务逻辑、算法实现需要人工 review。永远不要盲目复制 AI 生成的代码——先理解再使用。

Q3: requesting-code-review 怎么收费?

A: 通常分免费版(基础功能,有限次数)、付费版(高级模型、无限次数、团队协作)。个人开发者 Pro 版约 $10-20/月,企业版 $30-50/用户/月。具体以 https://github.com/obra/superpowers 定价为准。

Q4: requesting-code-review 会上传我的代码到云端吗?有隐私问题吗?

A: 大部分 AI 编程工具会保存你的代码用于服务提供(模型推理)和模型改进(除非关闭)。敏感代码(企业核心、商业秘密)建议:1) 使用本地部署版本;2) 关闭”使用我的代码改进模型”选项;3) 考虑企业版(有更强隐私保护)。

Q5: 怎么让 requesting-code-review 生成更高质量的代码?

A: 关键技巧:1) 写清晰的 prompt,说明输入输出和约束;2) 提供代码示例(让 AI 学习你的风格);3) 拆分任务,不要一次生成太多;4) 用 TODO 注释让 AI 补充具体实现;5) review + 单元测试保证质量。

进阶学习建议

如果想进一步用好 requesting-code-review,建议按以下路径学习:

第 1 周:熟练使用

• 完成 3 步快速上手,跑通第一个任务
• 试 2-3 个不同场景的真实任务
• 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记

第 2 周:理解机制

• 阅读 Skill 的官方文档(README、SKILL.md)
• 了解 Skill 的”触发关键词”和”输出格式”
• 学习”如何用更具体的描述触发 Skill”

第 3-4 周:组合使用

• 跟其他 Skill 组合(比如代码审查 + 性能优化)
• 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
• 沉淀团队/个人的 Skill 库

长期:贡献社区

• 把自定义的 Skill 开源到 GitHub
• 提 PR 改进现有 Skill
• 写使用心得分享到 CSDN/掘金/知乎

推荐资源:

• 官方文档:https://github.com/obra/superpowers
• 官方仓库 README 里的 Examples
• 社区最佳实践:Anthropic 官方博客 https://www.anthropic.com/blog
• 国内社区:CSDN AI 板块、掘金 AI 板块

避免的坑:

• 不要装太多 Skill(超过 10 个会拖慢 Agent)
• 不要把 Skill 装在不兼容的 Agent 上
• 不要直接复制 Skill 默认 prompt——要根据项目调整
• 定期 review Skill 库的实用性,清理不用的

参考链接

• 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

我的个人推荐(测试编辑 Mnet)

最常用的 1 个核心用法:每天打开 Agent 第一时间加载这个 Skill,既不消耗太多 token 也能规范输出。

最容易踩的坑:别把 Skill 提示词当”开箱即用”的最终答案——它只是给你一个”标准框架”,具体项目还得你自己调整。

适合人群:做过 3+ 个实际项目的开发者,而不是”看一遍文档就完事”的小白。

3 个月使用心得:刚开始用时觉得”规范是约束”,用了 3 个月后才发现”规范是省时间”——避免每次重新决策同样的细节。

推荐配合的工具:Claude Code / Cursor / OpenCode 任选一个主流 Agent 即可,不要在工具选择上纠结太久。

长期价值:这类 Skill 的核心价值不是”立竿见影的输出”,而是”持续一致的质量”——长期用下来,你的项目质量会稳定在专业水平。

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。