code-review

name	code-review
description	Use when the user asks to review code, check for issues, or says "review", "审查", "检查代码"
user-invocable	true

代码审查

概述

按优先级结构化审查代码。聚焦真实问题 — 正确性、安全性、可维护性，而不是风格吹毛求疵。

核心原则： 审查优先级：Bug > 安全 > 性能 > 可读性 > 风格。

违反优先级顺序就是违反代码审查的精神。

铁律

在验证正确性和安全性之前，不得评论代码风格

如果你还没有检查 Bug 和安全问题，就不应该评论命名和格式。

何时使用

适用于任何代码审查场景：

• 审查 diff、文件或 PR
• 用户说 "review"、"审查"、"检查代码"、"看看有没有问题"
• 合并或提交重要变更之前
• 完成功能开发或修复之后

特别是当：

• 变更涉及安全敏感代码（认证、输入处理、加密）
• 变更跨多个文件或模块
• 你对该代码区域不熟悉

不要跳过审查：

• "只是一个小改动"（小改动也能引入大 Bug）
• "是我自己写的"（自审也能发现问题）
• "只是重构"（重构可能改变行为）

三个阶段

必须按顺序完成每个阶段。

阶段一：理解上下文

在查看任何代码细节之前：

1. 确定范围和意图

   • 哪些文件改了？PR/提交的目的是什么？
   • 运行本目录下的 quick-review.sh 快速查看 diff 概况
   • 这个改动在解决什么问题？

2. 阅读周边代码

   • 不要孤立地审查 — 阅读上下文
   • 理解模块的职责
   • 检查代码库中的现有模式

3. 检查 diff 大小

   • < 200 行：内联审查
   • 200-500 行：逐文件审查

   • 500 行：建议拆分 PR

阶段二：按优先级检查清单

严格按顺序逐项检查：

完整清单见 checklist.md，简要版本：

1. 正确性（严重）— 逻辑错误、空值安全、边界情况、异常处理
2. 安全性（严重）— 注入、密钥泄露、权限控制、依赖漏洞
3. 性能（警告）— N+1 查询、内存泄漏、未清理资源
4. 可维护性（建议）— 命名、复杂度、DRY 原则、注释

各语言常见反模式详见 common-issues.md（TypeScript、Java、Python）。

阶段三：结构化输出

按严重性分组，而非按文件分组：

## 代码审查: <范围>

### 严重（必须修复）
- [Bug] <文件:行号> — 描述 + 修复建议
- [安全] <文件:行号> — 描述 + 修复建议

### 警告（建议修复）
- [性能] <文件:行号> — 描述 + 建议
- [异常] <文件:行号> — 描述 + 建议

### 建议（可以改进）
- [风格] <文件:行号> — 描述
- [DRY] <文件:行号> — 描述

### 亮点
- <值得肯定的好模式>

### 总结
<1-2 句话: 整体评价，通过/需要修改>

规则：

• 必须包含 亮点 — 肯定做得好的地方
• 每个严重性级别限制 3-5 条可操作项
• 每条发现必须包含 文件:行号 和 修复建议
• 总结必须给出明确的 通过 / 需要修改 结论

红旗信号 — 停下来重新审视

如果你发现自己在想：

• "看起来没问题"（才看了不到 30 秒）
• "跳过安全检查吧，这又不是那种代码"
• "文件太多了，扫一眼就行"
• "测试过了，所以肯定没问题"
• "只看看命名和格式就好了"
• "不需要看周边代码"

以上任何一条都意味着：停下来。回到阶段一。

常见自我合理化

借口	现实
"测试过了，所以是对的"	测试也有盲区。独立审查逻辑。
"只是风格问题"	如果你只发现了风格问题，说明你没认真看。
"文件太多审不完"	让作者拆 PR。不要囫囵吞枣。
"我信任这个开发者"	信任不能替代审查。看代码。
"只是日志/注释"	日志可能泄露密钥。注释可能误导。
"没时间仔细审查"	敷衍审查 = 漏掉 Bug = 以后花更多时间修。

速查表

阶段	核心活动	完成标准
1. 上下文	读范围、周边代码、diff 大小	理解意图
2. 检查清单	正确性 → 安全 → 性能 → 可维护性	所有类别已检查
3. 输出	按严重性分组的结构化报告	给出明确结论

支撑资源

本目录下可用的资源：

• checklist.md — 按优先级组织的完整审查清单
• common-issues.md — 按语言分类的常见反模式（TypeScript、Java、Python）
• quick-review.sh — 快速 diff 分析脚本（文件统计、风险检测）

实际效果

代码审查研究数据：

• 结构化审查比即兴审查多发现 2-3 倍 Bug
• 安全优先审查能预防 60% 的漏洞引入
• 使用清单审查可减少 30% 审查时间（减少来回）