Explain Changes 是一个说明代码变更的辅助技能,目标是对某个变更建立有依据的解释:原问题或旧状态是什么、新行为是什么、对用户、调用方或维护者有什么实际影响。解释在对话中交付,并尊重用户使用的语言和技术背景,篇幅随变更实质内容伸缩。
用途 它服务于需要理解某处改动而非修改代码的场景:本地未提交的修改、一个 PR、单个提交或提交区间、一个分支、标签或版本之间的两个快照,或外部提供的补丁与 diff。
主要能力
- 确定比较基线。若对话中已指明目标,直接使用;未指明时先查看工作区:有改动就解释这些改动,否则询问用户指的是哪个 PR、提交、分支、版本或补丁。多个可能目标会导致实质不同的解释时也会询问。随后简要说明比较范围与基线。
- 分类型建立比较:本地改动对比 HEAD,覆盖已暂存与未暂存变更及相关未跟踪文件;PR 获取描述、基线与头版本、diff 及关联 issue 或规格,并使用合并基点比较;提交或提交区间解释单个提交相对父提交的变化,或端点之间的净变化;分支与该目标分支合并基点比较以隔离分支自身工作;标签、版本或两个显式修订直接比较两个快照并说明方向;外部补丁按其声明的比较与上下文使用。
- 还原变更。阅读 diff 及足够的周边代码、调用方、测试和相关文档以确定两种状态,用 issue 或 PR 文本了解声明意图、用实现证据判断实际行为,标注推测的动机并说明声明目标与实际交付之间的差异。
- 分组讲解。按行为或目的分组,沿受影响流程跨文件追踪,覆盖所选变更的全部实质部分;生成的产物、锁文件和机械性修改可合并简述。区分运行时行为变化与测试、文档、配置及内部重构。每组说明:之前发生什么、变更后发生什么、影响谁以及在什么具体场景、实现如何产生差异(附代码引用)、有证据支持的迁移或兼容要求与取舍。必要时用相同代表性输入或调用场景对比两侧,结构变化明显时可用小型 Mermaid 或文本图。
- 组织输出。先讲主要变更及实际效果,再补必要背景,然后按逻辑顺序讲解分组;关键论断附文件路径、符号或源码链接。区分已观察行为、预期行为与不确定性;测试只作为覆盖场景的证据,只有在实际运行并观察到结果时才声称通过。
使用方式 该技能以对话形式工作,通过检查 Git 状态、diff、历史版本、PR 元数据及周边代码来获得证据;在可用时将 Git 引用解析为修订 ID,检查历史状态时保留工作区。若无法访问远程目标,会说明缺失的访问权限或工具,并请求 diff 或可访问目标,同时继续基于已有证据解释。
适用场景 适合代码评审前的理解、向他人说明某次改动的影响、梳理 PR 或发布版本的变更要点,以及解读外部提供的补丁。
限制 该技能只负责解释:编辑代码、创建提交、发布评论和开展验收评审需要另行请求。无法访问的目标、缺失的周边代码或基线证据会限制解释深度,此时会明确说明证据缺口。资料未提供安装命令、价格、平台支持等具体信息。