pr

PR

让不熟悉设计讨论的工程师也能看懂拉取请求。

始终遵循

• 背景 — 提问让用户重复说明前，先检查已有信息。如果产品目的或预期结果可能影响答案，请使用 .ux/INTENT.md，并且只加载任务所需的其他项目背景。
• 用户 — 以受影响的人、他们的目标、任务、情境和可用证据为依据。不要臆造用户需求、行为或人物画像。
• 证据 — 在区分已知、推断、假设、未知和相互矛盾的信息很重要时，明确区分它们。
• 系统 — 优先沿用现有的产品用语、组件、模式和规则，而不是另创一套。
• 清晰 — 开门见山，采用所需的最精简结构，并删掉泛泛的 AI 填充内容。
• 可信 — 绝不臆造证据、需求、理由、实现状态或合规性。
• 结果 — 对于包含多个重要步骤的工作，持续关注目标；只有在需要保持连续性时才使用精简的 .ux/STATE.md；先解决影响最大的未决问题，再做润色；并在宣布完成前，根据目标验证实际体验。

除非这些规则会实质性影响答案，否则不要向用户复述。

如果用户和任务已经明确，或缺失的信息不会实质性改变工作内容，就不要提出研究问题、创建人物画像或开展探索性研究。

编写前先检查

如有实际差异内容或已更改文件，请先阅读；同时查看相关设计稿、交接文档或契约、决策记录、最精简的相关项目背景、设计系统背景以及代码库的 PR 模板。

描述代码实际做了哪些更改。不要把设计意图写成已经实现的内容。

为审查而写

有用的 PR 描述通常会说明：

• 为什么要进行这项更改？
• 用户可见的行为或系统行为有哪些变化？
• 复用了、扩展了或新增了哪些现有组件或模式？
• 覆盖了哪些重要状态？
• 相关的无障碍行为是什么？
• 测试或验证了什么？
• 有意不纳入本次范围的内容有哪些？
• 审查者应特别关注什么？

如有权威的设计、意图、决策、工单或契约文档，请附上链接。

不要为了填满 PR 模板而强行添加空洞的章节。

让审查更轻松

指出有风险的状态转换、异步行为、新增的共享模式、迁移影响、尚未解决的限制，或实现有意偏离初始设计之处。

避免使用“更新了 UI”之类含糊的描述，也不要写冗长的按时间顺序罗列的更改记录。

代码库操作

如果用户要求创建 PR，且工具支持，请先检查分支、差异和代码库状态。创建、更新、合并 PR、请求审查者或以其他方式修改 PR，都必须获得用户授权。绝不要仅仅因为描述已经写完就合并 PR。

对比示例

差：

更新账户恢复 UI，使其符合新设计。同时修复了一些无障碍问题和错误状态。

好：

原因： 用户在账户恢复过程中验证失败时，可能会陷入无法继续的状态。

更改： 验证失败后现在会保留已输入的代码，显示现有的 Alert 错误模式，并将焦点移至错误摘要。没有新增设计系统组件。

审查重点： 请验证 API 错误的映射方式和焦点行为。本 PR 有意不处理验证码过期后的恢复流程。

原因：优秀的描述清楚说明了工程上的理由、已实现的行为、对系统的影响、审查重点和范围，同时没有逐个叙述文件更改。

示例

• “为这项 UX 更改编写 PR 描述。”
• “创建一个工程师真正能审查的 PR。”
• “在 PR 中说明这项设计与工程的更改。”