通俗易懂的 PR 描述
为需要快速理解变更的维护者编写。一个好的描述应在首屏回答三个问题：
- 什么出了问题或缺少什么？
- 为什么需要修改？
- 现在的情况是怎样的？
在编写之前，请阅读实际的 diff、当前 PR 正文、提交、测试和 PR 状态。旧的正文和提交标题描述的是意图，而非证据。除非作者确认，否则不要声称进行了手动测试、部署或生产行为。
必需的起始部分：变更了什么以及为什么
每个 PR 描述必须从贡献者拥有的 ## What Changed and Why 章节开始，紧跟在监控者拥有的 ## Status 之后（如果 Status 存在）。这是必需的，不是可选的格式。
使用三个简短的带标签段落，按以下顺序：
- 问题： 实际的用户或操作员故障，或缺失的行为。
- 此变更为何必要： 该故障为何重要，以及为何需要此边界。
- 新现状： 此 PR 之后的具体行为。
将每个带标签的段落控制在一到两句话。维护者应能仅从此章节回答“此 PR 做了什么？”。不要以实现细节、已删除的设计或重写历史开头。
审查一个不合格的开头时，给出具体的替代方案或一个针对实际 diff 定制的简洁的三段落大纲。不要仅仅说它冗长、不清楚或需要更好的解释。
对大多数 PR 使用此格式：
## What Changed and Why
**Issue:** [实际的用户或操作员故障，或缺失的行为。]
**Why this change was necessary:** [为何重要以及为何需要此边界。]
**New status quo:** [此 PR 之后的具体行为。]
## After merge
[仅为真正的操作员或审查者需要执行的操作。如果没有，则省略此章节。]
## Verification
[仅说明已确认的手动检查和真正的合并后检查。]
从实质内容开始。不要重复 PR 标题、添加介绍或编写总结下一段落的摘要。
保留的内容
- 每个实质性变更一个清晰终态。 阅读每个段落或项目符号第一句话的读者应能理解合并后改变了什么。
- 真实决策。 仅当被拒绝的替代方案会影响产品行为、风险或重大成本时，才提及它。用一句话说明选择了什么以及为什么。不要制造“关键决策”标签。
- 运营事实。 当审查者或操作员需要对其采取行动时，请提及迁移、回填、计划任务、集成、密钥、部署顺序和故障行为。
- 诚实的验证。 将某人实际手动检查的内容与真正的合并后才可进行的工作分开。不要列出 lint、构建、CI 或测试命令。当测试涵盖了有意义的行为时，可以用通俗英语提及。
- 开放议题。 仅包含审查者必须做出的未解决决策。先提出问题，然后是建议及其成本。当没有需要决定的事情时，省略此章节。
变更系统所需的证据
当 PR 更改了面向用户的系统、重要的操作员工作流或其配置，且未向审查者展示如何检查时，描述是不完整的。
- 截图或短视频： 将视觉证据放在其自己的
## Visual evidence章节中。对于更改的屏幕包含截图，对于更改的交互或多步骤流程包含短视频。嵌入媒体或链接到稳定的 PR 附件。说明必须说明更改了什么以及审查者在查看什么。不要用源代码截图、测试报告或未更改的屏幕来代替。对于公共和事件页面，将必要的手机证据放在笔记本电脑证据之前，并识别每个视口和测试状态。遵循visual-proofskill 进行捕获、上传和最新提交验证。仅当 PR 没有视觉或交互界面时，才省略此章节。 - 配置、环境和迁移： 仅将实际添加、删除、重命名或改变行为的环境变量、密钥、仪表盘设置和数据库迁移放在
## Configuration中。以操作员需要执行的一个操作开头；将普通的外部设置控制在一句简短的话中，例如：Set up a monitor at <URL> and point it to https://buildpurdue.org/api/health. No internal changes.不要用轮询细节、已在别处解释的理由或链接到重复的操作手册来填充此章节。对于每个实际的迁移，命名其已提交的supabase/migrations/路径，总结模式/数据/策略的更改，说明兼容性或回填要求，并给出已确认的npm run db:verify重放结果。切勿打印密钥值。当没有配置或迁移更改时，省略此章节。 - 更改的流程： 对发生实质性变化的流程使用 Mermaid 流程图。当一个流程包含多个步骤、分支、重试、系统之间的交接或故障路径时，该流程即为实质性流程。显示变更的路径及其重要的故障行为，使用审查者能读懂的普通标签。为每个不同的更改流程添加一个图表。不要对单步重命名或微不足道的本地计算使用图表。
这些与主要解释是分开的。解释说明变更存在的原因；证据、配置和图表让审查者可以检查它。
保持可读性
- 默认 250 字或更少。当操作员需要简短的检查清单时，描述可以更长，但每个句子都必须有其存在的价值。
- 使用短段落。仅在真正需要列表时使用项目符号，例如剩余的设置步骤。不要将每个句子都变成带标签的项目符号。
- 用通俗英语说明问题、原因和新现状。说明谁做了什么。
- 避免原始代码、查询、配置片段、作为名词的状态码、行话、隐喻、过度宣传和 em dash。
- 不要解释每个机制。只保留审查者需要知道的行为。
- 不要在后来的章节中重复事实。如果一个句子可以在不丢失信息的情况下消失，就删除它。
Status 由监控者控制
贡献者拥有 PR 描述的每个部分，除了 ## Status。不要自己添加、删除或编辑该章节。BuildPurdue PR 监控者拥有它并使其与当前的审查状态保持一致。
当监控者更改 Status 时，它还会发布一条匹配的 Status update: PR 评论。它使用一句通俗易懂的英语：当还有待办工作时，是合并前的具体下一步操作；如果没有任何待办工作，则是 No more remaining work.。Status 永远不应出现在面向贡献者的描述审查评论中。
不要将 Status 用于可选的未来想法、历史记录、仅合并后完成的工作，或单独跟踪且不阻塞此 PR 的工作。
何时需要更多结构
仅当包含的信息不适合主要解释时，才添加一个重点章节：
- 数据库/迁移： 必须运行什么，现有数据是否保持兼容，以及是否需要回填。
- 运行行为： 什么运行、何时运行、故障如何可见以及操作员必须配置什么。
- 验证： 已确认的手动检查和真正的合并后检查。
- 开放议题： 未解决的产品或风险选择。
一个小的 bug 修复可以简单地使用：
## Root cause
## Fix
## Verification
发布前
- 检查每个声明是否都能追溯到当前的 diff、测试、PR 状态或您运行的命令。
- 单独阅读首屏。它必须清晰地说明问题、变更的必要性以及新的现状。
- 删除历史叙述、变更日志风格的实施日志、重复的解释和无关的工作。
- 确认任何迁移、部署、密钥、仪表盘或合并后操作都是明确且可操作的。
- 大声朗读一遍。它听起来应该像一个人在向队友解释变更，而不是一份审计报告。
- 每次推送时，将正文与新的 diff 进行比较，并在行为、剩余设置或验证状态发生变化时更新它。
来源
在 .agents/skills/ 下编辑此副本。pre-commit 钩子会将其镜像到 .claude/skills/pr-description/；不要直接编辑镜像。