SuperAPI AI 工具集

low-level-code-review

编程与开发

查看项目

更新于 10-16 06:39

技能介绍

用途

该技能用于对 git diff 执行低层级代码审查,寻找小范围、局部性的编码错误。这类错误无需对代码库有高层理解即可识别和修复,属于在任何代码库、任何语言中都可能出现的纯机械性问题。

对于较大的 diff,建议将审查拆分为多个部分,每部分作为子代理运行(例如每个文件或目录一个子代理)。保持每个子代理专注于适量工作,避免迷失或偏离方向。

输出是一份待修复问题的工作清单。

输入

开始审查前,需收集以下信息(若作为子代理运行,由调用代理提供;否则自行确定或询问用户):

  • Git 范围:确定要审查哪个 diff:
    • 检查是否有未提交的更改(git diff 和 git diff --cached)
    • 若无未提交更改,检查当前分支是否与 master 不同
    • 若两者均不适用,向用户询问具体的 git 范围
  • 变更上下文(可选但有帮助):若已知,简要描述该变更的意图。

若作为子代理调用,提示中应包含:“Review the diff from <git-command>.”

获取 Diff

运行调用代理提供的 git diff 命令获取 diff,然后进行分析。

需查找的问题

仅关注明确是错误且可自信修复的问题。不要标记任何需要理解更广泛系统设计的内容。

确定的 Bug

  • 数值溢出/下溢:对整数类型的操作可能超出其边界(例如将两个接近最大值的 uint32_t 相加)。
  • 差一错误:循环边界、数组索引、范围计算。
  • 空/nullptr 解引用风险:在未检查指针是否可能为空的情况下解引用,尤其是在可能返回空的操作之后。
  • 未初始化变量:变量在赋值前被使用。
  • 资源泄漏:内存、文件句柄或其他资源被获取但在所有代码路径上未释放。
  • 释放/移动后使用:在资源被释放或移动后使用。
  • 双重释放:两次释放或删除同一资源。
  • 布尔逻辑错误:运算符优先级错误、德摩根定律错误、条件反转。
  • 字符串格式化不匹配:格式说明符与参数类型不匹配(例如对 size_t 使用 %d)。

ACID 语义违规(磁盘)

  • 查找写临时文件 + 重命名模式
  • 验证临时文件在重命名前已 fsync
  • 验证目录在重命名后已 fsync
  • 检查:若在步骤之间发生崩溃会怎样?

需问的问题:

  • 若操作中途断电,磁盘上是什么状态?
  • 崩溃后操作能否恢复/重试?
  • 文件写入之间是否存在顺序依赖?

ACID 语义违规(内存)

  • 查找可能因中断而使系统处于不一致状态的非原子状态更改
  • 检查共享状态周围是否有适当的锁定
  • 检查是否有适当的错误处理来回滚或补偿部分失败

需问的问题:

  • 若操作中途抛出异常或发生错误,系统是否可能处于不一致状态?
  • 状态更改是原子进行的,还是可能被中断而留下部分更新?
  • 是否有任何临界区缺少适当的锁定?

可能的失误

  • 复制粘贴错误:重复的代码块存在细微不一致,暗示复制粘贴时未更新某些内容。
  • 标识符拼写错误:变量或函数名几乎正确但不完全正确(尤其是在模仿现有模式的新代码中)。
  • 使用了错误的变量:误用了名称相似的变量。
  • switch 缺少 break:看似无意的贯穿。
  • 比较代替赋值(或反之):if (x = y) 与 if (x == y)。
  • 有符号/无符号比较:以可能产生意外结果的方式比较有符号和无符号整数。
  • 使用裸指针:应使用智能指针、optional 或引用。
  • 手动清理路径:应使用 RAII 守卫。
  • 常见 C++ 标准库误用:为任务使用了错误的容器、算法或工具函数,错误地调用容器方法或构造函数,引入已知的未定义行为,性能反模式等。

风格问题(仅在明显错误时)

  • 注释中的拼写错误:注释或文档中的单词拼写错误。
  • 命名不一致:新代码未遵循紧邻周围代码的命名模式。
  • 缺少 const:参数或变量明显可以是 const 但不是。
  • 未使用的变量:声明但从未使用的变量。
  • 未使用的 include:包含了头文件但变更代码中未使用其中任何内容。
  • 死代码:永远无法执行的代码(无条件 return 之后等)。
  • West const:const 应放在常量对象的右侧(“east const”)。
  • 旧惯用法:我们使用 C++20,因此应适当倾向于有助于正确性和清晰度的特性。

输出格式

生成结构化的工作清单作为输出。每项应包含:

  • 文件路径和行号(来自 diff)
  • 问题类型(来自上述类别)
  • 原始代码(确切的问题代码)
  • 建议修复(要做的具体编辑)
  • 简要说明(为何这是问题,一句话)

按文件分组问题。示例格式:

src/foo/Bar.cpp

Line 142: Numeric overflow risk

Original: uint32_t total = count1 + count2; Fix: uint64_t total = static_cast<uint64_t>(count1) + count2; Why: Both operands are uint32_t and their sum could exceed UINT32_MAX.

Line 287: Typo in comment

Original: // Calcualte the checksum Fix: // Calculate the checksum Why: Misspelled "Calculate".

始终

  • 始终引用 diff 中的确切行号
  • 始终原样引用原始代码
  • 始终提供具体、明确的修复(不只是“修复这个”)
  • 始终用一句话解释为何是问题
  • 始终仅关注 diff 中变更的行(以 + 开头的行)
  • 始终按文件分组问题以便处理
  • 始终在报告前考虑问题是否可能是有意为之
  • 始终优先处理潜在运行时错误而非风格问题
  • 始终在报告前检查同一函数中是否已在更早处检查了正确性条件
  • 始终验证问题存在于新代码中,而不仅仅是被删除的代码中

绝不

  • 绝不更改超出最小修复所需的逻辑或行为
  • 绝不建议重构、重新设计或架构更改
  • 绝不标记需要理解更广泛代码库或系统设计的问题
  • 绝不报告与周围代码无明显不一致的风格偏好
  • 绝不对 diff 中未修改的行建议更改
  • 绝不对模糊情况假设程序员意图
  • 绝不报告同一机械性问题超过 3 次;改为注明“以及本文件中 N 处类似情况”
  • 绝不标记有意为之的模式(例如不要将 if (auto* p = getPtr()) 标记为“条件中赋值”)
  • 绝不报告测试代码中明显有意的问题(例如测试错误路径)
  • 绝不花时间在编译器警告能捕获的问题上(假设构建已启用警告)

完成

按如下方式总结工作:

  • 呈现发现的问题工作清单
  • 若未发现问题,明确报告:“No low-level issues found in the diff.”
  • 若 diff 非常大(超过约 500 行新增),建议按文件或目录拆分审查以确保彻底性
  • 若作为子代理调用,将此总结传回调用代理。