code-review

代码评审诊断

系统性的代码评审可在代码上线前发现 60%–90% 的缺陷，将维护成本降低 40%，并有效传递知识。本技能为人工评审者和 AI Agent 提供结构化的评审指南。

何时使用本技能

在以下情况下使用本技能：

• 合并前评审代码
• 评估代码质量
• 准备提交 PR
• 在请求评审前进行自我评审

以下情况请勿使用本技能：

• 编写新代码（使用实现类技能）
• 设计架构（使用 system-design）
• 处理需求（使用 requirements-analysis）

核心原则

PR 越大，评审效果下降得越明显。 少于 400 行：缺陷检测效果最佳。400–800 行：效果降低 50%。超过 800 行：效果降低 90%。

快速参考：评审效果

因素	最佳	效果下降
PR 大小	< 400 行	> 800 行
评审时长	< 60 分钟	> 90 分钟
评审速度	200–400 LOC/小时	> 500 LOC/小时
评审者人数	2	4+（收益递减）

质量金字塔

层级	检查项	可发现的问题	频率
1. 自动化	Lint、类型、单元测试、安全扫描	60%	每次提交
2. 集成	集成测试、契约、性能	25%	每个 PR
3. 人工评审	设计、逻辑、可维护性、上下文	15%	重大变更

评审重点领域

1. 正确性

问题：

• 是否解决了所述问题？
• 是否处理了边界情况？
• 错误处理是否完整？
• 假设是否成立？

验证： 测试覆盖率、业务逻辑、数据完整性、并发处理

2. 可维护性

问题：

• 代码是否具有自解释性？
• 是否易于修改？
• 抽象是否恰当？
• 复杂度是否合理？

指标： 命名清晰、单一职责、耦合度低、内聚度高

3. 性能

问题：

• 是否存在明显的性能瓶颈？
• 缓存是否使用得当？
• 查询是否经过优化？
• 内存是否得到妥善管理？

警示信号： N+1 查询、无界循环、异步上下文中的同步 I/O、内存泄漏

4. 安全性

问题：

• 是否验证了输入？
• 是否保护了机密信息？
• 是否检查了身份验证？
• 是否验证了权限？

关键检查项： 不硬编码机密信息、使用参数化 SQL、防止 XSS、使用 CSRF 令牌

代码异味检查清单

方法级别

异味	阈值	操作
方法过长	> 50 行	提取方法
参数列表过长	> 5 个参数	使用参数对象
代码重复	> 10 行相似代码	提取共用代码
死代码	从未调用	移除

类级别

异味	症状	操作
上帝类	> 1000 行、> 20 个方法	拆分类
特性依恋	过度使用其他类的数据	移动方法
数据团	参数组相同	提取类

架构级别

异味	检测方式	操作
循环依赖	依赖环	引入接口
不稳定依赖	依赖易变模块	依赖倒置

评论指南

评论类型

[BLOCKING] - 合并前必须修复

• 安全漏洞、数据损坏风险、破坏性 API 变更

[MAJOR] - 应在合并前修复

• 缺少测试、性能问题、代码重复

[MINOR] - 可在后续跟进中修复

• 风格不一致、文档错别字、命名改进

[QUESTION] - 请求澄清

• 设计决策、业务逻辑、外部依赖

有效评论模式

Observation + Impact + Suggestion

Example:
"This method is 200 lines long [observation].
This makes it hard to understand and test [impact].
Consider extracting helper methods [suggestion]."

避免

• 含糊不清：“这里可以做得更好”
• 针对个人：“我不喜欢这样”
• 吹毛求疵：“注释末尾缺少句号”
• 令人应接不暇：50 条以上细微的风格问题

评审就绪检查清单

请求审查前

• 功能已完整实现
• 已编写并通过所有测试
• 已完成自我审查
• 没有注释掉的代码或调试语句
• 达到覆盖率阈值
• 通过 Lint 检查
• 构建成功
• 已更新文档
• PR 描述说明了问题和解决方案

PR 描述应包括

• 问题陈述（为什么要进行此更改？）
• 解决方案（如何解决问题？）
• 测试策略（如何验证？）
• 破坏性更改（如有）
• 审查重点（需要重点关注哪些地方？）

复杂度阈值

圈复杂度

范围	分类	操作
1-10	简单	可以接受
11-20	中等	考虑重构
21-50	复杂	必须重构
> 50	无法测试	必须拆分

认知复杂度

范围	分类
< 7	清晰
7-15	可接受
> 15	令人困惑——需要重构

反模式

盖章式批准

未经彻底审查就批准。在不到 1 分钟内回复“LGTM”。 解决方法： 设定最低审查时长，要求发表评论，并进行随机审计。

吹毛求疵

留下 50 条以上风格方面的评论，却忽略真正的问题。 解决方法： 自动化风格检查，关注逻辑和设计，限制次要评论。

大爆炸式审查

2000 行以上的 PR 让人应接不暇。 解决方法： 将小型 PR 依次叠加，使用功能标志，尽早审查草稿。

安全扫描类别

严重性分类

级别	定义	SLA
严重	可能导致远程代码执行	立即修复
高	可能发生数据泄露	24 小时内修复
中	影响有限	在当前迭代中修复
低	风险极低	方便时修复

审查指标

效率

指标	目标
首次审查响应时间	< 4 小时
审查轮次	< 3
PR 到合并的耗时	< 24 小时

质量

指标	目标
缺陷检出率	> 80%
合并后缺陷数	每个 PR < 0.5
审查覆盖率	100%

相关技能

• github-agile - PR 工作流和 GitHub 集成
• task-decomposition - 如果 PR 太大，将其拆分
• requirements-analysis - 用于需求不明确的情况