reviewkit

reviewkit

审查 AI Agent 刚刚编写的代码，检查 AI 生成的改动特有的失败模式。泛泛地“找 bug”会漏掉 Agent 最常犯的三种错误：写出孤立来看正确、放进这个仓库却不对的代码；在改动中塞入看似合理、却没人要求的杂项；以及悄悄把工作的一部分留着没做完。reviewkit 会先检查这些问题，然后再进行正确性审查，并按严重程度排列报告结果。它不会修复任何内容。是否修复由人决定，也可以交给实现类技能处理。

这是一个**审查者，不是编辑器。**它会读取改动并作出判断，绝不会编辑源代码。它唯一可选的产物是一份审查报告，用户可以保存下来，用于撰写 PR 描述。

以全新视角审查

**审查者不应是编写该改动的 Agent。**reviewkit 通常会在刚刚生成代码的同一会话中运行，这意味着审查者会带着编写代码时的所有自我辩解：已经为之找过理由的捷径、已经认定无关紧要的边缘情况。这是审查沦为盖章走过场的最大原因。

因此，如果你有子 Agent 工具，请把审查步骤委派给一个全新的子 Agent：把 diff、明确说明的意图以及以下审查步骤交给它，让它在不了解实现会话内容的情况下汇报结果。审阅其发现，然后再呈现给用户。如果没有可用的子 Agent 工具，就自行执行审查步骤，但要在报告中明确说明这是一次自我审查，因为用户需要知道这份结论有多大参考价值。绝不要悄悄自我审查刚刚由自己编写的改动。

无论采用哪种方式，都要牢记一点：审查磁盘上实际存在的代码，而不是你记得自己原本打算写的代码。

何时触发

在 Agent（或用户）完成一部分工作，并希望在发布前对其进行评判时触发：例如“审查这个”“审查我的改动”“审查 diff”“检查这段代码”“提交前自我审查”“/reviewkit”，或者在编码会话结束后只问一句“这样看起来对吗”。它审查的是未提交的工作或分支的 diff，而不是逐行审计整个代码库。

它不同于泛泛的正确性检查工具：reviewkit 会先检查是否符合项目惯例和Agent 生成的冗余内容，而侧重查找 bug 的审查会跳过这些。如果用户只想检查正确性 bug，就说明这一点，并且只运行该项检查；不要为了充实报告而加入另外两项。

流程

1. 选择审查目标

审查必须以实际 diff 为依据，因为凭记忆审查毫无价值。根据 git 状态确定目标，然后说明你的选择，并让用户有机会更改：

• 存在未提交的更改（git status --porcelain 输出非空）→ 检查工作树：git diff HEAD（同时包含已暂存内容时，使用 git diff --staged）。这是全新编码会话后的默认情况。git diff 不会显示未跟踪文件，因此 Agent 从未暂存的全新文件对它不可见，而整个新模块悄无声息地漏出审查是最糟糕的遗漏。使用 git status --porcelain（?? 条目）或 git ls-files --others --exclude-standard 列出这些文件，并将每个文件完整 Read 一遍，作为更改的一部分进行审查：所有未跟踪的源文件，无一例外。唯一可以跳过的未跟踪文件，是无人编写的文件：锁文件、构建输出、供应商依赖项、编译后的资源、快照。将它们标记为生成文件，抽查确认它们确实是生成的，而非手动编辑的，然后继续。
• 工作树干净，分支领先于其基分支 → 审查分支差异。从 gitkit 获取基分支，由它负责解析。不要假定是 main，也不要在此重新推导；错误的基分支会悄无声息地产生空差异，或包含半个仓库历史的差异，而这两种情况看起来都像是有效的审查目标。没有 gitkit 时，使用 git symbolic-ref --short refs/remotes/origin/HEAD 获取远程默认分支（去掉 origin/ 前缀）；若失败，则依次检查 main 或 master，选择第一个能通过 git rev-parse --verify 解析的分支，并在目标行说明使用了哪种回退方案。然后运行 git diff <base>...HEAD 和 git log <base>..HEAD --oneline，了解更改意图。
• 如果调用中指定了目标（“审查此分支”“审查我暂存的更改”）→ 直接遵从，跳过检测。

用一行说明选择了哪个目标以及原因，然后继续。如果以上条件都不适用（工作树干净且分支没有领先），请询问要审查什么，不要自行猜测。

审查前先验证。 确认目标能够解析（对于命名的基分支，使用 git rev-parse <ref>），且更改确实非空：已跟踪文件的差异，加上你列出的未跟踪文件。仅由新建未跟踪文件构成的更改，其 git diff 为空，但仍是完整的审查目标。如果引用无法解析，或者差异和未跟踪文件列表都为空，请停止并说明原因，因为审查错误或空的范围会导致捏造发现，而非真正的审查。

先完整阅读一次差异，再开始评判。只读一次。以下四轮是针对同一次阅读提出的四个问题，不是读四遍；如果某一轮需要你没有记住的细节，提取相关代码块（git diff HEAD -- <path>），不要再次读取整个差异。惯例契合度中用于对照的相邻代码也一样：只读能体现模式的同级文件，不要读遍整个目录。

完成此步骤的条件是：已说明目标行、引用可解析、已阅读每个更改文件和每个非生成的未跟踪文件，并且已记录明示的意图（或记录其缺失）。

记录更改的明示意图，来源可以是提交消息、分支名称、引用的计划或问题，或用户自己的表述，因为审查的一半是在确认“是否完整完成了要求，且仅完成了要求”。具体记录该意图：它是需求完整性和Agent 产物特征中的范围蔓延检查所依据的规范。

所有轮次的基本规则。 始终遵循以下规则；它们决定了真正的审查与无意义噪声之间的区别：

• 跳过已有工具可强制执行的事项。 不要报告格式、导入顺序或 lint 规则方面的问题，因为格式化工具、lint 工具或 CI 会自动检查这些内容。此次审查的全部价值，在于发现机器会漏掉的问题。把精力放在这些问题上。
• 每条发现都必须有证据。 引用有问题的代码片段，并指出它违反了什么：仓库规范文档中的具体条目、明确陈述的意图、真实的 API 签名，或具体的失败输入。无法引用证据支持的发现只是猜测；应将其删除。这是防止凭空捏造发现的首要保障。
• 每条发现发布前都必须达到可信度门槛。 设想一下，要让这条发现不成立，必须满足什么条件；只有当答案已由代码、复现结果或测试运行确认，或有强有力的依据且不存在可信的无害解释时，才报告这条发现。“可能有问题，但我无法检查运行时行为”只有在说明无法检查的具体部分时才算达标。更弱的情况不属于发现，而是未经验证的领域，应记录在报告发现中的覆盖范围说明里。把猜测降级为“未经验证”也是实实在在的结果；把猜测包装成 bug，只会浪费读者的时间，损害他们对整份报告的信任。
• 记录无法判断的内容。 审查过程中，持续记录未能真正覆盖的领域：无法通过静态分析判断的并发路径、授权模型位于差异范围之外的安全边界、只抽查而未通读的生成文件、无法离线核实真实 API 的依赖项。保持沉默会让人以为“没有问题”，因此必须明确指出未经检查的领域，不要略过。

2. 第 1 轮：符合规范

这次改动看起来像是由这个仓库里的其他代码写出来的吗？Agent 默认会生成普遍正确、却忽视本地惯例的代码。针对每个变更文件，都要与相邻文件进行比较，因为周围的代码就是规范：

• 命名与结构。 新名称、文件布局和模块边界是否与同级文件一致？如果仓库里到处都是 fetch_user，某个 Agent 却把辅助函数命名为 getUserData，就会显得格格不入。
• 既定模式。 仓库是否已有实现同一功能的方式（HTTP 客户端、错误类型、日志辅助函数、测试工厂），而这次改动却重新发明了一套？接受新的抽象之前，先用 grep 搜索已有实现。
• 惯用写法与风格。 检查错误处理、异步风格、导入方式，以及 lint 工具不会检查的格式约定。遵循现有写法，而不是抽象意义上的“最佳实践”。
• 依赖项。 是否添加了一个库来实现仓库已有的功能，或违反了项目惯例？检查清单文件和现有导入。
• 明确记录的规范。 如果仓库记录了规范（例如 CLAUDE.md、Agent 指南文件、CONTRIBUTING.md 或风格指南），应先阅读，并据此评估改动。仓库中记录的规则始终优先于一般的“最佳实践”。

这里常见的命名异味（采用 Fowler 的术语；适用时应使用这些标签，因为比一段描述更准确）：神秘命名（名称含义不清）、霰弹式修改（一个逻辑变更散布在多个文件中）、发散式变更（一个模块因多个互不相关的原因而被修改）。

完成本轮的标准是：每个变更文件都至少与一个同级文件或一项已记录规范进行了比较，而且上述每项检查都有对应发现或明确记录的无问题结果。

3. 第 2 轮：Agent 风格代码的特征

寻找机器生成代码的蛛丝马迹：看似高效，却毫无实际价值的填充内容：

• 过度工程化。 只为一个调用方设计的抽象、无人设置的配置项、可以用直接调用取代的多层间接调用，以及针对不存在的需求进行的“面向未来设计”。
• 无用和不可达代码。 从未调用的辅助函数、无法执行的分支、无人导入的导出项，以及赋值后从未读取的变量。
• 臆造或错误的 API。 调用真实类型中不存在的方法、标志或字段；使用听起来合理、却属于错误库版本的函数。请对照实际依赖项核实，而不是相信模型的猜测。
• 多余的注释。 复述代码的说明（// increment i）、没有补充信息的文档字符串，以及遗留的注释掉的代码。
• 范围蔓延。 超出请求范围的更改：无关的重构、对未修改行重新格式化、顺手重命名、无人要求的版本升级。凡是无法由既定意图证明合理的内容，都要标记出来。
• 虚假的健壮性。 吞掉错误的 try/catch、掩盖故障的默认值、没有断言任何内容或只是恒真判断的测试，以及代替真实处理逻辑的 TODO。

这里常见的代码异味包括：推测性通用化（为不存在的需求设计抽象，应删除并改为内联，直到出现真正的第二个调用方）、代码重复（在多个差异块中粘贴相同逻辑，而不是复用）、基本类型偏执（用裸字符串或整数代替领域概念）、中间人 / 消息链（只负责转发的层，或 a.b().c().d() 这样的导航）。推测性通用化尤其是 Agent 代码异味的典型特征。

当每个差异块都已依据上述特征逐一检查，并且每个新增的导出项、辅助函数和依赖项都有已确认的调用方或检查发现时，本轮检查才算完成。

4. 第 3 轮：需求完整性

Agent 交付不足的情况和交付过度一样常见：它们可能只给某个分支搭了个空架子，漏掉请求中的某个边界情况，或者只解决了简单的 80%，却悄悄留下未完成的部分。请依据 选择审查目标 中记录的意图，也就是计划、问题描述或用户的原话，评估更改并报告缺口：

• 缺少需求。 请求明确要求，但差异完全没有实现的内容。
• 实现不完整。 只处理了理想路径的需求、多个情况中只处理了一种，或只实现了接口而没有实现行为。
• 遗留的空架子和占位符。 看似已经完成的工作中，仍留有 TODO/FIXME/throw new Error("not implemented")/pass/空处理程序。
• 理解有误。 更改确实做了某些事，但并非请求的内容；它解决的是一个相近但更容易的问题。

如果没有可供衡量的已记录意图（没有计划、问题描述或明确请求），请说明这一点，并跳过本轮检查，不要凭空编造规范。不要猜测用户从未提出的需求。

当已记录意图中的每项需求都被标记为已满足、部分满足或缺失，并且每项都有对应的差异块作为依据时，本轮检查才算完成。

5. 第 4 轮：正确性

现在进行经典审查，检查前几轮之后留下的内容：

• 逻辑错误。 差一错误、条件反转、运算符错误、返回值处理不当。
• 边界情况。 空值/null/缺失输入、边界值、Unicode、大型负载，以及错误路径和正常路径。
• 数据边界。 对于改动后的 UI 渲染的每个值，若渲染方式或数据来源是由此差异新增或修改的，请在验证 schema、数据库列、API 类型或 maxLength 中找到其上限，然后检查渲染是否妥善处理：长文本截断或换行；对于电子邮件或 ID 等无断点字符串，使用断行规则（overflow-wrap、word-break）；数量为 1 时使用单数形式；数量为 0 时显示空状态；可选字段缺失时提供回退显示。引用上限和渲染代码所在行。前端上限低于后端上限属于问题，因为有效记录会因此无法保存或显示。如果仓库中没有上限，则根据渲染方式区分：没有长文本处理的渲染属于 🟡 问题，写作 unbounded: no limit in <schema>, <column>, <API type>; render at file:line has no truncation or break rule；已经处理长文本的渲染不属于问题；仓库外部（第三方 API）规定的上限则记入覆盖范围说明。qakit 的最坏情况检查是在运行时将这些值放到屏幕上。没有 qakit 时，请手动用长值、空值和缺失值渲染屏幕。
• 状态与并发。 竞态条件、共享状态变更、顺序假设、幂等性、资源清理（文件、连接、锁）。
• 安全性。 注入、缺少授权/所有权检查、代码或日志中的密钥、不安全的反序列化、未经验证的输入跨越信任边界。
• 测试。 改动后的测试是否确实覆盖了变更，是否通过？如果仓库的测试命令显而易见且运行成本低，就运行它；报告运行了什么以及结果。

测试套件通过并不能证明变更经过了测试，因为 Agent 写出的测试可能会通过，只是因为它们断言的内容根本不可能失败。对每个新增或修改的测试，都要检查以下几点：

• 如果实现有问题，它会失败吗？ 在脑中反转测试所覆盖的逻辑，或破坏一个边界值。如果测试仍然通过，那它只是装饰。这是判断测试质量最有力的问题。
• 它断言的是可观察行为吗？ 还是在断言中重新实现生产逻辑，再拿代码和自身比较？
• 测试场景是否清晰可见？ 还是深埋在设置/固定数据/模拟对象中，以至于测试只证明了模拟对象可用，其他什么也没证明？
• 它是否覆盖了变更引入的失败路径？ 而不只是功能演示中的正常路径？
• 它是否验证了所述需求？ 还是只验证了一个更容易满足的相近需求？

当每条改动后的代码路径都对上述每项检查有问题记录或明确的检查无异常结果，并且每个新增或修改的测试都回答了这五个问题时，本轮审查才算完成。

6. 报告审查结果

在行内打印审查报告，并按严重程度排列发现，让读者一眼就能判断优先级。为每项标注：

• 🔴 阻断项。 发布前必须修复；例如会造成实际故障的 bug、安全漏洞、缺失的要求或违反约定的问题。
• 🟡 应修复项。 确实存在的问题，值得处理，但不会阻止发布。
• 🟢 小问题。 润色、风格或细微疏漏；修复与否均可。

每项发现按以下顺序给出：位置，以可点击的 file:line 格式表示；发现它的检查环节（约定 / 疏漏 / 完整性 / 正确性）；引用有问题的代码片段，并说明违反了什么（根据选择审查目标中的证据规则，引用约定文档中的行、明确提出的要求、实际 API 或失败输入）；用一句话说明问题；给出具体修复方法。如果某个检查环节没有发现问题，请明确说明；检查结果干净也是真正的结果。绝不要为了显得审查全面而虚构问题。 如果无法引用证据，就不能算作发现。对于干净的差异，空报告才是诚实的结果。

报告结构如下：结论行、按严重程度从高到低排列的发现，最后是覆盖范围说明。

结论必须根据发现得出，不能凭感觉。 按以下规则机械地选择结论，让读者无需重新阅读清单也能信任结果：

• 需要修改。 存在一个或多个 🔴 阻断项。
• 修复后可就绪。 没有阻断项，但至少有一个 🟡 应修复项。
• 可就绪。 没有高于 🟢 小问题的发现。小问题不会阻碍变更。

不要因为变更整体不错或作者付出了很多努力而弱化结论；也不要为了显得严谨而把结论说得更严重。如果阻断项确实存在，即使其他方面都很出色，变更仍需修改。

最后附上覆盖范围说明：用一小段说明本次审查未验证的内容，即各检查环节记录的未验证部分，并说明是否运行了测试，以及这是全新视角审查还是自我审查（参见以全新视角进行审查）。如果读者知道并发路径未经检查，就可以自行跟进；如果读者误以为已经检查过，就会造成问题。如果缺口严重到可能藏有实际问题（例如未审查的安全边界，或无人能在此验证的迁移），请说明变更需要外部审查后才能继续，而不要给出证据不足以支持的结论。

不要编辑源代码或应用修复。修复工作的分配请参阅交接。

7. 可选：保存报告

展示审查结果后，可以询问用户是否要保存（不要主动保存）。如果用户需要一份可长期保留的副本，例如粘贴到 PR 描述中，请将其写入 docs/reviews/NNNN-review-<branch-or-feature-slug>-YYYY-MM-DD.md，使用下一个序号、简短的小写 kebab-case 标识，以及审查创建日期的 ISO 格式（例如，0002-review-auth-refactor-2026-07-23.md）。要获取序号 NNNN，请检查以下位置中最大的四位前缀序号并加一：当前工作树、git worktree list 列出的所有其他工作树，以及 origin/HEAD（执行 git fetch origin 后运行 git ls-tree --name-only origin/HEAD docs/reviews/）。如果没有序号，则从 0001 开始。请检查这三个来源，否则并行工作树可能会使用相同序号。跳过无法访问的来源，例如没有远程仓库时；如果没有 git，则只列出该目录。序号按目录独立管理，且绝不重复使用。如果编辑同一份报告，整个文件名保持不变。需要时创建 docs/reviews/。保存的文件必须与打印的内容完全一致，并添加一行标题，注明日期和审查范围。如果没有文件系统，则跳过此步骤，将行内报告作为交付内容。

8. 移交

报告结束后，以简短的三点收尾：

• 变更内容。 说明 reviewkit 未编辑任何源代码。说明报告是否已保存。
• 保存位置。 给出已保存报告的路径，或说明报告仅以内联形式提供。注明审查的范围。
• 下一步。 根据评审结论，指定一个行动：
  • ready → 如果已安装 qakit（/qakit），用 qakit 编写手动 QA 计划。否则，用 commitkit 提交；如果没有，则执行 git commit。
  • ready-with-fixes 或 needs-work → 使用 implementkit 的修复轮次落实评审结果，并将本报告交给它。否则，手动修复问题。然后再次运行 reviewkit。
  • blocked on outside review → 指明待审查的领域，以及必须完成审核的人员或检查。在审核完成前，不进行其他后续操作。

将任务交给下一个套件；不要调用它。

说明

• 根据约定只读。 reviewkit 会运行 git 以及读取／搜索命令来理解变更，并且最多运行仓库自身的测试命令来检查正确性。它绝不会编辑源代码、提交或推送。唯一可能的写入操作是在用户要求时，将可选报告文件保存到可选：保存报告中所述的位置。
• Skill 只在 gitkit 的工具列表中，其他地方都没有。 reviewkit 在审查分支差异时会调用 gitkit 来确定基准 ref，因为基准错误会导致差异为空，或包含半个仓库的历史，而这两种情况看起来都像是真正的审查目标。移交中提到的套件只负责接收任务，不会被调用。
• 按差异规模调整审查力度。 一行修复只需快速过一遍并给出一行结论；大型功能分支则需要完整审查。不要用繁琐流程来拉长小改动的审查。
• 不能替代测试或 CI。 这是在它们基础上的判断性审查，重点关注 Agent 编写的代码容易出现的问题。已由自动化检查覆盖的内容应报告为已覆盖；审查应重点关注它们遗漏的问题。这也是审查目标的基本规则跳过由工具强制执行的规则的原因。
• 没有 shell 或 git？ 请用户粘贴差异和原始需求，然后针对他们提供的内容运行四轮审查，并将报告以代码块形式打印出来，供他们自行保存。