Community编程与开发github.com

合并请求注释

为合并请求/拉取请求添加面向审查者的AI变更说明,包括意图、变更前后的行为以及已验证的入口点图,并以一个总览评论、每个变更文件的文件级评论以及真正不明显的代码段的行内评论呈现,每次推送后保持同步。

合并请求注释 是什么?

该技能专为需要向审查者解释AI生成代码变更的场景设计。它通过三层注释结构——总览评论(MR级别)、文件级评论(每个变更文件)和行内评论(仅非明显代码段)——帮助审查者快速理解变更的意图、行为变化和代码入口点。支持GitLab、GitHub和Bitbucket,并能根据项目语言自动调整注释语言。技能核心功能包括:首次运行生成完整注释集(预览后发布),后续推送自动同步更新注释(检测现有注释并仅更新变更部分)。内置脚本分析变更清单,自动识别测试用例变化,并通过入口点图确保调用链的准确性。注释遵循严格的预算控制(每个文件最多3条行内评论,每个MR最多12条),避免过度注释。同步模式会重新检查现有注释,移动、过时或孤立的注释会被相应处理,确保每次推送后注释与最新代码一致。该技能强调注释质量而非数量,要求对机械性文件仅提供一行解释,对测试文件提供用例列表,对复杂逻辑变更提供完整的模板格式。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kirill-kolomin/self-descriptive-merge-requests/tree/main/skills/annotate-merge-request

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

为审查者注释合并请求

审查者在阅读AI生成的差异时,大部分时间都在重构作者已知的三件事:为什么会有这个变更,什么行为变化了,以及谁调用了这段代码。这个技能将这三件事用简单语言写在合并请求级别——而不是源代码注释。

注释分为三层,每层有不同的规则:

层级覆盖范围包含内容
总览 - 一个MR级别的评论始终整个变更的概览图
文件 - 每个变更文件一个评论始终,自动生成文件除外文件变更的含义
行内 - 锚定在差异行上仅真正不明显的代码段,有预算限制为什么这段代码是这个样子

文件覆盖是无条件的:审查者打开差异中的任何文件都必须找到对该文件的解释。判断哪些值得解释、哪些是显而易见的,是在文件内部对方法和具体代码块做出的,而不是决定文件是否被覆盖。

操作模式

模式何时使用作用
annotate首次在MR上运行构建完整注释集,预览,批准后发布
sync每次推送到MR分支后根据新差异重新检查现有注释;仅更新、删除或添加变更的部分

如果MR上已存在此技能的注释(通过标记检测,见§7),则运行sync,而不是annotate——重新运行annotate会导致重复评论。

1. 前置检查

在编写任何内容前确认:

  1. 平台和MR身份。 git remote -v → gitlab.com/自建GitLab、github.com或Bitbucket。然后找到当前分支的开放MR(glab mr view、gh pr view)。如果还没有MR,则停止并说明——此技能注释已有MR,不创建MR。
  2. 差异范围。 始终使用 git merge-base HEAD origin/<target-branch> → <base>..HEAD。永远不要直接对比目标分支的头部:否则目标分支上无关的提交会显示为本次MR的变更。
  3. 语言。 使用项目MR已使用的语言编写注释(检查现有的MR/PR描述和评论)。默认使用用户与您交流的语言。
  4. 发布权限。 发布到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在评论发布后才存在,因此交叉链接需要两个阶段:

  1. 发布每条评论,在另一个注释的链接位置使用占位符令牌([[ref:<slug>]])。
  2. 收集已创建评论的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 钩子,以便在合并前不会忘记。

相关技能