用途
Five-axis code review 是一个代码审查清单技能,用于回答一个核心问题:「这段代码会不会在三个月内变成别人的麻烦?」它按五个轴依次走查,每个轴给出通过 / 不通过 / 不适用,每个不通过项都必须附带具体修复方案。
适用场景:用户要求审查代码、diff 或 pull request;希望审查保持可执行、跳过风格挑刺。
主要能力
按优先级顺序逐轴检查:
- 正确性:边界情况(null、空、零、负数、超大值)、并发/时序假设、错误处理(异常是否被吞掉)。这是唯一可以阻止合并的轴。
- 安全:用户输入是否被拼接进 SQL / shell 命令 / HTML;密钥或令牌是否硬编码;日志是否泄露敏感数据。
- 可读性:命名是否说明事物是什么;每个函数是否只做一件事;魔法数字是否已命名。只标记看不懂的地方,而不是「我会换个写法」。
- 性能:循环内重复查询或重复计算;N+1 问题;可避免的大对象拷贝。不做无数据的性能猜测(「这可能会变慢」不算评论)。
- 测试覆盖:新逻辑是否有测试;边界情况是否有用例。测试全绿但关键路径未覆盖,仍应退回。
使用方式
工作流:
- 先检查范围:看 diff 大小。超过约 400 行改动,先要求拆分再审查——超大 diff 的审查质量必然崩塌。
- 逐轴检查(顺序即优先级)。
- 撰写评论:固定格式
[轴] 文件:行 问题 → 建议修复。只写可执行建议;「可以优化」不算建议。 - 分诊:必须修复(正确性 / 安全)与建议修复(可读性 / 性能 / 测试)。「建议修复」不阻止合并,但需明确说明。
规则:
- 每次审查最多 10 条评论。超过说明代码问题太多——退回重写,而不是逐条打分 50 项。
- 不做风格管制:缩进、引号、分号是 linter 的职责,不是人的。
- 评论必须与 diff 对话:每条评论都要引用具体代码行。没有代码引用的评论无效。
最小可执行清单:
## Code review checklist
- [ ] Correctness: edge cases (null/0/negative/oversized) handled, exceptions not swallowed
- [ ] Correctness: concurrency/timing assumptions hold, no races
- [ ] Security: no SQL/shell/HTML injection points, no hard-coded secrets, no sensitive data in logs
- [ ] Readability: names are descriptive, functions have a single responsibility, no magic numbers
- [ ] Performance: no repeated queries/computation in loops, no N+1, no evidence-free performance worries
- [ ] Tests: new logic is covered, edge cases have cases
- [ ] Scope: diff ≤ ~400 lines, otherwise split first
示例评论:
[Must fix][Correctness] order.py:87 empty order list triggers IndexError → guard for empty before taking [0]
[Should fix][Readability] order.py:92 magic number 86400 → name it SECONDS_PER_DAY
适用场景
- 审查代码、diff 或 pull request。
- 需要可执行、跳过风格挑刺的审查。
限制
- 只覆盖五个审查轴,并非所有质量维度。领域特定的正确性(金融舍入、协议一致性、无障碍一致性)仍需专门审查。
- 五个轴是给人审查者用的启发式方法。清单全部通过并不证明改动正确、安全或高性能。
- 这里的安全审查是阅读清单,不是扫描器。静态分析、依赖审计和密钥扫描需作为独立工具运行。
- 该技能审查 diff,无法确认需求是否被满足;空发现列表只意味着在审查范围内没有有证据的发现。
反模式
- ❌ 顺手 LGTM:没读完整个 diff 就批准——审查成了表演。
- ❌ 风格警察:20 条评论里 18 条讲引号和换行,却漏掉一个空指针解引用。
- ❌ 没有代码的评论:「这段逻辑看起来不对」——哪段逻辑?哪一行?没说即无效。
- ❌ 性能猜测:「这个循环在规模大时可能很慢」——没有数据的性能评论是噪音。
- ❌ 打分 50 项:问题多到列不完时,正确做法是「重写后再提交」,而不是当老师。