描述写给谁看
一份好的 PR 描述服务三类读者：评审者（现在就要理解这次改动）、发布同学（上线时要知道影响与回滚方式）、未来的自己（排障时要知道当时为什么这么改）。描述写清背景、改动与验证，评审者就不必从 diff 里反推上下文，来回轮次自然会减少。
基本信息
| 必要要素 | 背景与动机、改动内容与取舍、验证方式、风险与回滚 |
|---|---|
| 写法建议 | 先写结论再写细节，关键决策单独列出 |
| 长度 | 与改动复杂度匹配：小改动几句话，大改动分节写 |
| 配套信息 | 关联工单、影响范围、需要额外注意的评审点 |
PR 描述模板
PR 描述模板
## 背景
为什么需要这个改动（问题、影响面）
## 改动
- 关键变化与设计取舍
- 明确不在本次范围的内容
## 验证
- 执行的测试与命令、结果
- 手工验证步骤（如可复现）
## 风险与回滚
- 风险点、监控项、回滚方式把描述写实的要点
- 验证部分要能核对：写清跑了什么命令、看到什么结果。
- 明确不在本次范围的内容，避免评审者追问为什么没做某件事。
- 列出需要重点评审的地方：哪几处判断最没把握，请对方重点看。
- 涉及兼容性或数据变更时，单独说明影响面与回滚方案。
- 关联工单与相关讨论，方便后来人追溯背景。
描述要素与作用
| 要素 | 回答的问题 |
|---|---|
| 背景 | 为什么现在要做这件事 |
| 改动范围 | 改了哪些，刻意没改哪些 |
| 验证方式 | 凭什么相信它是对的 |
| 风险与回滚 | 出问题影响多大，怎么退回去 |
| 重点评审点 | 最需要对方关注的判断在哪里 |
描述是异步沟通的主要载体：写清楚一次，比在评论区回答十次更省时间。
大改动把关键决策与备选方案写进描述：评审者能看清取舍过程，而不是只看到最终结果。