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>是默认分支或第一个提交。
- 如果提供了PR并且
--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句的开场白开始。
错误修复
- 出了什么问题:症状、在哪里发现、排除了哪些可能性。
- 根本原因:数据或流程出错的确切位置(
文件:行),如果有助于理解,可以配合图表。 - 导致问题的代码:一到两个代码片段。
- 修复:修复的差异代码片段以及为什么它能工作。指出它同时修复的副作用。
- 如何确认:一个在修复前失败、修复后通过的回归测试,完整测试套件计数,以及手动检查。
- 经验教训:初中级工程师可以在其他地方复用的2-4条经验。
功能
- 为什么:问题或目标,附有证据。
- 它在哪:架构或模块上下文(图表),以及哪些部分有意未修改。
- 流程:步骤或流程图,链接到代码卡片。
- 代码走查:每个重要文件一张卡片,按流程顺序排列。
- 需要知道的行为:边界情况、状态、失败模式(如果超过3个,使用表格)。
- 验证:仅最新的运行结果。
- 审查者总结: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正文、发表评论或推送任何内容。