五阶段结构化代码审查

技能文档

---
name: majiayu000-structured-review
title: 五阶段结构化代码审查
description: 按需求符合性、正确性、代码质量、测试、安全与性能五个阶段依次审查代码，输出分级、可执行、有建设性的审查意见，避免泛泛而谈或吹毛求疵。当用户请求代码审查、PR 审查、审查我的改动、检查代码质量、给出评审反馈时触发。触发词：代码审查、评审、PR 审查、code review、review 我的代码、审查改动。
category: 开发工具
---

# 五阶段结构化代码审查

对代码执行结构化的多阶段审查。该方法保证审查覆盖全面，同时输出可落地、有建设性的反馈。

## 技能工作流

### 步骤1：确认审查范围与规模

先确认要审查的改动范围（diff、PR 或指定文件），按规模选择策略：

| 规模 | 预期用时 | 处理方式 |
|------|---------|---------|
| 小（< 100 行） | 10-15 分钟 | 完整走五个阶段 |
| 中（100-300 行） | 20-30 分钟 | 完整走五个阶段 |
| 大（300 行以上） | 45-60 分钟 | 建议先请求拆分 PR 再审查 |

改动过大时，先建议拆分，再开始审查。

### 步骤2：阶段一——需求符合性

首先核实代码是否满足需求。

**需要回答的问题：**
- 是否实现了所要求的功能？
- 验收标准是否全部满足？
- 边界情况是否处理？
- 范围是否合适（既无缺失也无蔓延）？

**检查清单：**
- [ ] 实现了明确的需求
- [ ] 处理了指定的边界情况
- [ ] 没有范围蔓延（夹带了未要求的功能）
- [ ] 没有缺失的功能

**该阶段的反馈示例：**
- "这里似乎没有处理 X 为空的情况"
- "需求要求的是 Y，但这里实现的是 Z"
- "这里加入了未要求的功能 F，是有意为之吗？"

### 步骤3：阶段二——正确性

其次核实代码逻辑是否正确。

**需要回答的问题：**
- 逻辑是否正确？
- 是否存在 bug 或错误？
- 错误分支是否处理？
- 代码是否完整（有无烂尾）？

**检查清单：**
- [ ] 逻辑成立
- [ ] 无明显 bug
- [ ] 错误路径已处理
- [ ] 没有无着落的 TODO（未关联任务的 TODO）

**该阶段的反馈示例：**
- "`user` 为 null 时这里会抛异常"
- "循环提前退出，还有部分元素没处理"
- "API 调用失败时会发生什么？"

### 步骤4：阶段三——代码质量

再次评估代码的可读性与可维护性。

**需要回答的问题：**
- 代码是否易读？
- 是否遵循项目约定？
- 是否足够简洁？
- 是否易于维护？

**检查清单：**
- [ ] 命名清晰
- [ ] 函数/方法长度合理
- [ ] 没有不必要的复杂度
- [ ] 遵循项目既有约定
- [ ] 抽象层次恰当

**该阶段的反馈示例：**
- "能否把 `data` 改名为 `userProfile`，语义更清晰？"
- "这个函数做了三件事，建议拆分"
- "本项目的变量命名使用 camelCase"

### 步骤5：阶段四——测试

评估测试覆盖与测试质量。

**需要回答的问题：**
- 测试覆盖是否充分？
- 测试是否验证了该验证的东西？
- 测试是否易维护？

**检查清单：**
- [ ] 新增代码有测试
- [ ] 测试覆盖主路径与边界情况
- [ ] 测试可读、可维护
- [ ] 测试没有绑定实现细节

**该阶段的反馈示例：**
- "请为错误分支补一个测试"
- "改动实现方式的话这个测试就会挂"
- "这几组用例建议改成参数化测试"

### 步骤6：阶段五——安全与性能

最后检查安全与性能隐患。

**需要回答的问题：**
- 是否存在安全漏洞？
- 是否存在性能问题？
- 数据处理是否得当？

**检查清单：**
- [ ] 无 SQL 注入、XSS 等漏洞
- [ ] 密钥等敏感信息未泄露
- [ ] 无明显的 N+1 查询
- [ ] 无多余计算
- [ ] 敏感数据处理方式正确

**该阶段的反馈示例：**
- "该输入在使用前应做清洗"
- "这个查询建议加索引"
- "这个 API Key 应改从环境变量读取"

### 步骤7：汇总输出审查报告

五个阶段完成后，按分级汇总输出一份审查报告。

**意见分级：**

| 级别 | 适用场景 | 示例 |
|------|---------|------|
| **Blocker（阻塞）** | 合并前必须修复 | "安全问题：这里存在 SQL 注入" |
| **Major（重要）** | 应当修复，但非阻塞 | "空数组输入时这里会失败" |
| **Minor（次要）** | 建议，可选优化 | "建议改名以增强可读性" |
| **Nit（琐碎）** | 细节、风格问题 | "这里多了一个空行" |

**建设性反馈模板：**

```
[级别] [类别]: [问题]

**是什么：** [描述具体问题]
**为什么：** [解释为什么重要]
**建议：** [给出具体的改进方式]
```

示例：

```
[Major] 正确性: 可能出现空引用

**是什么：** `user.email` 在未判断 user 是否存在的情况下直接访问
**为什么：** user 不存在时会抛 TypeError
**建议：** 在访问属性前加上 `if (!user) return null;`
```

**报告末尾给出结论：** 通过（Approve）/ 需修改（Request Changes）/ 仅评论（Comment）。

## 反馈的写法

### 反面模式（不要这样写）

- "这是错的"（不可执行）
- "我会换一种写法"（不给理由）
- "你为什么没有……？"（带指责感）
- 对个人偏好吹毛求疵（约定之外的偏好）

### 正面做法

- 具体指出问题所在
- 说明问题的影响
- 给出解决方案或替代方案
- 通过提问理解作者意图

## 回应审查意见

收到审查意见时按以下顺序处理：

1. **确认** —— 表明已阅读并理解该意见
2. **澄清** —— 有疑问时先提问
3. **处理** —— 修改代码，或解释为何不修改
4. **解决** —— 处理完后标记为已解决

不同意审查意见时，可以建设性地表达：

```
关于 [X] 我理解你的顾虑。这次我选择 [Y]，原因是 [理由]。
你希望进一步讨论，还是这个做法可以接受？
```

## 审查报告模板

```markdown
## 审查：[PR 标题]

### 阶段一：需求
- [ ] 实现了需求
- [ ] 处理了边界情况
- [ ] 范围合适

### 阶段二：正确性
- [ ] 逻辑成立
- [ ] 无 bug
- [ ] 错误已处理

### 阶段三：质量
- [ ] 可读
- [ ] 遵循约定
- [ ] 可维护

### 阶段四：测试
- [ ] 有测试
- [ ] 测试质量合格

### 阶段五：安全/性能
- [ ] 无漏洞
- [ ] 无性能问题

### 结论：[ ] 通过 [ ] 需修改 [ ] 仅评论
```

使用说明

# 五阶段结构化代码审查

按「需求 → 正确性 → 质量 → 测试 → 安全性能」五个阶段审查代码，输出分级（Blocker/Major/Minor/Nit）、可执行、有建设性的评审意见。

## 适用场景

- 审查 PR / diff / 指定文件的改动
- 需要一份结构化的审查报告而非零散点评
- 希望评审意见可落地（问题 + 影响 + 建议）

## 使用方式

对 AI 助手说：

```text
帮我审查这段改动，按五阶段结构化审查输出报告
审查一下这个 PR
review 我的代码，给出分级反馈
```

## 输出内容

- 每个阶段的检查清单勾选结果
- 按级别分类的问题清单（是什么 / 为什么 / 建议）
- 末尾结论：通过 / 需修改 / 仅评论

## 注意事项

- 改动超过 300 行时建议先拆分 PR 再审查
- 意见分级中仅 Blocker 视为合并前必须修复项

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。