izittmarvin/xnova-studio/code-review

代码审查

概述

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

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

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

铁律

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

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

何时使用

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

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

特别是当：

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

不要跳过审查：

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

三个阶段

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

阶段一：理解上下文

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

1. 确定范围和意图

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

1. 阅读周边代码

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

1. 检查 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 秒）
• "跳过安全检查吧，这又不是那种代码"
• "文件太多了，扫一眼就行"
• "测试过了，所以肯定没问题"
• "只看看命名和格式就好了"
• "不需要看周边代码"

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

常见自我合理化

速查表

支撑资源

本目录下可用的资源：

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

实际效果

代码审查研究数据：

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