preparing-prs
Use when creating or updating GitHub pull request titles and bodies, especially when the current PR text is empty, vague, commit-driven, or inconsistent with the established PR structure
Source facts
- Repository
- lexmount/website-skills
- Last source activity
- May 21, 2026 at 13:27
- Detected SKILL.md language
- Chinese
- Stars
- 1
- Forks
- 0
Install options
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Review the source files
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Showing SKILL.md
SKILL.md
Source instructions · Read-only preview- name
- preparing-prs
- description
- Use when creating or updating GitHub pull request titles and bodies, especially when the current PR text is empty, vague, commit-driven, or inconsistent with the established PR structure
# Preparing PRs
## Overview
PR 文案应当是"变更摘要"，不是"提交记录翻译"。正文按本 SKILL 约定的三段式组织，信息密度以"能让 reviewer 快速抓住主题与风险边界"为准。标题默认使用英文。
## When to Use
- 新建 PR，需要整理标题和正文
- 修改已有 PR，发现当前标题或正文质量不够
- 同一 `head/base` 已经存在 PR，需要更新而不是重复创建
- 用户明确要求整理或规范化 PR 文案
不要在这些场景使用：
- 只做本地提交，不准备提 PR
- 只处理 merge / cleanup，不改 PR 文案
- 只需要跑验证，不需要整理 PR 标题正文
## Decide Whether to Open a PR First
本 SKILL 只承担"已决定要出 PR"之后的文案整理，不承担"要不要出 PR"的选型。如果用户还没明确，要先走 `finishing-a-development-branch`（或同等的"分支完结"流程），让用户在"本地 merge / push 并开 PR / 保留分支 / 丢弃"中选定后再回到本 SKILL。
可以直接进入后续步骤的场景：
- 用户明确说"提 PR / 开 PR / 创建 PR / 更新 PR"
- 分支已存在对应 PR（走后面的 "Existing PR Rule"）
- 用户要求整理或规范化 PR 文案
## Branch & Commit Confirmation
开始为新 PR 起草标题/正文之前，必须先和用户对齐分支范围与提交清单，不得直接假设 `main` / 当前分支是目标：
- **先问 head 和 base**：显式向用户确认"这个 PR 从哪个分支提到哪个分支"，即使当前 checkout 的分支看起来显然
- **列出两侧最新状态给用户审核**：
- `head` 分支 tip 的短 SHA 和 commit message
- `base` 分支 tip 的短 SHA 和 commit message（先 `git fetch origin <base>`，以远端为准，不信任本地可能落后的引用）
- `base..head` 的全部未合入提交，标注其中哪些是 merge commit、哪些是空 message 等异常 commit
- 如有 squash-merge 过的历史遗留（SHA 在 head 但 patch 已在 base 上），用 `git cherry -v <base> <head>` 或净 `git diff --stat <base>..<head>` 对比说明，避免用户误解规模
- 用户明确确认 head、base、提交范围后，再进入起草阶段
## Core Rules
### 1. 先读真实变更，再写 PR
写 PR 文案前至少读取：
- 当前分支相对 base 的全部未合入提交
- 当前分支相对 base 的实际 diff
- 若仓库维护了设计文档、执行计划、决策记录（例如 `docs/`、`design/`、`adr/`、`rfcs/` 等目录）且与本次改动相关，一并读取
- 当前会话里真实跑过的验证结果
不要只看其中一个提交，也不要直接把 commit message 拼成 PR 文案。标题和正文都必须覆盖"当前分支相对 base 仍未合入"的完整变更范围。
### 2. 标题规则
- 标题默认使用英文
- 以fix或feat为开头
- 标题以动词开头，使用祈使/现在时（`Add X`、`Fix Y`、`Refactor Z`、`Support …`），避免过去式/完成时（`Added X`、`Fixed Y`、`X has been fixed`）
- 标题总结"这一组未合入改动的主题"，不是重复单个 commit message
- 如果分支包含几类相关改动，选一个 umbrella title，把细节放到正文
### 3. 正文固定结构
正文默认使用以下三段（section 名按仓库正文语言选用对应翻译，例如中文仓库用 `变更概述 / 主要改动 / 影响说明`）：
```
### Summary
### Changes
### Impact
```
另有两段 **optional** 小节，默认启动`links`而不启动`Approach`（但可以询问用户后启用），并保持固定顺序：
- `### Approach`（放在 `### Changes` 之前）—— 当本 PR 含技术选型争议、非显然的方案权衡或推翻了上一轮设计时启用；只记决策与 tradeoff，不复述"改了哪些代码"。典型触发：reviewer 之后会问"为什么选 A 不选 B"
- `### Links`（放在 `### Impact` 之后，即正文最末）—— 当本 PR 引用外部资料（设计文档 / issue / Slack thread / Wiki 等）≥ 2 条时启用；单条引用直接内联在 `Summary` 里即可，不必单列一段
要求：
- `Changes` 拆成 2-4 个 `#### 1.` / `#### 2.` 主题小节
- 每个小节只讲一类改动，不做文件清单堆砌
- `Impact` 讲行为、边界、风险变化，不重复"改了哪些文件"
- `Approach`（若启用）按"方案 / 替代方案 / 取舍原因"组织，不超过 3-5 句；**不要**复述 `Changes` 的内容
- `Links`（若启用）用标准 Markdown 列表 `- [标题](url)`；单行一条，不加长段描述（原因放回 `Summary` 或 `Approach`）
- 验证段落（如 `Verification`）不是默认必填；只有用户明确要求，或当前 PR 特别需要强调验证边界时才单列出来
- 如果需要写验证段落，必须使用标准 Markdown checklist：完成项写 `- [x]`，未完成/阻塞项写 `- [ ]`，不要使用 `- [√]`
- 为了让结果更醒目，每个 checklist 项后面要补一行结果标识，并与 checklist 项之间保留一个空行；通过写 `✅ passed: ...`，失败写 `❌ failed: ...`，阻塞写 `❌ blocked: ...`（语言跟随正文）
### 4. 正文写法
- 正文语言跟随当前仓库已有 PR 的惯例；若无明显惯例默认中文，不要中英文混写
- 先写整体摘要，再写分组细节
- 摘要和分组必须覆盖当前分支相对 base 的全部未合入提交，不能只挑其中一部分
- 适度引用关键路径或模块名，使用实际受影响的具体文件路径
- 只写和这次 PR 相关的事实，不补无依据推断
## Edge Cases
- 分支只有一个 commit：仍然用三段式结构写正文，不可直接复制 commit message 当标题。单个 commit 的标题也应总结变更主题而非用 commit message 原文
- 多人协作分支（多人 commit 混合）：标题用 umbrella title 概括全部改动，正文 `Changes` 按主题（而非按人）分组，尽量归纳为 2–4 个主题小节
- 纯文档 / 配置变更（无代码逻辑改动）：同样遵循三段式结构，`Impact` 可简写为"无行为变化"或"仅文档更新"
- 紧急修复 / hotfix：三段式仍然适用，但此时 `Impact` 应特别强调风险和回滚策略
## Existing PR Rule
如果同一 `head/base` 已经存在 PR：
- 更新已有 PR
- 不创建重复 PR
- 如果本地分支内容变了，先同步分支，再改 PR 标题和正文
## GitHub CLI Workflow
优先使用下面的稳定命令序列，减少无效尝试：
1. **定位仓库与 PR**
- `gh repo view --json nameWithOwner -q .nameWithOwner`
- `gh pr list --head <head> --base <base> --json number,title,url,state`
- `gh pr view <number> --json number,title,url,state,headRefName,baseRefName,commits`
2. **读取评论**
- 普通评论 / review summary：`gh pr view <number> --comments --json comments,reviews`
- inline review comments：`gh api repos/<owner>/<repo>/pulls/<number>/comments --paginate`
3. **创建 / 更新 PR**
- 创建：`gh pr create --base <base> --head <head> --title "<title>" --body-file <file>`
- 更新正文：`gh pr edit <number> --body-file <file>`
- 提交修复说明：`gh pr comment <number> --body "<summary>"`
4. **回复 inline comment**
- `gh api repos/<owner>/<repo>/pulls/<number>/comments/<comment_id>/replies -f body="<reply>"`
- 不要使用 `repos/<owner>/<repo>/pulls/comments/<comment_id>/replies`；该路径会 404。
PR body 草稿仍写到 `.git/pr_body_<slug>.md` 或同等本地临时文件，避免 shell quoting 破坏 Markdown。
## Review Feedback Workflow
当用户要求"根据 PR 评论继续修改"或同等意思时：
1. 读取普通评论、review summary、inline review comments。
2. 对每条评论做技术判断：正确就修；不正确或与用户先前决策冲突就用技术理由回复。
3. 修复后重新运行相关验证。
4. 提交并推送当前 PR 分支。
5. 按需更新现有 PR body 中的变更和验证结果。
6. 提交一个 top-level PR comment，总结本轮修复与验证。
7. 回复已处理的 inline comment 线程。
### Review follow-up 优先级
用户明确要求处理 PR review（例如"根据评论继续修改"）时，这条指令已经授权本轮必要的 PR 维护动作：推送修复、更新现有 PR body、发布处理摘要、回复 inline thread。此时不再套用下面的草稿确认流程。
仍需单独确认的动作：merge、close PR、force push、删除分支、发布版本、对外通知等不可逆或高风险动作。
## Draft Confirmation
本节适用于新建 PR，或用户单独要求整理 / 改写 PR 文案但尚未授权提交。`gh pr create` / `gh pr edit` 执行前，必须先把拟定的标题和正文写成 `.git` 下的临时文件，并将路径贴给用户，待用户确认并明确同意后再实际提交：
- 若用户要求修改，先改草稿并再次写入临时文件，寻求用户确认和同意后再提交，不要边改边提交
- 未得到用户明确同意（例如"可以"、"提交"、"就这样"）前，不得执行 `gh pr create` / `gh pr edit`
- 仅当用户在当前会话明确授权"直接提交无需再确认"，或任务属于上面的 review follow-up，才可跳过此步
## Template
最小版（只有必选段）：
```md
### Summary
This PR ...
### Changes
#### 1. ...
- ...
#### 2. ...
- ...
### Impact
- ...
```
含 optional 段的完整版（只在触发条件满足时加）：
```md
### Summary
This PR ...
### Approach
- 为什么选 A 而不是 B：...
- 主要 tradeoff：...
### Changes
#### 1. ...
- ...
#### 2. ...
- ...
### Impact
- ...
### Links
- [设计文档](url)
- [Issue](url)
```
## Common Mistakes
- 用 commit message 直接当 PR 标题
- 无视仓库已有 PR 惯例，机械添加或强制去掉前缀
- body 只写远端已推送的一小段改动，漏掉当前分支其他未合入提交
- 机械补一个验证段落，但里面没有任何必要信息
- 正文为空，或者只有一句话
- 分支已经有 PR，却又重复创建一个新的
- 标题或正文残留 `Co-Authored-By: Claude`、`🤖 Generated with Claude Code`、`Generated with Claude Code` 等 AI 署名或工具标记
## Verification Checklist
PR 提交前，必须对本次 PR 涉及的所有 commit 执行对应的验证（例如单元测试、lint、类型检查），并在 PR 评论或输出中显式报告结果。若正文包含 `Verification` 小节，使用标准 Markdown checklist，并在每项下方补结果标识：
```md
- [x] `<项目对应的测试/验证命令>`
`✅ passed: 34 tests passed`
- [ ] `<其他验证命令>`
`❌ blocked: ModuleNotFoundError: ...`
```
要求：
1. 列出当前 PR 所有 commit 涉及的代码文件和模块
2. 根据仓库的测试约定定位对应的测试文件或命令（例如 pytest、jest、cargo test、go test、`npm test` 等）
3. 逐个运行相关验证命令，记录结果（`- [x]` / `- [ ]` + 下一行结果标识和原因）
4. 如果某模块没有现有测试覆盖，标注为 `- [ ] no existing tests`，并补 `❌ blocked: no reusable tests`
5. 验证全部通过后方可提交 PR；存在失败需先修复或在 PR 中说明原因
View on GitHub