create-pr skill 解析¶

create-pr 是一套围绕主分支提交流程设计的交付框架。它的核心设计思想是：在进入团队评审之前，应先把分支规范与同步检查、质量证据、安全风险、兼容性说明和交付状态整理完整。 因此它把认证预检、分支同步、风险分级、质量验证、安全扫描、文档检查、提交规范和 PR 内容组织成一条固定流程。

1. 定义¶

create-pr 是一个面向主分支提 PR 的结构化交付 skill。它要求在创建 PR 之前完成一系列强制门禁检查，并用统一的 PR 标题和 PR 正文模板组织结果，最后再决定这个 PR 应该是 draft 还是 ready。它输出的不只是一个 PR 链接，而是一份带有门禁结论、未覆盖风险、PR 元数据和后续动作的交付报告。

2. 背景与问题¶

这个 skill 要解决的问题是：很多 PR 在进入团队评审前就已经带着大量不确定性，只是这些不确定性没有被显式写出来。

在没有明确流程约束时，常见问题通常集中在 6 类：

create-pr 的设计逻辑，就是把这些经常被"先开了再说"带过去的问题，全部前移为显式门禁，并要求每道门禁都留下可核查的结论。

3. 与常见替代方案的对比¶

在进入具体设计之前，先看它和几种常见做法的区别：

它并不是要替代 CI、代码审查或 GitHub 本身，而是把"PR 进入评审之前需要先补齐哪些信息"这件事标准化。

4. 核心设计逻辑¶

4.1 用固定流程 vs 自由发挥¶

create-pr 把整个过程固定成 13 个步骤，并把其中最关键的部分拆成 A 号门禁到 H 号门禁。这样设计，是因为 PR 创建本身是一个很容易被人类和模型同时低估的动作。

很多人会觉得："代码都写完了，开个 PR 只是顺手的最后一步。" 但真正影响团队评审质量的，恰恰往往是这最后一步做得是否扎实：

• 这条分支是不是已经同步到最新 origin/main？
• 质量检查有没有真的跑？
• 安全扫描是没问题，还是根本没做？
• 这个变更是低风险小改，还是涉及认证、迁移、并发、公共 API 的高风险改动？
• 这个 PR 现在到底该是 draft 还是 ready？

固定流程的作用，就是把这些原本容易被省略的判断变成一条清晰、可复查、尽量不依赖临场发挥的交付链。

4.2 先做认证和仓库预检¶

A 号门禁 要先检查 GitHub 认证状态、远端仓库、默认分支、权限和分支保护信息。

这道门禁的设计重点不是技术复杂度，而是避免在错误前提下继续推进后面的流程。比如：

• gh 根本没登录，却已经开始准备 PR 正文。
• 远端没有 main，或者默认分支不是 main，后续所有比较基准都错了。
• 当前账号没有权限，PR 创建根本无法完成。
• 分支保护规则取不到，需要明确记录覆盖缺口。

这类问题都不是代码本身的问题，但一旦前提错了，后面所有 Gate 的结论都可能没有意义。所以它被放在最前面，而且是 blocker。

4.3 把分支规范与同步检查单独做成 B 号门禁¶

B 号门禁 专门处理分支问题：不能从 main 发 PR、工作区必须干净、必须没有冲突标记、必须同步到最新 origin/main，并对分支命名做规范检查。

这是 create-pr 很重要的一层设计，因为很多 PR 事故，根本不是实现逻辑有问题，而是提交载体本身就不干净。比如：

• 在脏工作区里开 PR，导致本地未提交改动和已提交内容混在一起。
• 分支落后主干很多天，review 看到的其实已经不是当前主线语境。
• 分支名和提交语义完全脱钩，后续追踪困难。
• 冲突标记残留没发现，等 reviewer 或 CI 才暴露。

把这些问题前置到 B 号门禁，等于先验证"这个分支是否适合作为评审对象"。

4.4 做变更风险分类，而不只是列 diff¶

C 号门禁 要求不仅列出变更文件，还要识别高风险区域，并根据改动总行数给出分级：

• ≤ 400 行：正常
• 401–800 行：警告，建议考虑拆分
• > 800 行：强警告，除非变更天然不可拆分

这个设计解决的是 review 里一个很现实的问题：不是所有 PR 都值得用同样的评审预期去看。

同样是一个 PR：

• 如果只是几十行的小修补，review 重点可能是正确性和回归风险。
• 如果触碰认证、支付、迁移、并发、公共 API、基础设施配置，哪怕改动不大，也要补充更完整的风险和回滚说明。
• 如果一次改了 800 多行，哪怕逻辑上都没错，review 质量本身也会下降。

所以 create-pr 不把 diff 当成纯展示，而是把它当成决定后续审查负担和交付要求的输入。

4.5 质量证据必须显式记录¶

D 号门禁 要求运行项目标准检查，优先用仓库自带命令，做不到再回退到语言默认检查，并且必须记录具体命令和通过 / 失败结果。

这道门禁背后的设计思想很直接：没跑过的东西，不能写得像已经验证过一样。

这解决了两个常见问题：

• PR 描述里写着"已测试"，但没人知道到底跑了什么。
• 命令失败了，只在终端里看过一眼，最终 PR 正文里完全没有留下痕迹。

它要求的不只是"跑检查"，而是"把检查转成评审者能直接消费的证据"。这样 reviewer 不需要猜：这次变更到底有没有经过最基本的质量验证。

4.6 安全检查要单独成 Gate，而且强调多工具交叉验证¶

E 号门禁 把文件名风险扫描、diff 内容扫描，以及 Go 生态里的 gosec、govulncheck 放在同一层处理。

这是 create-pr 非常突出的设计点，因为 PR 是代码进入团队视野的前一道关口。如果在这个时候还没把高置信度安全问题拦下来，后面即使 reviewer 看到了，也已经浪费了团队时间。

评估报告里的场景 3 很能说明问题：with-skill 不只是发现了硬编码的 ghp_ token，还通过正则扫描和工具扫描形成了更扎实的证据链，并明确建议不要 push / create。without-skill 虽然也能看出来有问题，但结果更像一个普通 code review comment，而不是一项阻塞性安全结论。

这种设计的价值在于：

• 提高高危问题的发现率
• 降低"只是觉得像有问题"的模糊性
• 让 draft / ready 的判断有更明确的依据

4.7 文档和兼容性必须在开 PR 前说清楚¶

F 号门禁 要求检查文档、README、changelog 是否需要更新，并明确兼容性和 breaking change。

这条规则其实是在纠正一种很常见的误区：很多人把文档更新和兼容性说明当成 merge 之后再补的事，但评审者在看 PR 时，最需要知道的恰恰就是这些内容：

• 这个改动是否改变了外部行为？
• 有没有迁移成本？
• 如果上线后出问题，怎么回滚？
• 如果是 breaking change，影响面在哪里？

如果这些信息没有在 PR 里说清楚，reviewer 看到的就只是代码 diff，而不是一次完整交付。create-pr 把这件事放进强制门禁，等于明确规定：PR 不是只给代码看的，也是给变更说明看的。

4.8 commit hygiene 和 PR title 要绑在一起¶

G 号门禁同时检查 commit 集合和 PR title，要求都符合 Conventional Commits 规范，尤其强调：

• 标题格式必须是 <type>(<scope>): <subject>
• subject 不超过 50 个字符
• 语气用祈使句，不带句号

这样设计有一个非常现实的原因：很多团队采用 squash merge，最终进入 main 的 commit message 就是 PR title。如果 PR title 不受约束，前面再怎么注意提交规范，最后落到主干的历史仍然会变形。

因此，这个 skill 实际上把"提交规范"从 commit 层延伸到了 PR 层，避免出现：

• commit 写得还行，但 PR title 很随意
• commit set 混入无关提交
• reviewer 得自己猜这个 PR 到底应该怎么命名

4.9 引入 confirmed / likely / suspected 置信度模型¶

create-pr 的一个关键设计，是不直接二元判断 draft 或 ready，而是先定义三档 confidence：

• confirmed
• likely
• suspected

然后再用这个中间层去决定 draft / ready。

这个设计很重要，因为现实里的 PR 状态并不总是非黑即白：

• 有些 PR 所有关键 Gate 都跑过了，可以明确 ready。
• 有些 PR 只有一项非阻塞检查没跑完，逻辑上接近 ready，但仍有未覆盖项。
• 有些 PR 多个 Gate 都没法验证，或者高风险问题还没处理，明显不该直接 ready。

如果没有 confidence 这一层，系统很容易退化成主观判断："我感觉问题不大，先标 ready 吧。" 而有了这层之后，draft / ready 就变成基于证据的推理结果，而不是一种心情状态。

4.10 固定 PR 正文结构¶

create-pr 要求 PR 正文至少包含 8 个章节：

1. Problem/Context
2. What Changed
3. Why This Approach
4. Risk and 回滚方案
5. Test 证据
6. Security Notes
7. Breaking Changes / Migration Notes
8. Reviewer Checklist

这并不是为了把 PR 写成长文，而是为了让评审者在固定位置找到固定类型的信息。

这套结构解决的不是"会不会写 PR 描述"，而是"PR 描述是不是足以支撑高质量 review"。它把 reviewer 最关心的几类信息集中起来：

• 背景是什么
• 到底改了什么
• 为什么这么做
• 风险在哪里
• 有没有测试证据
• 有没有安全问题
• 是否有 breaking change
• reviewer 该重点看什么

评估报告显示，这也是 with-skill 与 without-skill 差异很大的部分：without-skill 往往能写出一个可读的说明，但经常缺风险、回滚、安全、兼容性这类真正决定评审效率的章节。

4.11 post-create verification 仍然值得单独保留¶

H 号门禁要求在 PR 创建后再次验证：

• base 是否真的是 main
• head 是否真的是当前分支
• 标题和正文是否正确渲染
• draft / ready 状态是否与 Gate 结果一致

很多流程把 gh pr create 成功当成结束，但 create-pr 认为最好再补一次核对。因为创建成功不等于创建正确：

• 可能 base 选错了
• 可能标题或正文因为转义、模板、换行导致渲染不对
• 可能明明该是 draft，最后却成了 ready

需要注意的是，H 号门禁在 Quick Reference 里更偏向信息性检查，而不是像 A 到 G 号门禁那样的前置 blocker；其中 gh pr checks 也明确是可选、非阻塞项。它的意义，是给这次交付补一个最后的核对步骤，尽量确保结果和前面的判断一致，而不是再引入一轮新的硬阻塞。

4.12 Uncovered Risk List 作为必备输出¶

这个 skill 不允许把无法验证的内容悄悄带过去，而是要求显式列出 Uncovered Risk List。

这层设计非常关键，因为在真实项目里，很多 Gate 不会永远处在理想状态：

• 某个工具没装
• 分支保护规则取不到
• 某项测试环境当前跑不了
• 某个安全检查有等价上游保障，但本地没有直接证据

如果没有 Uncovered Risk List，这些缺口要么被忽略，要么混在正文里，很难被 reviewer 和作者共同管理。显式列出来之后，团队才能真正讨论：

• 这个风险能否接受？
• 谁来补？
• 在补之前为什么不能标 ready？

5. 这个设计解决了哪些具体问题¶

从 SKILL.md 和评估报告可以看出，这个 skill 重点解决的是以下几类工程问题：

评估报告的数据也支持这一点：create-pr 在 3 个测试场景、34 项断言中达到 100% 通过，而 without-skill 严格通过率只有 29%；即使只看不依赖流程结构的 12 项实质性能力，with-skill 也是 100%，without-skill 只有 58%。这说明它的价值不只是"更有条理"，而是显著提升了 PR 创建这一环节的完整性和可靠性。

6. 主要亮点¶

6.1 把"开 PR"从命令动作升级为交付流程¶

这是整个 skill 最核心的亮点。它不把开 PR 看成最后一下点击，而是把它定义成进入团队评审之前的正式交付动作。

6.2 用 Gate 流程把容易漏掉的步骤固定下来¶

很多 baseline 行为其实也能做到部分检查，但非常不稳定。create-pr 的优势不在于某一条单独规则有多新，而在于它把认证、分支、质量、安全、文档、提交规范和 post-create 检查组织成了完整链路。

6.3 用 confidence 模型减少状态误判¶

confirmed / likely / suspected 这层中间抽象很有价值。它让 draft / ready 的判断不再只是一个粗暴的二元开关，而是一个有证据梯度的结果。

6.4 把 reviewer 真正需要的信息提前准备好¶

固定的 PR 正文结构和输出契约，本质上都是在帮 reviewer 节省理解成本。reviewer 不需要满篇翻找：

• 为什么这么改
• 改了哪些部分
• 风险是什么
• 测试怎么做的
• 有哪些未覆盖项

这些都被放进了固定位置。

6.5 在 baseline 最薄弱的地方提供最大增益¶

评估报告里它是通过率差异最大的 skill（+71pp）。这说明 PR 创建并不是 baseline 模型天然擅长的领域，反而特别需要这种流程化 skill 来补足。

7. 什么时候适合用，什么时候不该硬用¶

8. 结论¶

create-pr 的真正亮点，不是它会调用 gh pr create，而是它把 PR 创建前后那些最容易被忽略、最容易凭感觉处理的判断系统化了。它通过一套固定 Gate，把仓库前提、分支规范与同步检查、质量证据、安全检查、兼容性说明、提交规范、PR 结构和最终状态串成一个可核查的交付闭环。

从设计上看，这个 skill 很典型地体现了生产级交付流程的几个原则：先确认前提，再组织评审材料；先把风险写清楚，再请求别人花时间评审；先说明哪些已验证，哪些未覆盖，再决定 PR 是否 ready。 这也是它为什么在 baseline 最薄弱的 PR 创建场景里，能够带来很明显的质量提升。

9. 文档维护¶

当以下内容发生变化时，这份文档应该同步更新：

• skills/create-pr/SKILL.md 的 Gate 流程、confidence 模型、非协商规则或输出格式发生变化。
• skills/create-pr/references/*.md 中的 PR 模板、checklist 或配置示例发生变化。
• evaluate/create-pr-skill-eval-report.zh-CN.md 中支撑本文结论的关键数据发生变化。
• 项目对主分支提交流程、PR 标题规范、breaking change 说明或 rollout / rollback 约束发生变化。

建议按季度复查一次；如果 create-pr skill 有明显重构，则应立即复查。

10. 相关阅读¶

• skills/create-pr/SKILL.md
• skills/create-pr/references/pr-body-template.md
• skills/create-pr/references/create-pr-checklists.md
• skills/create-pr/references/create-pr-config.example.yaml
• skills/create-pr/references/merge-strategy-guide.md
• skills/create-pr/references/bundled-script-guide.md
• evaluate/create-pr-skill-eval-report.zh-CN.md