为审查者注释合并请求
审查者在阅读AI生成的差异时,大部分时间都在重构作者已知的三件事:为什么会有这个变更,什么行为变化了,以及谁调用了这段代码。这个技能将这三件事用简单语言写在合并请求级别——而不是源代码注释。
注释分为三层,每层有不同的规则:
| 层级 | 覆盖范围 | 包含内容 |
|---|---|---|
| 总览 - 一个MR级别的评论 | 始终 | 整个变更的概览图 |
| 文件 - 每个变更文件一个评论 | 始终,自动生成文件除外 | 文件变更的含义 |
| 行内 - 锚定在差异行上 | 仅真正不明显的代码段,有预算限制 | 为什么这段代码是这个样子 |
文件覆盖是无条件的:审查者打开差异中的任何文件都必须找到对该文件的解释。判断哪些值得解释、哪些是显而易见的,是在文件内部对方法和具体代码块做出的,而不是决定文件是否被覆盖。
操作模式
| 模式 | 何时使用 | 作用 |
|---|---|---|
annotate | 首次在MR上运行 | 构建完整注释集,预览,批准后发布 |
sync | 每次推送到MR分支后 | 根据新差异重新检查现有注释;仅更新、删除或添加变更的部分 |
如果MR上已存在此技能的注释(通过标记检测,见§7),则运行sync,而不是annotate——重新运行annotate会导致重复评论。
1. 前置检查
在编写任何内容前确认:
- 平台和MR身份。
git remote -v→ gitlab.com/自建GitLab、github.com或Bitbucket。然后找到当前分支的开放MR(glab mr view、gh pr view)。如果还没有MR,则停止并说明——此技能注释已有MR,不创建MR。 - 差异范围。 始终使用
git merge-base HEAD origin/<target-branch>→<base>..HEAD。永远不要直接对比目标分支的头部:否则目标分支上无关的提交会显示为本次MR的变更。 - 语言。 使用项目MR已使用的语言编写注释(检查现有的MR/PR描述和评论)。默认使用用户与您交流的语言。
- 发布权限。 发布到MR对团队可见并会通知审查者。默认以dry-run预览方式展示在对话中,仅在用户批准后发布。仅当用户已明确表示无需询问即可发布时跳过预览。
阅读 references/platform-gitlab.md、references/platform-github.md 或 references/platform-bitbucket.md 以获取确切的命令——注释API在文件级锚定、可解决性和更新语义方面存在差异。
2. 建立变更清单
两个脚本位于此文件旁边的 scripts/ 目录中。通过绝对路径调用它们,从技能自身的目录构建。运行时的工作目录是用户的仓库,而非技能目录,因此仅用 scripts/... 路径会失败。下面,$SKILL 表示包含此 SKILL.md 的目录(例如,用户级安装的 ~/.claude/skills/annotate-merge-request,或从插件加载时的 skills/annotate-merge-request)。
python3 "$SKILL/scripts/diff_inventory.py" <base>..HEAD --json > /tmp/sdmr-inventory.json
对于每个变更文件,该脚本提供:变更类型(添加/修改/删除/重命名)、requires_file_comment(仅对自动生成/供应商文件为false)、file_fingerprint(文件指纹)、以及带有新侧行号(行内评论必须锚定的位置)、最近封闭符号和无关性信号的代码块。对于规范和测试文件,还会输出 test_cases——文件中每个用例及其状态(unchanged(未变)/ adapted(适配)/ added(添加)/ removed(删除)),通过比较两个版本之间的用例主体计算得出,而不是从差异中读取。这是供您阅读的启发式映射,不能替代实际差异——对于您要描述的任何内容,请阅读实际差异。
每个代码块的 anchor 是一个建议(其第一个添加的行);added_lines 列出了所有可用于锚定的行。选择与解释内容实际相关的行。
硬约束:行内评论只能锚定在差异中出现的行上。 GitLab和GitHub都不允许在远离代码块的未修改代码上添加评论。任何关于MR未修改的代码的内容都应放在文件或总览评论中,绝不能放在行内。
3. 第一层——覆盖每个变更文件
清单中标记为 requires_file_comment: true 的每个文件都恰好得到一个文件级评论。没有例外,没有预算,没有关于它是否“足够有趣”的判断。
唯一的豁免是自动生成和供应商输出——锁定文件、dist/、快照、代码生成、压缩包、vendor/。清单会标记这些;如果它遗漏了您的项目生成的某个模式,也将其豁免,并告诉用户要添加哪个模式。
变化的是形式和长度,而非存在性:
- 具有真正逻辑变更的文件使用完整模板(
references/annotation-format.md):角色、变更原因、变更前→变更后、从哪里调用。 - 规范或测试文件则使用测试用例列表——其中现在包含的每个用例,每个都有状态(
unchanged(未变)/adapted(适配)/added(添加)/removed(删除)),对于变更的用例,提供简短描述。标准模板不适合规范:没有东西调用它们,因此入口点部分自然为空。清单为您计算状态(每个文件的test_cases);adapted(适配)用例是审查者最需要的,因此它们排在前面,并且必须说明调用形状还是期望值发生了变化。完整规则见references/annotation-format.md。 - 机械性文件只得到一行,让审查者可以放心跳过:
仅导入了路径——跟随了PricingService的重命名;无行为变更。 - 被删除的文件得到一行,说明为什么被删除以及被什么替代——这通常是MR中最有用的注释之一。
将这些作为文件级评论锚定(GitHub上为 subject_type=file,GitLab上为 position_type=file),而不是在行上。它们附加到文件头部,因此不会与代码交错,审查者在打开每个文件时就会看到。如果实例不支持文件级锚定,则回退到文件的第一个变更行——平台参考文件给出了确切的后备方案。
写好一行解释是整个技能的关键。现在的工作量随文件数量增加,因此用三段描述一个机械性文件是一个缺陷,而不是彻底性。
4. 第二层——总览评论
一个MR级别的评论,是整个审查的入口点,严格按照 references/annotation-format.md 指定的结构:
- 意图——这个MR解决什么问题,用两三句简单语言说明。不要重述差异。
- 变更前→变更后行为——运行系统的观察者会注意到什么。对于新组件,说“新”而不是虚构一个“之前”。
- 入口点图——读者如何从实际入口点(HTTP路由、CLI命令、事件处理程序、cron、导出的API)到达变更的代码。限制在3层以内;每个变更区域一行,而不是每个文件一行。
- 阅读顺序——首先打开哪个文件,哪些是机械性的后续文件。
- 行内评论索引——指向每个行内注释的链接。
总览有自身的容量限制(最多7个阅读顺序条目,最多5个行为行,不逐文件枚举——文件评论负责此项)。这些限制在 references/annotation-format.md 中;请遵守它们,否则总览会变成文件评论本应防止的长篇大论。
验证入口点图
永远不要猜测调用图。 编造的调用列表比没有注释更糟糕:它自信地错误,而且审查者会相信它。对于声明的每个边,使用实际搜索(跨仓库的 rg -n 'symbolName',包括测试和配置)找到调用者,并一直向上跟踪直到到达入口点或3层,以先到者为准。如果无法解析符号的调用者——动态分发、DI容器、反射、字符串键控注册表——则写 入口点未解析(<原因>) 而不是听起来合理的链。
5. 第三层——行内评论,仅针对非明显代码
这是唯一需要判断的层级。对每个方法和代码块运行 references/significance-test.md 中的重要性测试。简而言之:
需要注释的条件: 读者可能会合理地问“为什么这样?”——不明显的意图、在差异中不可见的行为变更、非局部后果、故意的权衡、不寻常的算法、变通方案、来自文件外部的约束,或与本次MR中另一个变更的交互。
跳过的条件: 代码对代码库的合格读者不言自明:一个5-10行将字符串转换为标题大小写的辅助函数、一个 DEBOUNCE_MS = 300 常量、一个明显的空值检查、机械性的测试更新。文件评论已经覆盖了文件;行内评论会以更低的价值重复它。
代码的大小不是测试标准——它的推断距离才是。自定义编码方案中的6行辅助函数需要注释;200行的生成快照文件则不需要。
预算(默认值;用户可显式提高):
- 每个文件最多3条行内评论,每个MR最多12条。
- 这些是上限,不是配额。如果一个文件的完整故事已由其文件评论讲述,则得到零条行内评论,这是正常情况。
- 超出预算是一个信号,而不是许可:如果一个MR中超过12个点都真正非明显,则MR太大,或者解释应放在总览中,作为完整故事讲述。请向用户说明这一点。
每个行内注释使用与文件评论相同的部分,但限于该代码块,并保持简短——3到6行,在紧凑的差异视图中阅读。
6. MR内的交叉引用
当一个变更仅与同一MR中的另一个变更一起才有意义时,将它们链接起来。交叉引用通常属于入口点图,但也出现在意图(“需要因为<其他文件>现在传递X”)和变更前/后(“旧路径仍然存在,见<其他评论>”)。文件评论是最自然的位置:此文件的新合约由 [[ref:order-controller]] 消费。
评论URL在评论发布后才存在,因此交叉链接需要两个阶段:
- 发布每条评论,在另一个注释的链接位置使用占位符令牌(
[[ref:<slug>]])。 - 收集已创建评论的ID/URL,然后编辑每个正文,用真实链接替换令牌。
在发布前规划好slug——每个 [[ref:...]] 令牌必须在阶段2中解析,而已发布评论中遗留的令牌是明显的缺陷。阶段2不是可选的。
7. 发布,并带身份标记
此技能创建的每条评论都以在渲染的Markdown中不可见的标记行结束:
<!-- sdmr:v1 kind=overview -->
<!-- sdmr:v1 kind=file slug=<slug> anchor=<file> ffp=<file-fingerprint> -->
<!-- sdmr:v1 kind=inline slug=<slug> anchor=<file>@<new-line> fp=<hunk-fingerprint> -->
对 ffp= 使用清单中的 file_fingerprint,对 fp= 使用代码块的 fingerprint。标记使 sync 成为可能:它识别技能自己的评论、每个评论的附加对象以及所描述代码的指纹。永远不要在缺少标记的情况下发布注释;永远不要编辑人类的评论。
让注释保持未解决状态。 已解决的线程会折叠显示,因此审查者必须逐一展开每个注释——这恰好隐藏了注释存在的目的。以开放状态发布,让审查者在阅读时逐一解决;这个点击是审查者自己的“已读”标记。
这种选择的代价:如果项目要求所有线程在合并前解决(GitLab的所有线程必须解决,GitHub的要求对话解决),则注释必须在合并按钮解锁前解决。每个文件都有一个文件评论,可能需要多次点击,因此当您检测到此类设置时告知用户,并提供在结束时批量解决的选项。两个平台的命令在平台参考文件中。
8. 每次推送后同步
新提交会静默地使注释失效:评论描述的代码可能已移动、改变含义或消失——新文件则完全没有覆盖。每次推送到MR分支后,以 sync 模式重新运行此技能。
python3 "$SKILL/scripts/sync_state.py" --inventory /tmp/sdmr-inventory.json --comments /tmp/sdmr-comments.json
--comments 可重复使用,并接受平台的原始JSON——在GitHub上这是两次调用(审查评论和问题评论),因此传递两个文件。
它分类每个现有注释为 ok(锚定和指纹未变——保持不变)、moved(相同代码,新行——重新锚定)、stale(描述的代码已变更——重新读取并重写)、或 orphaned(文件或代码块已删除——删除)。它还报告**file coverage**(文件覆盖)——哪些变更文件仍缺少文件级评论,哪些被豁免——以及 uncovered(未覆盖)的代码块,这些现在是行内评论的候选者。
然后:仅修复它标记的内容,始终就地重写总览评论(它总结整个MR,任何推送都可能使其无效),并重新运行§6的阶段2,以便交叉引用链接仍指向活跃的评论。文件覆盖中的 MISSING(缺失)行不是可选的——没有评论的新文件是这个技能存在的目的之一。请遵循 references/sync-after-push.md 中的强制推送情况、各平台删除评论的处理方法,以及如何避免搅动实际上未更改的评论。
向用户说明一次,每次推送后都需要运行此操作,并且 references/sync-after-push.md 包含一个可选的 pre-push 钩子,以便在合并前不会忘记。