create-compelling-prs

创建有说服力的 PR

你的 PR 需要争取关注。审查者要查看很多 PR——如果你的 PR 不能立即令人信服，就会被跳过或拒绝。证据胜过说辞。一个实施完善、能在 2 分钟内说服审查者的 PR，胜过五个需要后续跟进的 PR。

PR 正文模板

选择与你的更改类型相匹配的模板。

Bug 修复

## What broke
[One sentence: what failed and where]

## Root cause
[The underlying cause — missing guard, race condition, wrong assumption]

## Fix
[What changed and why this approach over alternatives]

## Before / After
| Before | After |
|--------|-------|
| ![before](URL) | ![after](URL) |

## Test output
[paste test run]

## How to verify
1. [Step to reproduce original bug — should now pass]
2. [Regression check]

Closes #ISSUE

功能

## What this adds
[One sentence: the user-visible capability]

## Why
[Business or product motivation]

## Implementation
[2-3 sentences: what was added/changed, key design decisions]

## Demo
![demo](URL_OR_GIF)

## Test output
[paste test run]

## How to verify
1. [Golden path step]
2. [Edge case]

Closes #ISSUE

重构

## What changed
[What was moved, renamed, or restructured]

## Why
[The underlying problem that made this necessary]

## What stays the same
[Public API, behavior, outputs — nothing visible changed]

## Test output
[paste exact commands, revisions, scope and results; state limits and remaining required gates]

Closes #ISSUE

依赖项

## Update
[Package] vX.Y.Z → vA.B.C

## Why now
[Security advisory / feature needed / routine bump]

## Risk
[Low/Medium/High — breaking changes? Coverage of affected areas?]

## Test output
[paste — owning repo dependency verification passed; name the commands and scope]

---

独立审查记录

当实施流程提供独立的建议性审查时，添加一个简短章节，说明哪些建议已修正、哪些建议已说明理由后拒绝、哪些建议因审查运行时故障而无法获取，以及仍存在哪些残留问题。客观的仓库政策可能会影响就绪状态或合并。独立 LLM 的建议本身绝不会阻止创建 PR、导致任务失败，或使已推送的检查点陷入停滞。

---

部署证据

PR 是否必须证明其在审查前已在某处运行，以及应以何种形式提供证明，由仓库政策决定，而非协议规定。有些公司要求基础设施/后端 PR 必须通过已验证的预发布环境部署；有些公司则完全没有预发布环境。

先阅读仓库操作指南（GET /admin/playbooks/<org>/<repo>，若没有则查看 CONTRIBUTING.md / .github/PULL_REQUEST_TEMPLATE.md），并确认以下事项：

问题	重要性
审查门禁要求提供哪些部署证据，适用于哪些路径？	门禁可能会在审查前拒绝 PR
证据区块的准确格式是什么？	门禁会解析该区块——必须逐字照搬操作指南中的区块，不要改写
应放在正文还是评论中？	扫描正文的门禁看不到评论，反之亦然
什么情况可以豁免？	仅涉及文档/测试的 PR 通常可豁免；操作指南会说明如何记录豁免

操作指南中没有部署证据政策？ 不要自行编造，也不要假设存在预发布环境。说明你在本地验证了什么以及如何验证——列出准确的命令及其输出，并在 PR 正文中注明，操作指南未定义部署证据要求。

---

可视化证据

对于任何影响 UI 的更改，截取更改前后的屏幕截图（优先使用 Playwright，也可手动截取），并将其嵌入 PR 正文。

图片托管方式由仓库政策决定。 查看操作指南中是否有资源托管章节，并遵照执行。如果环境中提供了 EVIDENCE_* 密钥，请使用 evidence-upload 技能：它会将图片上传到公开证据存储桶，并输出可嵌入的 URL，即使在私有仓库中也能正常显示（任何上传内容都可通过 URL 公开访问——不要上传机密或客户数据）。

没有资源托管章节？ 直接将图片附加到 PR（GitHub 会托管通过 PR 编辑器或评论 API 上传的图片），或链接到 CI 工件，并说明你采用了哪种方式。切勿链接到审查者无法访问的图片托管服务。

以下情况可跳过： 仅涉及后端、仅涉及 CLI、配置/基础设施、仅涉及测试，或截取耗时超过 120 秒。可视化证据是建议项，绝非门禁要求——除非仓库操作指南将其列为门禁要求。

验证范围

在选择命令之前，先查明所属仓库当前生效的指令和验证要求。将完整变更映射到受影响的行为和直接使用方，包括共享代码、依赖项／锁文件变更、迁移、转换和集成边界。在验证要求允许的情况下，运行有意义的定向检查；保留所有必需的广泛验证、完整测试套件、构建、暂存和发布门禁。依赖项变更不能免于测试。影响范围未映射或缺少有意义的覆盖时，必须扩大验证范围，或明确记录尚未解决的覆盖缺口。未经检查仓库策略及其实际配置的工作流，切勿推断 CI 负责执行完整门禁。

记录命令、范围、结果、测试数量、确切修订版本和剩余门禁。失败、不可用或测试数量为零的运行均不算通过。只有当现有验证记录的修订版本、范围、环境和策略仍然适用时，才可复用；代码有变更、验证失败或存在未解决的问题时，必须重新运行。仍需独立验收：检查差异，并在有用时复现相关行为或门禁；无需在代码未变的情况下自动重复相同的完整测试套件。

自审清单

在创建 PR 或将其标记为可供审查前，先运行此清单：

• 完整吗？ 这是否完成了本 PR 唯一驱动事项所代表的限定范围工作？
• 可交付吗？ 如果按现状合并，这个 PR 能否关闭其驱动事项，并确保所有有意推迟的命名标准均已原样写入关联的后续事项，并遵循共享的后续事项约定？
• 没有手动处理的注意事项吗？ PR 正文中是否完全没有“你需要手动执行 X”之类的说明？
• 验证通过了吗？ 当前证据是否涵盖受影响的行为和仓库要求的所有门禁？是否记录了确切命令、范围和修订版本？
• 证据齐全吗？ 每项有意义的变更是否都附有截图或测试输出？
• 遵循策略了吗？ playbook 指定位置是否包含部署证据块原文，或者正文中是否注明“playbook 中没有相关策略”？
• 关联了事项吗？ PR 是否恰好关联一个驱动事项，并使用 Closes #N、Fixes #N 或 Resolves #N 标记该事项？有意采用多 PR 工作流时，后续 PR 是否各自拥有驱动事项；是否已按照共享的后续事项约定创建并关联后续事项，并由后续 PR 关闭该事项？仅当某事项被明确标识为相关背景时才使用 Refs #N，绝不可用于驱动当前 PR 的事项。

如果“没有手动处理的注意事项？”检查未通过：请关闭 PR 并报告阻塞问题，且使用仓库 playbook 指定的形式（阻塞问题报告、事项或任务报告）；如果 playbook 未指定形式，则在仓库中创建事项。 把工作推回给别人的 PR，比没有 PR 更糟。要绕开障碍——如果只有 UI 可用，就使用 API；如果缺少 API，就编写脚本来完成。

负责人自我评估循环

工作者报告完成后，不要立即接受。要进一步严格审查。

迭代流程：

1. 检查约定的结果、差异、受影响的行为和当前验证凭据。
2. 找出具体的验收差距。要求采取行动，而非口头保证：缺少行为检查时需要提供证据；存在渲染差距时，在适用情况下需要检查或提供截图。
3. 更正后，在修改后的版本上验证受影响的范围，并解决所有仍然存在的重要差距。保留仓库要求的独立门禁。
4. 有充分依据支持验收时就停止。不要为了证明自己付出了努力而增加迭代、测试或代码更改。如果无法解决某项差距，应说明具体阻碍和证据。

规则：

• 绝不接受空谈。“我确信这很可靠”不是证据——必须要求提供证据。
• **独立验证。**检查当前证据，并根据所属仓库的约定复现相关行为或检查。打开 PR URL；在适用情况下加载受影响的线上站点。验收前解决重要差距。
• **跟踪更正和证据。**有效的验证凭据无需代码更改即可弥补差距；对于每个已发现的差距，都必须要求提供具体结果。

轮换提问（变换问法，避免回答流于形式）：

• “资深工程师在代码审查中会拒绝什么？”
• “这些证据覆盖了哪些受影响的行为和仓库门禁？运行缺少的关键检查并粘贴输出。”
• “截取受影响页面的截图。它符合设计系统吗？”
• “你搁置了什么？重新阅读任务并列出所有交付项。”
• “如果这被拒绝，最可能的原因是什么？提前修好。”