pr-explainer 是一个面向 Pull Request 评审场景的技能,用于生成可分享的 PR 讲解产物。它的目标读者是第一次看到该 PR 的评审者,帮助其在打开 diff 之前快速理解改动的全貌。
用途
当需要撰写 Pull Request 描述、发布说明(release notes)或差异摘要(summary diffs)时使用该技能。它会为当前分支的待合并 PR 生成一个自包含的 HTML 页面,作为可分享的讲解产物。
主要能力
该技能会读取当前分支的待合并 PR 信息:使用 git log --oneline @{upstream}..HEAD 获取提交列表(若无 upstream,则回退到 origin/main..HEAD),使用 git diff @{upstream}...HEAD 获取统一差异。
生成的页面必须回答以下五个问题:
- 这个 PR 试图解决什么问题?
- 为什么它是一个问题?
- 我们如何解决它?
- 我们考虑过哪些替代方案?
- 为什么当前方案比替代方案更好?
如果 diff、PR 正文和提交信息中没有为其中某个问题提供证据(最常见的是第 4 和第 5 点),页面应如实说明(例如“该 PR 未记录考虑过哪些替代方案”),而不是编造答案。
使用方式
该技能基于 artifact-explainer 技能的模板构建页面,并按其指示使用 Artifact 工具发布。使用模板的 sections 风格:保留章节结构,删除编号步骤。各槽位填充方式如下:
- 导语(Lede):用两三句话说明该 PR 改了什么以及为什么需要它。如果 PR 正文已经写得好,可直接复用。
- 章节(Sections):当改动有结构性叙事时,先放一张架构或流程图;否则直接进入代码。先放一个前后对比章节,展示用户可观察到的变化(行为、API 形态或输出);如果改动没有可观察的表面,则跳过。然后按材料的自然接缝将 diff 分组为章节——将相关改动归为一组,而不是按文件拆分。每个章节中,代码片段通常就是主题本身:一段精简的代码片段、一段通俗解释,以及评审者应仔细查看的内容;仅在结构或流程确实需要时才添加图表(该技能的图表优先默认适用于概念讲解,而非 PR 讲解,后者多为符号性内容)。最后以一个章节收尾,说明 diff 中不明显的内容——仅凭 diff 看不到的上下文(为什么选这个方案而非替代方案、尝试过并否决了什么、有意留下的后续工作)。
- 回顾(Recap):将要点重述为评审者应重点关注的地方。
页面正文末尾需逐字添加以下一行:
Paste this URL back into Claude Code to keep iterating on these findings.
保持诚实
描述 diff 实际做了什么——追踪它,而不是从名称推断。如果 PR 中有不清楚的地方,应在第 4 节中说明,而不是猜测。
适用场景
适用于需要为 Pull Request 撰写描述、生成发布说明或差异摘要的开发者与评审流程。
限制
该技能要求当前分支存在待合并的 PR 或可比较的上游分支;若缺少 upstream,会回退到 origin/main..HEAD。对于 diff 中无法体现的信息(如替代方案、被否决的尝试),技能不会编造,而是明确标注缺失。