用途
open-a-pr 是一个面向 Pull Request(PR)创建的技能,目标是让 PR 正文在读者打开 diff 之前的三十秒内把必要信息说清楚。它同时适用于撰写 PR 描述、重写已有 PR 描述、判断 PR 正文是否过长,以及检查 PR 描述是否可读。
主要能力
该技能规定 PR 正文使用 .github/pull_request_template.md 的结构:填满每个标题、不新增标题、总字数约 250 词以内。各段落分别对应:
- What is this about?用一两句平实的话说明涉及的表层和改动。
- What problem does it solve?说明人感受到的痛点或承担的风险,而不是机制;并描述改动前的具体状况,例如人看到什么或无法做什么。
- How is this implemented?用两到五条要点向评审者说明主要改动部分及其连接方式,文件路径、工具名、路由和开关放在这里。
- What else changed?逐条列出不属于主任务的附带改动,如顺手修复、重构、重命名、依赖升级、测试或工具调整;没有则写 none。
- Release note:给使用 OpenWork 的人一句话,或写 none。该说明会直接进入变更日志收集流程;面向 CI、测试、评审工具或无人注意的重构写 none,此类 PR 将不进入变更日志;删除或改变用户依赖的功能必须写说明。
- Evidence:指出证明改动的 spec,并用一行说明其 before → after 展示什么;不复制结论、SHA、截图或链接。没有 spec 改动时需用一行说明原因,例如仅做类型检查和构建。UI 改动需在末尾写一行 Design: P3, S4, C6。
标题需使用 conventional commit 风格、祈使语气、不超过 70 个字符。
使用方式
发起 PR 前应自行运行相关 spec(run-tests),或让 CI 在 PR 头部运行 PR 变更的 spec 并保留记录作为产物:
gh workflow run pr-proof.yml --ref <branch> -f pr=<number>
创建和编辑 PR 的命令为:
gh pr create --base dev --title "<type>(<scope>): <change>" --body-file /tmp/pr-body.md gh pr edit <n> --body-file /tmp/pr-body.md
建议先写好正文文件,再以评审者视角通读;如果某段落让人需要滚动,就删减。合并后,开发推送会运行新增或改动的每项证明以及每个核心旅程。证据绑定到具体提交:rebase 或 cherry-pick 后需在新头部重跑 spec,不能引用旧运行结果。红色证据应通过修正 spec 或代码并重跑解决,而不是在正文中叙述。
适用场景
适用于创建新 PR、重写 PR 描述、评估 PR 正文是否过长或不可读,以及需要控制 PR 描述信息密度、突出改动前状况与证据的团队协作场景。
限制
该技能面向特定仓库的模板与工作流,资料未提供通用化配置或跨平台适配说明。正文不应包含根因叙述、套件计数与 CI 矩阵、镜像摘要、worktree 设置、凭证说明、其他 PR 的失败、风险与回滚等模板化内容。关于收费、价格、平台支持等事实,资料暂未提供。