用途:在起草或编辑 Pull Request 标题与正文时,按照资深工程师的标准写作,让同事一眼看懂改了什么。适用于运行 gh pr create 之前,或修改已有 PR 正文时。
主要能力与写作要求: 标题用平实语言陈述实际改动,沿用仓库已有的约定前缀,如 [fix] <Title>、[feat] <Title>、[chore] <Title>、[docs] <Title>;如用户给出 issue id 则加后缀,如 [fix] <Title> [AGE-1234];标题用一般现在时的主动意图表述,控制在约 70 字符以内。
正文结构:除极小改动外,采用 ## Context(一到两句,先写用户或同事能察觉的症状,再讲根因)、## Changes(平实解释改动,数据形态、签名或行为变化时给出具体前后对比)、## Tests / notes(简短列出本地验证内容和需注意之处)、## What to QA(仅用户可见改动,给出手动测试步骤)。标题可按情境调整,但顺序保持先现象或意图、再改动、最后验证。
写作规则:用具体前后对比而不是复述 diff;删除泛泛的 Summary/Overview、复选框式清单、逐文件罗列、营销词(comprehensive、robust、seamlessly、leverage、powerful)以及凑数条目。禁止使用破折号,改用句号、括号或分号;使用主动语态、短句、完整句子;不过度使用加粗和项目符号;语言约相当于十一年级英语,除不可避免的技术术语。
仓库模板说明:GitHub 会用 .github/PULL_REQUEST_TEMPLATE.md 预填正文,包含 Summary、Testing、Demo、Checklist、Contributor Resources,但这不是本仓库 PR 的样子,应以第 2 节结构替换。其中 Demo 仍适用:UI 改动需要真实运行该分支的应用截图,不得用稿图、组件测试脚手架或重建页面替代;无法运行应用时应说明演示缺失及原因。Testing 的实质内容保留在 ## Tests 标题下。若作者是仓库核心维护者,可去掉 Checklist 和 Contributor Resources。
Tes 区内容:本地运行了什么(如 pnpm test、pytest tests/...、在 /observability 手动检查 UI)、评审者应留意的地方(脆弱区域、后续 PR 未包含的工作)、迁移或发布说明。没有真实内容就省略该节,空标题比没有更糟。
What to QA 区:仅用于用户可见改动。面向了解产品的测试者,跳过基础知识,指明具体页面与流程,每项检查一行写清去哪、做什么、应看到什么,并包含最可能被破坏的回归项;若检查需要准备(预置项目、旧记录、功能开关)则在同行说明。纯重构、CI、文档改动不需要该节。
审阅者 30 秒测试:完成前自问,30 秒后评审者是否知道背景和改了什么;形态或行为变化处是否有具体前后对比;是否删掉了所有不该保留的句子;是否检查了破折号和营销词。任一为否就先修改再推送。