pr-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Writer

PR 撰写指南

Write the PR body as a cover note for reviewers, not a changelog, template, validation log, or file-by-file summary.

PR正文应撰写为面向评审者的说明性内容，而非变更日志、模板、验证日志或逐文件摘要。

Inspect the Change

检查变更内容

Requires authenticated

gh

. Inspect the current branch, working tree, PR, base branch, commits, and full diff:

bash

git branch --show-current
git status --porcelain
gh pr view --json number,title,body,url,baseRefName,headRefName
gh repo view --json defaultBranchRef

gh pr view

reports that no PR exists, continue with first-time PR creation. For an existing PR, use its

baseRefName

; otherwise use the repository default branch. Set

BASE

, then inspect:

bash

git log "$BASE"..HEAD --oneline
git diff "$BASE"...HEAD

If on

main

master

, create a feature branch first. Ensure intended changes are committed and review the whole branch diff, not only the latest commit or existing PR text.

需要已认证的

gh

工具。检查当前分支、工作区、PR、基准分支、提交记录以及完整差异：

bash

git branch --show-current
git status --porcelain
gh pr view --json number,title,body,url,baseRefName,headRefName
gh repo view --json defaultBranchRef

如果

gh pr view

显示不存在PR，则继续创建新PR。对于已存在的PR，使用其

baseRefName

；否则使用仓库的默认分支。设置

BASE

变量后，执行以下检查：

bash

git log "$BASE"..HEAD --oneline
git diff "$BASE"...HEAD

如果当前处于

main

或

master

分支，请先创建功能分支。确保预期的变更已提交，并查看整个分支的差异，而非仅查看最新提交或现有PR文本。

Core Rules

核心规则

Describe concrete changed behavior, affected surfaces, and reviewer impact before implementation detail.
Explain motivation, risk, tradeoffs, migration, or review focus only when useful.
Use the smallest structure that makes the change easier to review.
Replace internal prompt or process terminology with specific behavior.
When refreshing a PR, rewrite around the current full diff without narrating review history.

在描述实现细节之前，先说明具体的变更行为、受影响范围以及对评审者的影响。
仅在必要时解释变更动机、风险、权衡方案、迁移方法或评审重点。
使用最简洁的结构，让变更更易于评审。
用具体的行为描述替代内部提示或流程术语。
更新PR时，围绕当前完整差异重写内容，无需叙述评审历史。

Titles

标题规范

Use

<type>(<scope>): <subject>

<type>: <subject>

Allowed types:

feat

fix

ref

perf

docs

test

build

ci

chore

style

meta

license

, and

revert

Describe the dominant full-branch change with the narrowest accurate type and scope.
Use
```
!
```
only when the change breaks an external contract, and explain the affected surface in the body.
Avoid vague subjects such as
```
update
```
,
```
cleanup
```
,
```
misc
```
,
```
fix stuff
```
, or
```
address feedback
```
. Do not add a trailing period.
Keep an existing title only when it still describes the whole diff.

采用

<type>(<scope>): <subject>

或

<type>: <subject>

格式。

允许的类型包括：

feat

、

fix

、

ref

、

perf

、

docs

、

test

、

build

、

ci

、

chore

、

style

、

meta

、

license

和

revert

。

用最精准的类型和范围描述分支的主要变更。
仅当变更破坏外部契约时使用
```
!
```
，并在正文中说明受影响的范围。
避免使用模糊的主题，如
```
update
```
、
```
cleanup
```
、
```
misc
```
、
```
fix stuff
```
或
```
address feedback
```
。结尾不要加句号。
仅当现有标题仍能完整描述所有差异时，才保留该标题。

Body Shape

正文结构

Choose the minimum useful shape:

Change	Include
Small or obvious	One concise paragraph without headings.
Feature, bug fix, or refactor	Changed behavior and effect; add root cause, unchanged behavior, or non-obvious approach when relevant.
Contract or breaking change	Affected API, schema, payload, config, permission, storage, or CLI surface; include compatibility and migration guidance.
Operational, visual, or workflow change	User/operator effect, measured impact, failure modes, or flow when useful.
Broad, generated, or cross-cutting change	Organizing principle, why the breadth is necessary, and where review should start.

Default:

markdown

<What changed and what effect it has.>

<Why the approach, risk, migration, or review focus matters, if not obvious.>

For review-feedback updates, describe the resulting PR as a whole rather than the sequence of revisions.

选择最简洁实用的结构：

变更类型	需包含内容
小型或明显变更	一段简洁的段落，无需标题。
功能新增、Bug修复或重构	变更行为及影响；必要时补充根本原因、未变更行为或非直观实现方案。
契约变更或破坏性变更	受影响的API、schema、payload、配置、权限、存储或CLI范围；包含兼容性说明及迁移指南。
操作、视觉或工作流变更	用户/操作者影响、可衡量的效果、故障模式或流程（必要时）。
大范围、自动生成或跨模块变更	组织原则、大范围变更的必要性说明，以及评审的起始点。

默认格式：

markdown

<变更内容及其影响。>

<若变更方案、风险、迁移方法或评审重点并非显而易见，则说明其必要性。>

针对评审反馈的更新，应描述最终的PR整体内容，而非修订的先后顺序。

Reviewer Aids

评审辅助内容

Use an aid only when it reduces reviewer reconstruction work:

A compact before/after or interface example for changed contracts.
A small Mermaid diagram for async flows or state transitions.
A screenshot or recording note when visual evidence exists.
A rollout, compatibility, risk, or review-order note when reviewers or adopters need it.

Introduce an artifact with one sentence explaining what reviewers should notice. Omit it when prose is clearer.

仅当辅助内容能减少评审者的理解成本时使用：

针对契约变更，提供简洁的前后对比或接口示例。
针对异步流程或状态转换，提供小型Mermaid图。
若有视觉证据，提供截图或录制说明。
当评审者或使用者需要时，提供发布计划、兼容性说明、风险提示或评审顺序建议。

用一句话介绍辅助内容，说明评审者应关注的要点。若文字描述更清晰，则无需添加辅助内容。

Boundaries

内容边界

Do not add default
```
Summary
```
,
```
Changes
```
, or
```
Test Plan
```
sections.
Omit routine validation unless it changes risk assessment or explains meaningful regression coverage. For docs, skills, copy, or config changes, omit it by default.
Do not paste commands, CI logs, validation dumps, commit logs, placeholders, or exhaustive file lists.
Never include customer or organization names, user emails, support ticket contents, secrets, or PII.
Use issue references only when verified from user input, branch names, commits, PR discussion, or tracker output.
```
Fixes <issue>
```
closes;
```
Refs <issue>
```
only links.

不要添加默认的
```
Summary
```
、
```
Changes
```
或
```
Test Plan
```
章节。
除非常规验证会改变风险评估或说明有意义的回归覆盖范围，否则省略常规验证内容。对于文档、技能、文案或配置变更，默认省略验证内容。
不要粘贴命令、CI日志、验证输出、提交记录、占位符或详尽的文件列表。
绝对不要包含客户或组织名称、用户邮箱、支持工单内容、机密信息或个人身份信息（PII）。
仅当从用户输入、分支名称、提交记录、PR讨论或跟踪系统输出中确认后，才引用问题。
```
Fixes <issue>
```
用于关闭问题；
```
Refs <issue>
```
仅用于链接问题。

Create or Update

创建或更新PR

Create new PRs as drafts. Write the body to a temporary Markdown file, then run:

bash

gh pr create --draft --title '<title>' --body-file /tmp/pr-body.md

Update existing PRs with

gh api

bash

gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER \
  -f title='<title>' \
  -F body=@/tmp/pr-body.md

Refresh the title and body when follow-up commits materially change scope, approach, breaking behavior, risk, migration, or review expectations. Skip typo-only, formatting-only, and rename-only follow-ups.

新PR以草稿形式创建。将正文写入临时Markdown文件，然后执行：

bash

gh pr create --draft --title '<title>' --body-file /tmp/pr-body.md

使用

gh api

更新现有PR：

bash

gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER \\
  -f title='<title>' \\
  -F body=@/tmp/pr-body.md

当后续提交实质性改变了范围、方案、破坏性、风险、迁移方法或评审预期时，更新PR标题和正文。仅修正拼写、格式或重命名的后续提交无需更新。

Examples

示例

Small change:

markdown

The AI Customizations section now starts collapsed so it does not consume
sidebar space before users need it. Expanding it preserves the existing saved
preference behavior.

Breaking contract:

markdown

Run logs now emit chunk-level records instead of one skill-level record.
Consumers that read top-level `findings` must iterate over
`chunk.findings` for each record.

Before:

```json
{"skill": "security-review", "findings": [...]}
```

After:

```json
{"schemaVersion": 1, "chunk": {"index": 1, "findings": [...]}}
```

小型变更示例：

markdown

AI自定义部分现在默认折叠，避免在用户需要前占用侧边栏空间。展开该部分时仍保留原有的偏好设置保存行为。

破坏性契约变更示例：

markdown

运行日志现在输出块级记录，而非单个技能级记录。读取顶层`findings`的消费者必须遍历每条记录的`chunk.findings`。

变更前：

```json
{"skill": "security-review", "findings": [...]}
```

变更后：

```json
{"schemaVersion": 1, "chunk": {"index": 1, "findings": [...]}}
```
````",