SuperAPI AI 工具集

reviewing-code

编程与开发

查看项目

更新于 10-28 15:10

技能介绍

用途 这是一个面向代码评审的技能,为调用方提供可执行的第二意见:判断变更是否完成它要做的事、哪些问题应当阻止合入、每个阻塞项的最小修复是什么。评审结论本身就是交付物,技能不修改代码。

主要能力

  1. 先固定评审对象:可评审当前改动、某分支、最近一次提交或最近历史,也可评审设计或计划。使用 git diff 查看工作区,git diff --cached 查看暂存区,git diff <base>...HEAD 查看分支;记录 HEAD SHA,避免后续提交改变评审范围。对提交历史先用 git show --stat 和 git show,或使用范围较窄的 git log。评审设计时先读计划,再读它将触及的代码。
  2. 明确意图:用一行说明变更服务的用户问题、缺陷、迁移或决策。简报给出则采用,否则从 diff、提交信息和测试推断并标注为推断。
  3. 先读后判:不评论未读过的代码。读 diff 后,读足够的周边文件以理解每条变更调用链,包括调用方、跨越的类型、覆盖它的测试以及应匹配的本地模式。可把独立命令合并到一次 shell_command 调用中,如 git diff --stat && git diff -- src/foo.ts && rg "pattern" src。外部事实查源头:读项目使用的库版本,而不是凭记忆;读服务端代码,而不是从客户端猜测。
  4. 以怀疑者视角尝试打破变更:构造它可能未处理的输入、状态、顺序、失败、重试和并发调用者,逐条追踪;检查被吞掉的错误路径;判断它是否修复根因而非症状;对每个新分支、选项、包装或抽象追问其必要性,寻找能删除它而保持行为的更简单方案。
  5. 从两个维度评审并分开报告:意图(是否完整解决所述问题、是否破坏调用方依赖的行为,重点关注持久化、权限、安全、并发、重试、缓存、迁移、公共 API、计费、数据丢失和客户端-服务端契约)与规范(是否符合代码库约定、错误处理、命名、文件位置和类型;TypeScript 中关注 any、类型断言、非空断言和隐藏不变量的可选字段;依据仓库规则时引用该规则)。
  6. 严格定义什么算问题:只报告本次变更引入、作者看到后会修复的问题,并说明触发输入或情境及受影响代码。变更前已存在的问题最多列为后续项;diff 与测试显示是刻意权衡的选择记为规范说明而非缺陷。清晰缺陷或安全漏洞即使触发罕见也报告;较轻问题仅在能描述具体情形时报告;疑似严重但未确认的问题要报告并说明未能核查之处;安全发现需指明不可信输入及其进入点。少量扎实发现优于长列表。
  7. 说明检查了什么:每条发现指向已读代码或标注为猜测;区分代码所见、由此得出的结论以及简报所述但未核实的内容;简要说明所作假设。

使用方式 报告先给裁决,再给证据与行动,不加赞美、不复述 diff、不写填充内容。代码链接格式为 [显示文本](file:///绝对路径#L10-L20),路径从工作区根目录构建。报告分段:意图(一行,推断时标注)、阻塞项(通常不超过三个,按根因合并症状,每项含触发条件、影响、链接和最小有效修复及粗略规模 S 小于1小时、M 1–3小时、L 1–2天;无阻塞则写 No blockers 并说明检查过的最高风险区域及尝试打破的方式)、后续项(有用的非阻塞工作,各带链接,不凑数)、规范(非阻塞的约定、类型与简洁性说明)、假设与未验证声明(裁决依赖但未能确认的内容及何种情况会改变结论)。简报提出窄问题时,先用证据直接回答,再只保留有内容的分段,跳过空段。

适用场景 适用于评审工作区改动、暂存改动、分支差异、最近提交、设计或计划,尤其适合持久化、权限、安全、并发、迁移、公共 API、计费和数据丢失等高风险区域。

限制 除非简报要求,不运行测试、构建、包管理器或格式化工具;不修改文件或仓库状态。缺少简报时意图需推断并标注。无法确认的假设和未验证声明需明确写出。