diffity-review

Diffity Review 技能

使用 diffity agent CLI 审查差异并留下内联评论。

参数

• ref（可选）：要审查的 Git 引用（例如 main..feature、HEAD~3）。默认为工作树更改。如果同时提供 ref 和 focus，则两者都要使用（例如 /diffity-review main..feature security）。
• focus（可选）：将审查重点放在特定领域。可选项：security、performance、naming、errors、types、logic。如果省略，则审查所有内容。

CLI 参考

diffity agent diff
diffity agent list [--status open|resolved|dismissed] [--json]
diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new|old] --body "<text>"
diffity agent general-comment --body "<text>"
diffity agent resolve <id> [--summary "<text>"]
diffity agent dismiss <id> [--reason "<text>"]
diffity agent reply <id> --body "<text>"

• comment 必须提供 --file、--line、--body
• --end-line 默认为 --line（单行评论）
• --side 默认为 new
• general-comment 会创建与任何文件或行都无关的差异级评论
• <id> 接受完整 UUID 或 8 个字符的前缀

前置条件

1. 检查 diffity 是否可用：运行 which diffity。如果未找到，请使用 npm install -g diffity 安装。

说明

第 1 步：确保 diffity 正在为正确的 ref 运行（不打开浏览器）

审查需要一个正在运行且 ref 与请求的 ref 匹配的会话。ref 不匹配会导致添加评论时出现“file not in current diff”错误。

1. 运行 diffity list --json 获取所有正在运行的实例。解析 JSON 输出，并找到 repoRoot 与当前仓库匹配的条目。
2. 如果存在匹配条目，请将其 ref 字段与请求的 ref 进行比较：
   • 注册表对工作树会话存储 "work"，对命名 ref 则存储用户提供的 ref 字符串（例如 "main"、"HEAD~3"）。
   • 如果 ref 匹配 → 复用该会话，记下端口，然后继续执行第 2 步。
   • 如果 ref 不匹配 → 重启：运行 diffity <ref> --no-open --new（如果没有 ref，则运行 diffity --no-open --new）。--new 标志会终止旧会话并启动新会话。使用 Bash 工具并设置 run_in_background: true。等待 2 秒，然后运行 diffity list --json 验证并记下端口。
   • 如果未请求 ref，且运行中的会话的 ref 不是 "work" → 使用 diffity --no-open --new 重启（运行中的会话针对的是命名 ref，但我们需要工作树会话）。
3. 如果此仓库没有运行中的会话，则在后台启动一个：
   • 命令：diffity <ref> --no-open（如果没有 ref，则运行 diffity --no-open）
   • 使用 Bash 工具并设置 run_in_background: true
   • 等待 2 秒，然后运行 diffity list --json 验证并记下端口。

第 2 步：审查差异

1. 直接从 diffity 获取统一差异——这会自动处理合并基准解析、未跟踪文件和所有 ref 类型：

   diffity agent diff
   

   这会输出当前会话的完整统一差异。行号位于 @@ 块头中。
2. 查找并阅读所有相关的 CLAUDE.md 文件——根目录中的 CLAUDE.md，以及包含已修改文件的目录中的任何 CLAUDE.md 文件。这些文件定义了项目专属规则，差异必须遵循这些规则。

评估更改规模并调整策略

3. 评估差异规模并制定审查方案。无论差异规模如何，都要彻底审查每个文件——区别只在于如何安排工作：

   • 小型（约少于 100 行更改、1-3 个文件）：直接按顺序审查每个文件。
   • 中型（100-500 行更改、3-10 个文件）：按领域分组文件（例如后端、前端、测试、配置）。先审查核心逻辑文件，以便在审查连带影响前理解其意图。
   • 大型（500 行以上更改或 10 个以上文件）：按领域分组文件。从核心逻辑开始，然后审查所有剩余文件。对于机械重复的更改（例如在 20 个文件中应用相同的重命名），先验证前几个实例中的模式是否正确，然后检查所有剩余实例是否偏离该模式——不能跳过任何实例，但模式确定后可以加快检查速度。

   无论规模大小，都要阅读并审查每个已更改文件。不要跳过文件，也不要只抽查。

在审查前理解变更

4. 先总结变更。 在查找问题之前，先在脑中梳理差异：

   • 这项变更要实现什么？（新功能、错误修复、重构、配置变更）
   • 哪些文件属于结构性变更，哪些涉及核心逻辑变更？
   • 作者的意图是什么？阅读提交说明（git log --oneline <args>）以及相关问题或 PR 描述，了解背景。
   • 作者做出了哪些关键决策？他们受到哪些约束？

   理解意图有助于区分有意的行为与真正的错误。

5. 对每个变更文件（根据上述大小策略进行调整），阅读整个文件（而不只是差异片段），以了解完整上下文。

6. 交叉检查调用方和依赖项。 对于任何变更的函数签名、重命名的导出项、修改的返回类型或改变的行为，请在整个代码库中搜索其用法。单独看起来正确的函数，也可能破坏所有调用方。检查：

   • 谁调用了这个函数？他们能否处理新的返回值、错误或 null 情况？
   • 谁导入了这个模块？修改后的导出名称能否正确解析？
   • 类型变更能否正确传递给使用方？

7. 使用以下方法分析代码变更。如果提供了 focus 参数，请重点关注该领域。否则，执行所有分析环节并应用信号阈值。

如何分析

差异会告诉你变更了什么；周边代码则能说明变更是否正确。请执行以下分析：

数据流分析——追踪变更代码中的值。每个变量来自哪里？又流向哪里？检查：

• 在变更代码假定值不为 null 或 undefined 的情况下，该值是否可能为 null 或 undefined？
• 变更代码是否处理了上游条件语句的所有分支？
• 如果函数的返回类型发生变化，所有调用方是否都能处理新的结构？
• 是否有类型收窄检查（例如 if (x)）被差异意外移到了检查范围之外？

状态与生命周期分析——针对有状态代码（React 状态、数据库事务、流、事件监听器）：

• 此变更是否创建了无法进入或无法退出的状态？
• 资源（监听器、订阅、文件句柄）是否仍能在所有路径上得到清理？
• 并发访问是否会破坏共享状态？
• 操作顺序是否仍满足不变量（例如，先初始化再使用）？

契约分析——检查变更代码是否符合必须满足的契约：

• 函数是否仍满足调用方的预期？（阅读调用方代码，不要猜测。）
• 如果函数实现了接口或重写了基类方法，是否仍符合要求？
• 前置条件和后置条件是否得到保留？
• 对于 API 端点，响应结构是否与客户端发送或预期的结构一致？

边界分析——针对系统边界处的代码（用户输入、网络、文件 I/O、IPC）：

• 使用用户可控的输入前，是否对其进行了验证？
• 格式错误的外部数据是否会导致进程崩溃或状态损坏？
• 是否存在注入风险（SQL、shell、XSS、路径遍历）？

边缘情况分析——只关注实际可能发生的情况，而非理论情况：

• 空数组、空字符串、零、负数——代码能否正确处理？
• 循环、切片或索引运算是否存在差一错误？
• 是否存在整数溢出，或除数来自输入时的除零问题？

完整性检查

分析代码是否正确后，检查这项更改是否完整——不只是正确，还要确认已经完成：

测试覆盖：

• 如果差异引入了新行为（新函数、端点、UI 流程、分支），是否有测试覆盖？如果没有，请将其标记为 [suggestion]。
• 如果差异修复了一个错误，是否有能捕获该错误的测试？回归测试可防止问题再次出现。
• 如果差异修改了现有行为，是否更新了现有测试以与之匹配？仍然通过的过时测试比没有测试更糟——它们会带来错误的信心。
• 如果差异包含测试，请检查测试质量：
  • 它们测试的是正确的内容吗？（行为，而非实现细节）
  • 它们覆盖了代码所处理的边界情况吗？（空输入、错误路径、边界值）
  • 它们是隔离的吗？（不暗中依赖测试顺序或全局状态）
  • 即使代码有问题，它们也可能通过吗？（同义反复式断言、被 Mock 掉的逻辑）

缺失内容：

• 修改了架构却没有迁移？
• 新增的环境变量没有文档说明或默认值？
• 新增的依赖没有更新锁文件？
• API 响应变更后，客户端没有相应更新？
• 新增的错误类型在调用处没有处理？
• 删除功能后没有清理相关代码（无效导入、未使用的配置、无关联的测试）？

只标记那些明显是确保此更改正常工作所必需的缺失内容。不要标记那些只是期望改进的内容。

应标记的问题

标记会影响正确性、安全性或可靠性的实际问题：

• 导致代码无法编译、解析或运行的问题（语法错误、类型错误、缺少导入、无法解析的引用）
• 会产生错误结果的逻辑错误（明显的 Bug、差一错误、条件失效）
• 修改代码中的安全漏洞（注入、XSS、绕过身份验证、数据泄露）
• 可以通过具体场景验证的竞态条件或数据丢失风险
• 违反 CLAUDE.md 的情况，且能引用被违反的具体规则
• 契约失效——修改后的函数不再满足调用方的预期
• 新增或修改行为缺少测试（标记为 [suggestion]，而非 [must-fix]，除非项目的 CLAUDE.md 要求必须编写测试）
• 更改不完整——缺少明显是确保此更改正常工作所必需的迁移、配置或客户端更新

跳过风格问题、可由 Linter 捕获的问题，以及未修改代码中原本就存在的问题。关注差异，而非整个文件。

评论前先验证

发布每条问题反馈前，请先验证其属实：

• 重新阅读上下文代码——许多看似存在的 Bug 在结合完整上下文后便不复存在
• 对于“缺少导入”或“变量未定义”的说法，请通过 grep 确认
• 对于调用方不兼容的问题，请查看实际调用位置
• 对于违反 CLAUDE.md 的问题，请确认该规则适用于此文件
• 对于缺少测试的问题，请确认其他文件中没有已经覆盖此路径的测试

如果多个文件中出现相同模式，请仅评论首次出现的位置，并在总体摘要中提及这一模式，不要重复评论。

第 3 步：留下评论

1. 按严重程度排序评论。 先发布所有 [must-fix] 评论，然后是 [suggestion]，最后是 [question]。每种严重程度内，按文件顺序排列。这样作者快速浏览时能先看到最重要的问题。

2. 在评论正文中使用严重程度前缀对每项发现进行分类：

   • [must-fix] — 错误、安全问题、数据丢失风险。会导致代码中断或产生错误结果的问题。
   • [suggestion] — 有明确理由的具体改进建议。不是风格偏好，而是真正的改进。这包括缺少测试、改动不完整以及更好的方案。
   • [question] — 需要作者澄清的不明确之处。

3. 针对每项发现，使用以下方式留下内联评论：

   diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new] --body "<comment>"
   

   • 对新增或修改的代码使用 --side new（默认值）
   • 对已删除的代码使用 --side old
   • 如果问题涉及多行，使用 --end-line
   • 先指出问题，不要先讲背景。内容应具体且可执行。
   • 对于小型、自成一体的修复，附上展示修复方式的代码建议
   • 对于较大型的修复（结构性改动、多处改动），描述问题和建议的处理方法，不要提供完整代码块
   • 如果指出违反了 CLAUDE.md 规则，请引用被违反的确切规则

4. 留下所有内联评论后，判断是否需要一般评论：

   • 没有发现问题 → 留下一般评论：“未发现问题。已检查错误和 CLAUDE.md 合规性。”
   • 发现 1-2 个问题 → 跳过一般评论，除非存在内联评论无法涵盖的跨领域问题。
   • 发现 3 个或更多问题 → 留下一般评论，概述主要类别。
   • 差异较大 → 始终留下一般评论，说明审查范围并按类别归纳发现的问题。
   • 一般评论中不要使用严重程度前缀——前缀仅用于内联发现。
   • 开门见山地给出结论，直接简洁——不要恭维，不要说废话，不要叙述代码的作用。

   diffity agent general-comment --body "<overall review summary>"
   

第 4 步：打开浏览器

1. 现在评论已准备就绪，打开浏览器：

   diffity open <ref>
   

   如果提供了 ref 参数，请传入（例如 diffity open HEAD~3）。如果没有提供，则省略该参数以打开默认视图。

2. 告知用户审查已完成，他们可以查看浏览器。示例：

   审查完成 — 请查看浏览器。

   发现：2 个必须修复的问题、1 条建议

   准备好后，运行 /diffity-resolve 进行修复。