SuperAPI AI 工具集

pr-writer

编程与开发

查看项目

更新于 10-28 20:12

技能介绍

PR Writer 是一个面向开发者的技能,用于在创建、编写或起草 Pull Request(PR)或 Merge Request 时,生成符合规范、可读性高的 PR 标题与描述。其定位是扮演一位有十年以上经验的高级工程师,以尊重审阅者时间为原则,直接说明改动存在的理由、解决的问题以及审阅者需要了解的信息,不使用填充性内容。

主要能力与使用方式:

一、检查暂存变更。技能会先运行 git diff --cached --stat 检查是否存在已暂存但未提交的改动;若有,则暂停并询问用户是否先提交,待用户确认后才继续。

二、收集上下文。运行随附的 diff 脚本获取基础分支、提交记录、改动文件与完整 diff;若提交信息与 diff 不足以说明改动动机,可查看分支上近期提交补充上下文;若提交信息引用了 GitHub issue(如 #123、fixes #456),可用 gh issue view 获取 issue 标题与描述作为动机补充;同时结合当前对话中作者做出的设计决策、权衡与被否决的方案,尤其用于「Why」和「Risks」部分。

三、应用项目约定。读取 PR 模板(.github/PULL_REQUEST_TEMPLATE.md)作为结构骨架,按顺序填写其中每个部分;读取 PR 指南(team/PR.md)作为内容质量的依据,其优先级高于通用约定。当 PR 引入或修改公共 API 时,需在模板的 Description 块中、动机之后添加 Public API Changes 部分并附代码片段;内部重构、缺陷修复、纯文档或 CI 改动则省略该部分。

四、撰写 PR。标题须遵循 Conventional Commits 格式:<type>(<optional scope>): <subject>,subject 以小写字母开头,有效类型包括 feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert、design。Why 部分以动机开篇,说明哪里坏了、缺了什么、有什么业务或用户需求,通常是最长的一部分。What 部分用一两句话说明审阅者无法一眼推断的方法或设计决策,不复述 diff 中的文件、导入、行号、测试或 mock 改动。篇幅需与 diff 规模匹配:一到几行的改动通常只需一两句话;常规功能或修复为数段短文,一分钟内可读完;简短片段优于冗长句子。Risks / Callouts 部分列出审阅者应重点核查的事项,如迁移问题、向后兼容、性能影响;若确实无可提示则省略。

五、自我审阅。输出前以审阅者视角重读 Description,明确本 PR 中读者无法从 diff 获取的核心事实,逐句删去复述 diff、重复代码已显示内容或仅作安抚的句子,并核对篇幅与 diff 规模是否匹配。

规则与限制:不虚构 diff 中不存在的改动;对动机、范围或意图不确定时询问用户而非猜测;不逐一列出所有改动文件;不在 PR 任何位置叙述测试、fixture 或 mock 的改动,Testing 部分只说明运行了什么及其覆盖范围;琐碎改动(如拼写修正、依赖升级)保持描述相应简短;遵循所选 PR 指南中的写作原则与反模式;正文不按固定列宽硬换行,每段写成连续一行由 Markdown 自动软换行;完整填写模板所有部分,不跳过或重排;模板中的复选框默认勾选(- [x]),但与文档更新或文档示例相关的复选框保持未勾选,交用户手动确认。

输出方面,最终 PR 以单个 Markdown 代码块输出以便直接复制,同时将 PR 正文写入 .local/pr-body.md(必要时创建 .local/ 目录),若该位置已有无关工作的描述则覆盖。

适用场景:开发者在提交 PR 前需要快速生成结构规范、动机清晰的标题与描述;需要按项目模板与团队指南统一写作风格;需要将对话中的设计权衡与关联 issue 信息融入 PR。限制:依赖 git 与 gh CLI 环境,gh 未认证或不可用时会告知用户并基于现有上下文继续;不适用于非代码托管平台上的 PR 流程(资料未提供相关信息)。