Community写作与编辑github.com

PR解释器

为队友(以初中级工程师为对象)解释一个拉取请求、错误修复或本地变更。默认生成独立的HTML页面,使用`--md`可生成Markdown交接文档。涵盖功能(原因、架构、流程、关键代码、验证)或错误修复(症状、根因、修复、证明)。适用于“解释这个PR/修复/变更”、“写一个演练”、“编写交接文档”、“创建审查指南”或在工作交接前使用。支持`--concise`(两分钟版)、`--local`(未提交或未推送的工作)和`--md`(HANDOVER.md格式的Markdown)。

PR解释器 是什么?

PR解释器是一款AI驱动的技能,专为开发者平台(如Claude Code、Cursor、Codex)设计,用于自动化生成针对初中级工程师的拉取请求、错误修复或本地变更的技术解释文档。该技能的核心价值在于将复杂的代码变更转化为清晰、自包含的教学式页面,默认以HTML格式输出,并支持通过`--md`标志生成Markdown格式的交接文档。它能够自动识别变更类型(功能或错误修复),并按照预定义的骨架组织内容:对于错误修复,依次描述症状、根因、错误代码、修复代码、验证过程和关键教训;对于功能更新,则涵盖问题背景、架构位置、数据流、关键代码走查、边界行为、验证结果和审查重点。该技能利用`gh`CLI工具(如果可用)提取PR详情和差异,或通过本地git命令分析未提交的变更。它注重技术精确性,要求使用真实的模块名、函数名和行号,同时通过简洁易懂的措辞确保初中级工程师能够理解。此外,它还支持生成流程图和表格等视觉元素(仅当文本无法清晰解释时),并包含验证结果的引用,如回归测试(在修复前后运行)和其他手动测试证据。输出结果以文件形式呈现,并附带详细的报告,说明覆盖的章节、使用的视觉元素和验证运行情况。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sahildaswani/agent-skills/tree/HEAD/skills/pr-explainer

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

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

文档

PR解释器 是做什么的?

生成一份完整的文档,向队友解释一个变更:之前哪里出了问题或缺少什么,系统是如何围绕这些问题运行的,变更做了什么,以及我们如何确认它有效。

参数

  • 目标: PR编号或URL,或者不指定。
    • 如果提供了PR并且ghCLI可用,则使用 gh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,files 获取详情,并使用 gh pr diff <url> 获取差异。在PR的头部提交处读取周围代码(git show <headRefOid>:<path>),而不是本地 HEAD。
    • 如果没有提供PR,或者没有gh:解释本地变更。使用 git diff <base>...HEAD 获取提交的差异,使用 git diff 和 git status 获取未提交的工作,其中 <base> 是默认分支或第一个提交。
  • --local:即使存在PR,也使用本地检出(未推送的工作)。在页面上注明这反映的是本地变更。
  • --concise:一个简短的版本,大约两分钟可以读完。最多一个视觉元素,最多3个代码片段,无目录,每个部分1-3句话。
  • --md:编写Markdown而不是HTML(默认文件名为仓库根目录下的 HANDOVER.md,除非用户指定了其他名称)。在浏览器不方便时,以及交接文档中使用此选项。

读者和语气

  • 读者是团队中的初中级工程师。使用短句、简单的动词,每个段落只表达一个想法。
  • 不要解释基础知识(REST、SQL、JWT、React hooks),也不要使用非技术的类比。保持技术性,使用真实的模块名、函数名、路由名、字段名和实际数字。
  • 让措辞简单,而不是内容。在出现不常见的库调用或模式的地方进行解释。
  • 以最终稿的口气书写。直接描述当前状态。没有变更日志或“我们之前认为”的说法。
  • 对确定性要诚实。将未经证实的论断标记为“很可能,尚未确认”。

范围:解释变更,而不是差异

  • 选择那些能讲述故事的文件,并且只选择其中重要的代码行。
  • 每个文件使用1-3个代码片段,每个片段不超过25行,省略的部分用 ... 表示。每个片段附带文件路径,以及2-4句说明其作用和原因。
  • 对于修复,展示导致bug的代码以及修复的差异。
  • 按照运行时流程对代码进行排序,而不是按照差异顺序。
  • 跳过管道代码、重命名和格式化。如果审查者在差异中会看到它们,则用一句话提及。

1. 理解变更

  • 阅读差异和周围的代码。确定模式:
    • 功能:新行为或大型重构。
    • 错误修复:症状、根因和修复。
  • 找到最新的验证运行:测试命令和计数,最好有证据证明新的回归测试在没有修复时失败,在有修复时通过。如果此类证据不存在且成本较低,请生成它:git stash push -- <src files>,运行测试,然后 git stash pop。同时查找手动或端到端检查(CLI输出、请求、截图)。只展示每种验证的最新运行结果。
  • 在可能的情况下,使用对话中的发现(根因分析、QA报告、工单)。

2. 骨架

每个文档都以一行标题(repo · PR #n · ticket 或 repo · local changes)、一个通俗易懂的标题以及1-2句的开场白开始。

错误修复

  1. 出了什么问题:症状、在哪里发现、排除了哪些可能性。
  2. 根本原因:数据或流程出错的确切位置(文件:行),如果有助于理解,可以配合图表。
  3. 导致问题的代码:一到两个代码片段。
  4. 修复:修复的差异代码片段以及为什么它能工作。指出它同时修复的副作用。
  5. 如何确认:一个在修复前失败、修复后通过的回归测试,完整测试套件计数,以及手动检查。
  6. 经验教训:初中级工程师可以在其他地方复用的2-4条经验。

功能

  1. 为什么:问题或目标,附有证据。
  2. 它在哪:架构或模块上下文(图表),以及哪些部分有意未修改。
  3. 流程:步骤或流程图,链接到代码卡片。
  4. 代码走查:每个重要文件一张卡片,按流程顺序排列。
  5. 需要知道的行为:边界情况、状态、失败模式(如果超过3个,使用表格)。
  6. 验证:仅最新的运行结果。
  7. 审查者总结:2-3行的心智模型,以及在差异中应该重点查看的地方。

交接文档补充(使用--md时始终包含;HTML中可选):

  • 如何运行/测试:确切的命令。
  • 做出的假设:在规格说明未明确时所做的决策及其原因。
  • 待解决的业务问题:按影响排序。
  • 风险和回滚:生产环境中可能出问题的地方以及如何回滚。
  • 后续步骤:如果有更多时间,你会做什么。

简洁版: 只包含出了什么问题 / 什么和为什么、根本原因 / 它是如何工作的、修复 / 关键代码以及如何确认。

3. 视觉元素:仅在文本无法解释时才使用

内容使用方式
模块或服务架构、谁调用谁、请求顺序Mermaid flowchart / sequenceDiagram(≤ ~12个节点)
一个分支在前后行为不同前后对比表格或小型静态SVG
数据经过多个阶段、被过滤器丢弃的值示例输入→输出的表格,显示前后对比
状态、命令、风险、合约表格

在Markdown中,使用围栏 ```mermaid 代码块(GitHub会渲染它们)。只有在用户要求时才添加动画。

4. 构建

  • HTML: 从 references/page-template.html 开始(自包含、支持亮暗模式、从CDN加载Mermaid和highlight.js)。保存到 .pr-review/<name>.html,以工单或PR命名,或命名为 local-<short-desc>。确保它不在git跟踪范围内:如果 git check-ignore -q .pr-review/ 失败,则将 .pr-review/ 追加到 .git/info/exclude。除非被要求,否则不要编辑 .gitignore。
    • 代码片段:<pre><code class="language-<lang>">…</code></pre>,HTML转义。对于修复差异,使用 language-diff 配合 -/+ 行。
    • Mermaid:<pre class="mermaid">…</pre>。永远不要硬编码颜色。
  • Markdown(--md): 纯GitHub风格Markdown,相同的骨架,不使用HTML。

5. 一次检查

  • HTML:如果浏览器工具可用,在桌面宽度和约400px宽度各打开页面一次。检查Mermaid是否渲染、代码是否高亮,一次性修复发现的问题,不要循环。否则,说明没有预览过,并给出打开命令(macOS上为 open,Windows上为 start,Linux上为 xdg-open)。
  • 重新阅读页面上的每个 文件:行、数字和命令,对照代码进行检查。事实必须准确无误。

6. 报告

回复时包含:

  • 文件路径
  • 模式以及涵盖的章节
  • 使用的视觉元素及其解释的内容
  • 文档展示的是哪个验证运行
  • 任何标记为“尚未确认”的内容

未经请求,不得编辑PR正文、发表评论或推送任何内容。

相关技能