SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场create-compelling-prs

create-compelling-prs

编程与开发

查看项目

更新于 10-15 12:42

技能介绍

用途

create-compelling-prs 用于在准备 PR 供评审时，让 PR 更具说服力。其核心理念是：评审者同时面对许多 PR，如果 PR 不能立即令人信服，就可能被跳过或拒绝；证据胜过修辞，一个实现良好、能在 2 分钟内说服人的 PR，比五个需要反复追问的 PR 更有价值。

主要能力

PR 正文模板

按变更类型选择对应模板：

  • Bugfix：包含「What broke（哪里坏了）」「Root cause（根因）」「Fix（修复方式及为何选此方案）」「Before / After（前后对比）」「Test output（测试输出）」「How to verify（如何验证，含复现原 bug 的步骤与回归检查）」，并以 Closes #ISSUE 关联。
  • Feature：包含「What this adds（新增的用户可见能力）」「Why（业务或产品动机）」「Implementation（实现说明与关键设计决策）」「Demo（演示图或 GIF）」「Test output」「How to verify（黄金路径与边界情况）」，并以 Closes #ISSUE 关联。
  • Refactor：包含「What changed（移动、重命名或重构了什么）」「Why（促使此变更的底层问题）」「What stays the same（公共 API、行为、输出不变）」「Test output（精确命令、修订版本、范围与结果，并说明限制与剩余必需门禁）」，并以 Closes #ISSUE 关联。
  • Deps：包含「Update（包版本变化）」「Why now（安全公告 / 所需功能 / 例行升级）」「Risk（低/中/高，是否有破坏性变更、受影响区域的覆盖情况）」「Test output（所属仓库依赖验证通过，并写明命令与范围）」，并以 Closes #ISSUE 关联。

独立评审记录

当实现流程提供独立咨询评审时，需增加简短章节，区分：已修正的建议、已拒绝并附理由的建议、因评审运行时故障而不可用的建议、以及仍然残留的问题。客观的仓库政策可能决定就绪或合并门禁；独立 LLM 建议本身从不阻止 PR 创建、不导致任务失败，也不使已推送的检查点搁浅。

部署证据

PR 是否必须在评审前证明其在某处运行过、以及以何种形式证明，属于仓库政策而非协议。有些公司对基础设施/后端 PR 要求已验证的预发布部署，有些则根本没有预发布环境。

应先阅读仓库 playbook（GET /admin/playbooks/<org>/<repo>，回退到 CONTRIBUTING.md / .github/PULL_REQUEST_TEMPLATE.md），并解决以下问题：

  • 评审门禁要求什么部署证据，适用于哪些路径？（门禁可能未经评审就拒绝 PR）
  • 证据块的精确格式是什么？（门禁会解析它——需逐字复现 playbook 的块，不要改写）
  • 放在正文还是评论？（扫描正文的门禁看不到评论，反之亦然）
  • 什么可以豁免？（文档/仅测试 PR 通常豁免；playbook 会说明如何记录豁免）

如果 playbook 中没有部署证据政策：不要自行发明，也不要假设存在预发布环境。应说明你在本地验证了什么、如何验证（精确命令及其输出），并在 PR 正文中注明 playbook 未定义部署证据要求。

视觉证据

对于任何影响 UI 的变更，捕获前后截图（优先 Playwright，手动为回退方案）并嵌入 PR 正文。

图片托管位置属于仓库政策。检查 playbook 是否有资源托管章节并遵循。当政策使用 Pylot 资源时，阅读 pylot-cli 并使用其 Assets 工作流；该技能是受支持生命周期命令与上传传输的唯一来源。

如果没有资源托管章节：直接将图片附加到 PR（GitHub 托管通过 PR 编辑器或评论 API 上传的图片），或链接 CI 产物，并说明使用了哪种方式。绝不要链接评审者无法访问的托管图片。

跳过条件：仅后端、仅 CLI、配置/基础设施、仅测试，或捕获超过 120 秒。视觉证据是建议，绝不是门禁——除非仓库 playbook 将其设为门禁。

验证范围

在选择命令前，先解析所属仓库的活跃指令与验证契约。将完整变更映射到受影响行为与直接消费者，包括共享代码、依赖/锁文件变更、迁移、转换与集成边界。当契约允许时运行有意义的聚焦检查；保留所有必需的广泛、全量套件、构建、预发布与发布门禁。依赖变更不豁免测试。未映射的影响或缺少有意义覆盖时，需要更广泛的验证或明确记录未解决的覆盖缺口。绝不要在未检查仓库政策及其实际配置工作流的情况下，推断 CI 拥有某个完整门禁。

记录命令、范围、结果、测试计数、精确修订版本与剩余门禁。失败、不可用或零测试的运行不算通过。仅当当前收据的修订版本、范围、环境与政策仍然适用时才复用；在变更、失败或未解决疑虑后需重新运行。独立验收仍然必需：检查 diff 并在有用时复现相关行为或门禁，而无需在未变更代码上自动重复同一全量套件。

自审清单

在打开 PR 或将其标记为可供评审前运行：

  • 完整？ 是否完成了本 PR 单一驱动 issue 所代表的有限工作？
  • 可发布？ 若按原样合并，PR 是否会关闭其驱动 issue，且每个有意推迟的具名标准都逐字记录在链接的后续 issue 中（使用共享后续 issue 契约）？
  • 无手动注意事项？ PR 正文中零「你需要手动做 X」的说明。
  • 验证通过？ 当前证据覆盖受影响行为与每个必需仓库门禁；精确命令、范围与修订版本已记录。
  • 证据存在？ 每个有意义的变更都嵌入了截图或测试输出。
  • 政策遵守？ playbook 的部署证据块逐字出现在其指定位置——或正文中有「playbook 无政策」的说明。
  • Issue 已链接？ PR 恰好有一个驱动 issue，并使用 Closes #N、Fixes #N 或 Resolves #N。多 PR 工作中每个后续 PR 都有自己的驱动 issue；使用共享后续 issue 契约提交并链接后续 issue，然后从后续 PR 关闭该后续 issue。Refs #N 仅用于明确标识为相关上下文的 issue，绝不用于驱动当前 PR 的 issue。

如果「无手动注意事项？」检查失败：关闭 PR 并报告阻塞——以仓库 playbook 指定的形式（阻塞报告、issue、任务报告）；若未指定，则在仓库上开 issue。把工作推回给别人的 PR 比没有 PR 更糟。绕过障碍——如果 UI 是唯一路径，用 API；如果 API 缺失，写脚本。

负责人自评循环

当工作者报告完成后，不要立即接受，要更用力地追问。

迭代协议：

  1. 检查约定的结果、diff、受影响行为与当前验证收据。
  2. 识别具体的验收缺口。要求行动而非声明：缺少行为检查需要证据；渲染缺口在相关时需要检查或截图。
  3. 修正后，在结果修订版本上验证受影响范围，并解决任何剩余实质性缺口。保留独立要求的仓库门禁。
  4. 当验收得到支持时停止。不要仅为展示努力而增加迭代、测试或代码变更。如果缺口无法解决，说明具体阻塞与证据。

规则：

  • 绝不接受修辞。「我有信心这很扎实」不是证据——要求证据。
  • 独立验证。在所属仓库契约下检查当前证据并复现相关行为或检查。打开 PR URL；适用时加载受影响的线上站点。在接受前解决实质性缺口。
  • 跟踪修正与证据。有效的验证收据可以在无代码变更的情况下关闭缺口；对每个识别出的缺口要求具体结果。

轮换问题（变化以避免公式化回答）：

  • 「高级工程师在代码评审中会拒绝什么？」
  • 「这份证据覆盖了哪些受影响行为与仓库门禁？运行缺失的有意义检查并粘贴输出。」
  • 「截图受影响的页面。它符合设计系统吗？」
  • 「你推掉了什么？重读任务并列出每个交付物。」
  • 「如果这被拒绝，最可能的原因是什么？预先修复它。」

使用方式

该技能以技能文档形式提供，通过阅读并遵循其中的模板、清单与流程来使用。具体安装命令与调用方式在提供的资料中暂未说明。

适用场景

  • 在提交 PR 供评审前，按变更类型套用正文模板。
  • 需要按仓库 playbook 要求附上部署证据或视觉证据时。
  • 需要执行自审清单、确认 issue 链接与验证范围时。
  • 作为负责人对工作者提交的 PR 进行自评与追问时。

限制

  • 部署证据与视觉证据是否为门禁取决于仓库政策，技能本身不强制。
  • 视觉证据在仅后端、仅 CLI、配置/基础设施、仅测试或捕获超过 120 秒时跳过。
  • 独立 LLM 建议本身不阻止 PR 创建、不导致任务失败。
  • 若 playbook 未定义部署证据政策，不得自行发明或假设存在预发布环境。
  • 关于收费、价格、平台支持等具体信息，资料中暂未提供。