SuperAPI AI 工具集

five-axis-code-review

编程与开发

查看项目

更新于 10-20 02:32

技能介绍

用途

Five-axis code review 是一个代码审查清单技能,用于回答一个核心问题:「这段代码会不会在三个月内变成别人的麻烦?」它按五个轴依次走查,每个轴给出通过 / 不通过 / 不适用,每个不通过项都必须附带具体修复方案。

适用场景:用户要求审查代码、diff 或 pull request;希望审查保持可执行、跳过风格挑刺。

主要能力

按优先级顺序逐轴检查:

  1. 正确性:边界情况(null、空、零、负数、超大值)、并发/时序假设、错误处理(异常是否被吞掉)。这是唯一可以阻止合并的轴。
  2. 安全:用户输入是否被拼接进 SQL / shell 命令 / HTML;密钥或令牌是否硬编码;日志是否泄露敏感数据。
  3. 可读性:命名是否说明事物是什么;每个函数是否只做一件事;魔法数字是否已命名。只标记看不懂的地方,而不是「我会换个写法」。
  4. 性能:循环内重复查询或重复计算;N+1 问题;可避免的大对象拷贝。不做无数据的性能猜测(「这可能会变慢」不算评论)。
  5. 测试覆盖:新逻辑是否有测试;边界情况是否有用例。测试全绿但关键路径未覆盖,仍应退回。

使用方式

工作流:

  • 先检查范围:看 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 项:问题多到列不完时,正确做法是「重写后再提交」,而不是当老师。