Write a PR description that helps reviewers

Goal: Turn a messy change into a clear pull-request summary—then you verify every file and test step before you open the PR.

Best for: First PRs, small-team reviews, hotfix communication.

Reviewers should not reverse-engineer your intent from a 40-file diff. AI can draft Why / What / How to test / Risk. It must not invent files, tickets, or test results you never ran.

Why beginners skip this

“Just fix it” on “Turn a messy change into a clear” skips the explain pass that catches the wrong layer The fix is one dated pass/fail on a live artifact for “Turn a messy change into a clear”—not another bookmark. If you cannot name what you will refuse this week, you are still collecting titles

Step 1 — PR template prompt

Do this step with a real artifact open—not from memory.

From this diff summary, write a PR description:
## Why
## What changed
## How to test

## Risk
Rules:
- Do not invent files, tickets, or screenshots I did not mention
- Keep under 180 words
- How to test must be steps I can run
- If tests were not run, say Not run yet
Summary:
[paste]

Step 2 — Null-check hotfix

Messy branch: 12 files including accidental .env.example tweak.
PR body must list every file; flag .env.example for remove-from-PR.

Step 3 — Human gate before “Create pull request”

• Diff still matches the What section?
• You actually ran at least one How-to-test step?
• Secrets absent from the PR body and screenshots?

Tighten this PR body: remove any claim about CI or coverage I did not state. Keep under 150 words.

Tighten this PR body. Remove any claim about CI or coverage I did not state. Keep under 150 words. Keep Why/What/How-to-test/Risk.
Draft:
Why: cart crashed when coupon missing.
What: null check in checkout.ts + unit test.
How to test: npm test checkout.test.ts
Risk: other coupon edge cases.
(Do not add “CI green” or coverage %.)

Diff in, vibes out

Draft PR text from the diff summary you paste. Delete invented ticket numbers.

How-to-test must be runnable

“Works for me” is not a test plan. Write the command, the click path, or “Not run yet.” Reviewers trust an honest Not run more than a fake green check.

PR leaves console.log of user email.
Body must flag risk + remove-before-merge checklist + honest file list.
Context: real workstream this week (Asia/Shanghai). Name actual files/people.
Constraints: no invented metrics/owners/prices; label Unknowns; stop before send/delete/pay.
Done check: I can mark pass/fail in one minute on the output.

Red flag

No risk section; “tests passed locally” with no command; description disagrees with the diff—rewrite.

Save this card

Card: PR text from the diff you paste; never invent tickets, CI, or mystery owners. Keep this beside the tool; read before you start.

1. What I shipped: ___ 2. What I refused: ___ 3. What I will never-do again: ___ (date: Asia/Shanghai)

• [ ] Tools/writes paused
• [ ] Refuse-line dated
• [ ] Artifact path saved
• [ ] Next link chosen (or stop)

Before you start

Open the failing test, diff, or ticket for “Turn a messy change into a clear.” Keep secrets out of the chat. Have the file path you will name. Guide: code-pr-description-that-helps. If you only have a blank practice box, stop and fetch the real job first.

• Goal in one line: ___
• Allowed tools: ___
• Forbidden: ___
• Human approve needed for: ___

How to use this week

For your next PR, paste a short diff summary (not vibes) and ask for Why / What / How to test / Risk under 180 words. Delete any invented Jira IDs or “CI green” claims you did not run. Ship the artifact out of chat (doc/PR/note) so the week leaves a file, not only a thread—date it Asia/Shanghai.

Mid-week cost check: if this habit disappeared tomorrow, what breakages would you notice in 24 hours? Write one line (Asia/Shanghai).

Pitfalls

Temptation: skip the habit for code-pr-description-that-helps to “save five minutes.”
Job still: Turn a messy change into a clear
Do the smallest correct pass: Done visible · one checkable artifact · Unknowns labeled [?].
Boundaries: draft only; no silent send; no invented metrics.
Return: the artifact + the refuse-line you said aloud.

Practice now

Live card: one real code change under “Write a PR description that helps reviewers”—diff-only + test note (Asia/Shanghai).

Today: take one real change. Fill Why (user-visible), What (files you touched), How to test (commands or clicks), Risk (one honest line). Ban ticket numbers you do not have.

Today card (copy) — code-pr-description-that-helps: 1. Artifact I will produce: ___ 2. Pass/fail check: ___ 3. Refuse-line if tempted to skip verify/send: ___ (date: Asia/Shanghai) 4. One never-do from this guide: ___

• [ ] Artifact path written
• [ ] Refuse example would say "yes"
• [ ] Dated Asia/Shanghai

One sentence takeaway

PR text from the diff you paste; never invent tickets, CI, or mystery owners. This week: ship one PR with motive / change / test / risk filled.

• You can point to a dated refuse-line
• You have one artifact path from tonight
• You can teach the red flag in one sentence

Next

Code review checklist · Explain then change · Tests with the model · Minimal repro first

Pair with today: open the first Next link (claude-code-review-checklist) only after you dated a refuse-line for this guide (Asia/Shanghai).

写出帮到审阅者的 PR 说明

目标： 把杂乱改动收成清楚的 Pull Request 说明——打开 PR 前，你亲自核对每个文件与测试步骤。

适合： 第一次提 PR、小团队审阅、hotfix 沟通。

审阅者不该从 40 个文件的 diff 反推你的意图。AI 可以起草 Why / What / How to test / Risk。但绝不能编造你没提过的文件、工单或「已跑通」的测试结果。

为什么新手跳过

丢一句「感觉 LGTM」或指望评审从几十个文件的 diff 反推意图，是在浪费大家时间。紧凑写清 Why / What / 如何测 / 风险，才是对评审真正的礼貌。

步骤 1——PR 模板提示词

用真实材料做这一步——不要凭记忆。

根据这段改动摘要，写 PR 说明：
## Why（为什么）
## What changed（改了什么）
## How to test（如何测试）
## Risk（风险）
规则：
- 不要编造我没提的文件、工单或截图
- 180 词以内
- 测试步骤必须是我能跑的
- 若还没跑测试，写 Not run yet
摘要：
[粘贴]

步骤 2——空值检查 hotfix

改动：修复 session refresh；文件含 session.ts 与测试；无 infra 变更。
写 PR 正文：摘要、文件、风险、测试计划。测试覆盖率别瞎编。

步骤 3——点「写出帮到审阅者的 PR 说明」前的人闸

• Diff 是否仍与 What 一致？
• 你是否真跑过至少一步 How to test？
• PR 正文与截图里是否没有密钥？

收紧这篇 PR 正文：删掉任何我没说过的 CI/覆盖率声明。150 词以内。

分支很乱：12 个文件，还误改了 .env.example。
PR 必须列出每个文件，并把 .env.example 标成「移出本 PR」。

用 diff，别凭感觉

根据粘贴的 diff 摘要起草 PR。删掉编造的工单号。

现实核对

把这份指南放在真实任务旁边。若说不出任务，先选一件再往下读。

「如何测」必须能照做

「我这边可以」不算测试计划。写命令、点击路径，或老实写「尚未跑」。评审更信任诚实的尚未跑，而不是假的绿灯。

红旗

描述里没有风险栏；测试只写「本地过了」却无命令或环境。描述与 diff 对不上——整段重写。无风险说明就不点「请求审查」，先补齐四行。

保存这张卡

卡面：动机 / 改动 / 测试 / 风险。开 PR 前看卡；无风险栏不点审；测试无命令就停。缺检查项就先补卡，再允许继续。

打开你真正会用的账号/项目。准备好与「写出帮到审阅者的 PR 说明」相关的真实材料（不要空白练习框）。

默认姿态：在人确认发送/写入之前只出草稿。授予新工具前，先写一条带日期的拒做句（Asia/Shanghai）。

1. 我交出了：___ 2. 我拒绝了：___ 3. 我永不再做：___（日期：Asia/Shanghai）

• [ ] 工具/写入已暂停
• [ ] 拒做句已标注日期
• [ ] 成品路径已存
• [ ] 已选下一步（或停）

本周怎么用

本周每条 PR 用四行模板；无测试说明不点审。把过/不过写进笔记并注明日期（Asia/Shanghai）。

常见坑

任务：Turn a messy change into a clear
场景要点：缺陷单/diff 打开；练习编号 3/4。
边界：仅草稿；未知 [?]；禁止悄悄发送；禁止编造指标。
返回：可检查产出 + 过/不过理由一行。

任务：Turn a messy change into a clear
场景要点：缺陷单/diff 打开；练习编号 4/4。
边界：仅草稿；未知 [?]；禁止悄悄发送；禁止编造指标。
返回：可检查产出 + 过/不过理由一行。