code-review-and-quality

code-review-and-quality Skill 多维度简评

综合评分:8.7 / 10 ⭐⭐⭐⭐⭐ 类别:代码审查 / 协作质量 仓库:obra/superpowers 维护者:Jesse Vincent / Prime Radiant 引用:Superpowers 官方仓库 · CSDN 详解 · 掘金原理解析

一、核心定位与价值

code review 是软件开发最高 ROI 的实践之一,但80% 的 code review 是低效的——开发者把代码扔上去说”review 一下”,没有上下文;reviewer 看不懂就放过或瞎批。

requesting-code-review + receiving-code-review 这对姊妹技能,解决两端:“如何高效请求 review”和”如何专业接收 review 反馈”。

核心原则

请求方:“提供完整上下文,便于审查者理解改动” 接收方:“技术评估而非情绪表演——验证后再实施”

适用场景

• 完成重要功能
• 合并前 milestone
• 重要 bug 修复
• 任何多人协作场景

二、requesting-code-review 完整工作流

2.1 触发条件

Use when completing tasks, implementing major features, or before merging to verify work meets requirements.

翻译:完成任务、实现主要功能、合并前,验证工作是否符合要求。

2.2 PR Description 模板(强制要求)

来源:CSDN: Superpowers 详解

## What Was Implemented
{WHAT_WAS_IMPLEMENTED}
- 一句话描述刚构建的内容
- 关键变更点
- 用户可见的变化

## Plan or Requirements
{PLAN_OR_REQUIREMENTS}
- 链接到 plan 文件或 spec
- 或简述"应该做什么"

## Base SHA
{BASE_SHA}
```bash
git log --oneline | grep "Task X" | head -1 | awk '{print $1}'

Head SHA

{HEAD_SHA}

git rev-parse HEAD

Description

{DESCRIPTION}

• Brief summary of the implementation
• 2-3 段解释为什么这样做
• 关键 trade-off

Testing

• 单元测试通过
• 集成测试通过
• 手动测试过

Risks

• 任何已知风险
• 任何 trade-off
• 任何 follow-up

Screenshots / Demos

(如适用)

### 2.3 集成场景

| 阶段 | 调用频率 |
|---|---|
| **Subagent-driven Development** | **每完成一个任务后**审查,防止问题累积 |
| **Executing Plans** | **每个批次(3 个任务)**完成后审查 |
| **Ad-hoc Development** | 合并前或卡住时审查 |

### 2.4 模板示例

```markdown
## What Was Implemented
实现用户邮箱密码登录功能,后端 FastAPI + JWT,前端 React + httpOnly cookie。

## Plan or Requirements
- Plan: docs/plans/2026-06-15-user-auth.md
- Spec: openspec/changes/add-user-auth/specs/auth.md

## Base SHA
a1b2c3d  Task 1: add users table

## Head SHA
e4f5g6h  Task 15: docs update

## Description
- 选 bcrypt 而非 argon2:Python 生态更成熟,文档多
- 用 httpOnly cookie 而非 localStorage:防 XSS
- JWT 30 分钟过期:平衡安全 + UX

## Testing
- [x] 15 个单元测试
- [x] 3 个集成测试
- [x] 手动测试:register + login + protected page
- [x] 覆盖率 87%

## Risks
- 30 分钟 JWT 过期可能让用户频繁重登——>考虑用 refresh token(下次迭代)
- 没用 rate limiting——>已知问题,不在本 PR 范围

## Screenshots
[登录页截图]
[Dashboard 截图]

三、receiving-code-review 完整工作流

3.1 5 步响应模式

1. **READ (完整阅读)**
   - 不要立刻反应
   - 通读所有反馈

2. **UNDERSTAND (理解重述)**
   - 用自己的话复述
   - 或向 review 者提问

3. **VERIFY (对照现实)**
   - 对照代码库实际状况
   - 不凭印象

4. **EVALUATE (技术评估)**
   - 对 THIS codebase 技术上是否合理?
   - 是否有更好方案?

5. **RESPOND (回应)**
   - 技术性致谢
   - 或要求澄清

3.2 场景处理

来自人类伙伴(Trusted)

# ✅ 直接实施(理解后)
"I understand. Implementing now."

# ✅ 仍要问(范围不清时)
"I see your point about X. Should this also apply to Y, or just X?"

来自外部 reviewer

# ✅ 实施前先验证技术正确性
"Before implementing, let me verify this approach works with our setup."

# ✅ 不合理时反对
"I checked the benchmark. This micro-optimization actually hurts readability
without measurable perf gain. Can we discuss?"

# ✅ 没法验证时
"I don't have access to test this scenario. Can you share the reproduction?"

3.3 反模式:表演性同意

# ❌ WRONG (Performative agreement)
"Great point! You're absolutely right! Will fix immediately!"
# 实际:reviewer 是错的,你也跟着改

# ✅ RIGHT (Technical acknowledgment)
"I see your concern about X. However, in this codebase Y is the case.
Can we discuss whether Z would be a better approach?"

四、与其他 Skill 配合

完整工作流:

[1] 实施代码 (writing-plans → executing-plans)
  ↓
[2] self-verification
  ↓
[3] requesting-code-review(请求审查)
  ↓
[4] 人类 reviewer review
  ↓
[5] receiving-code-review(接收反馈)
  ↓
[6] 5 步响应:Read → Understand → Verify → Evaluate → Respond
  ↓
[7] 修改代码
  ↓
[8] finishing-a-development-branch

五、5 大反模式

5.1 扔代码不写 description

# ❌ BAD
Title: update
Description: (空)

# ✅ GOOD
Title: feat(auth): implement user email login
Description: 完整模板 (见上)

5.2 防御性反应

# ❌ WRONG
Reviewer: "这个函数太长"
作者: "我赶时间"

# ✅ GOOD
Reviewer: "这个函数太长"
作者: "我看了,确实 80 行。可以拆成 validate/process/persist 三个。你看这样 OK 吗?"

5.3 沉默修改不解释

# ❌ WRONG
Reviewer 提 5 个 comment
作者静默改了 3 个,2 个没改,1 个改了一半

# ✅ GOOD
作者回应每个 comment:
- #1 已改 (commit xxx)
- #2 已改 (commit xxx)
- #3 不改,原因: [技术理由]
- #4 改为部分改 [解释]
- #5 后续 issue 跟踪

5.4 review 沦为 nit-pick

# ❌ BAD reviewer
"这个变量名用 user 不好,改成 currentUser 吧"
(无业务影响,纯粹风格)

# ✅ GOOD reviewer
"建议在 user 后加注释,新人看不懂 [reason]"
(有实际价值)

5.5 review 不及时

BAD:PR 提交 3 周才 review GOOD:SLA 24 小时响应,3 天内出 review

六、实战案例:接收 review 反馈

案例 1:reviewer 提了错误建议

Reviewer: "用 Redis 缓存这个用户对象"

你的 5 步:
1. READ: 看完整反馈
2. UNDERSTAND: "建议缓存用户对象,理由是减少 DB 查询"
3. VERIFY: 查监控,发现这个查询 QPS 只有 2,平均耗时 5ms
4. EVALUATE: 缓存价值低,反而增加复杂度
5. RESPOND:
   "看了监控,这个查询 QPS=2,平均 5ms。加 Redis 缓存价值有限
   (节省 5ms,每秒省 2 次查询 = 10ms/秒),但增加运维成本和 stale 数据风险。
   建议保持现状,等 QPS > 100 再考虑。要不要我加个 issue 跟踪?"

案例 2:reviewer 提了模糊建议

Reviewer: "这个设计感觉不够好"

你的 5 步:
1. READ
2. UNDERSTAND: "建议改进设计,但没说具体哪里"
3. VERIFY: 看了代码,觉得当前设计已经 OK
4. EVALUATE: 不确定 reviewer 的具体关注点
5. RESPOND:
   "能具体说说哪里不够好吗?比如:
   - 扩展性?目前接口已支持 3 个 driver
   - 可读性?函数已控制在 30 行内
   - 性能?已 benchmark 过 P99 < 50ms
   还是其他方面?"

案例 3:reviewer 提了 style 建议

Reviewer: "变量名 user_id 用 snake_case,违反我们的 camelCase 规范"

你的 5 步:
1. READ
2. UNDERSTAND: "建议改 camelCase"
3. VERIFY: 查 .editorconfig / .eslintrc,确实规定 camelCase
4. EVALUATE: 工具会自动报错,必须改
5. RESPOND: "确实是疏漏,马上改。已加 lint rule 防止再发生。"

案例 4:reviewer 提了架构重构

Reviewer: "建议把 user_service 拆成 3 个微服务"

你的 5 步:
1. READ
2. UNDERSTAND: "建议微服务化"
3. VERIFY: 看 QPS = 50,DAU = 1000,系统负载 5%
4. EVALUATE: 微服务化成本 >> 当前收益(团队小、流量低、复杂度激增)
5. RESPOND:
   "QPS=50,系统负载 5%,微服务化收益不抵成本(运维 / 部署 / 监控复杂度激增)。
   建议等 DAU > 10 万或团队 > 10 人再考虑。开了 issue #123 跟踪。"

七、5 条反合理化

八、5 条实战技巧

请求方

1. PR description 写满模板:reviewer 5 分钟可读懂
2. diff 控制在 400 行内:超出难 review
3. 截图 / 录屏:UI 改动必附
4. 链接到 plan / spec:reviewer 知道为什么做
5. CI 跑过再求 review:不要让 reviewer 帮你 debug

接收方

1. 24 小时内响应所有 comment
2. 每个 comment 单独回应(commit 链接或解释)
3. 不同意时,带数据反对
4. 修改后 mention reviewer:@reviewer done
5. 复杂讨论拉出 PR:线上讨论难追溯

九、Q&A

Q: 必须用 Claude 吗? A: Skill 是给 Agent 的;人类也适用其中原则。

Q: 多久 review 一次? A: 每 task / 每 batch / 合并前。

Q: reviewer 必须是高级工程师? A: 不,任何团队成员都可。重点是”多双眼睛”。

Q: 多久回复 review 反馈? A: 24 小时内响应(SLA)。

Q: 必须所有 comment 都修吗? A: 不用。技术合理的改;不合理的反对。

Q: 跟 GitHub PR review 区别? A: GitHub 是工具;此 Skill 是”如何高效用工具”。

Q: 中文支持? A: 完美。逻辑与语言无关。

Q: 团队怎么落地? A: 在 CLAUDE.md / 团队规范中明确”所有 PR 必走此流程”。

十、Prompt 模板

模板 1:生成 PR description

我刚完成 user-auth 计划(15 个 task)。
请按 requesting-code-review 模板生成 PR description:
- What Was Implemented
- Plan/Requirements 链接
- Base SHA / Head SHA
- Description(为什么这样做)
- Testing(覆盖情况)
- Risks(已知问题)
- Screenshots(如 UI)

模板 2:接收 review 反馈

我收到以下 review feedback:
[粘贴 comment]

请按 receiving-code-review 5 步法响应:
1. Read 完整读
2. Understand 复述
3. Verify 对照代码
4. Evaluate 技术评估
5. Respond 技术回应

模板 3:self-review

请按 requesting-code-review 模板审查我自己的 diff:
[粘贴 diff]

输出:
- 哪些 issue 别人会提
- 哪些边界没考虑
- 哪些测试缺失
- 哪些文档要补

十一、真实战绩

来源:obra/superpowers 社区统计

十二、与其他工具对比

requesting/receiving-code-review 是这些工具的正确使用方法**——工具替代不了”写好 description”和”技术性回应”。**

十三、安装

# Claude Code
/plugin marketplace add obra/superpowers
/plugin install superpowers@claude-plugins-official

# 通用
npx skills add obra/superpowers --skill requesting-code-review
npx skills add obra/superpowers --skill receiving-code-review

十四、总结

核心价值:

• 标准化 PR description
• 5 步接收反馈法
• 团队协作质量门禁
• 反防御性反应 / 表演性同意

适用人群:

• 所有团队开发者
• Tech Lead
• 跨团队协作
• 开源贡献者

投入产出比:⭐⭐⭐⭐⭐(5/5)—— 团队必装。

何时不要用:

• 1 人独立项目
• 纯聊天
• 临时 hack

参考链接:

• Superpowers 官方仓库
• CSDN: Superpowers Skills 完整探索
• 掘金: Superpowers 原理解析
• chongwenz: 常用命令与场景
• 配套:verification-before-completion | writing-plans | subagent-driven-development