Menu
写 Pull Request 描述时使用。让 reviewer 快速理解与审查。
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
| name | pr-description |
| description | 写 Pull Request 描述时使用。让 reviewer 快速理解与审查。 |
| category | docs |
| tags | ["pr","协作"] |
规则： PR 描述必须包含三部分:改了什么(变更摘要)、为什么改(背景/动机)、怎么验证(测试方法)——缺一不可。
为什么： AI 辅助写代码时,描述最常见的问题是只写"做了什么"而完全不写"为什么"和"怎么验证"。reviewer 看到一堆代码改动不知道背景是什么、这个方案是否是最优选择,也不知道怎么本地复现来验证。结果要么盲目通过,要么来回追问浪费时间。典型事故:PR 描述写"修复 bug",reviewer 花 20 分钟读代码才弄清楚是哪个 bug、怎么触发、为什么这样修。
怎么做：
规则： 关联对应的 issue 编号或需求单;如果有 breaking change,必须在描述顶部显著标注,并附上迁移步骤。
为什么： AI 生成的 PR 里经常找不到任何 issue 关联,也没有 breaking change 警告。前者让项目管理失去可追溯性,半年后不知道某个改动是为了什么;后者让接入方在升级后莫名跑挂,只能自己去 git log 里找原因。破坏性变更不显著标注是最容易被忽视的 PR 问题,影响范围往往远超当前 repo。
怎么做：
Closes #123 或 Related to #456 自动关联 issue。⚠️ Breaking Change + 影响范围 + 迁移方法。规则： 描述中的"测试计划"要具体到可操作的步骤:运行什么命令、访问什么 URL、输入什么数据、期望看到什么结果。
为什么： AI 写的 PR 描述里"测试方法"常是一行:已通过单元测试。reviewer 无法判断:单元测试覆盖了哪些场景?有没有集成测试?手动测了哪些场景?UI 改动有没有截图?结果只能靠"信任 CI 绿了就行"通过 PR,这是生产事故的温床。特别是 UI 改动或涉及第三方服务的改动,仅靠 CI 无法验证。
怎么做：
1. 拉取分支 2. 执行 XXX 3. 访问 /endpoint 4. 预期返回 200 + {…}。规则： 单个 PR 只做一件事;超过 400 行 diff 或涉及多个不相关改动时主动拆分;对无法当前解决的遗留问题,在描述中明确说明。
为什么： AI 辅助开发时容易在一个 PR 里顺手做了重构+功能+修 bug,产生千行 diff。reviewer 面对大 PR 的选择往往是:浅看后盲目通过,或者拖着不审导致 PR 堆积。两者都有风险。同时 AI 有时为了"让代码跑起来"引入了临时方案却不说明,reviewer 不知道这是临时的还是正式的,后续也没人跟进清理。
怎么做：
当前方案为临时修复,完整方案见 #789。规则： PR 描述末尾附一个可勾选的自检清单,提交前自己过一遍打勾,让 reviewer 看到你已自查过什么。
为什么： AI 完成实现后很容易忽略收尾工作:console.log 没删、CHANGELOG 没更新、文档没同步。自检清单是一种强制提醒机制——不是给 reviewer 看的形式主义,而是给自己设的最后一道门。有了清单,reviewer 也能快速判断"作者已确认过测试通过",减少重复问题。
怎么做：
[ ] 测试已通过、[ ] 无调试代码残留、[ ] 相关文档已更新、[ ] breaking change 已标注。.github/pull_request_template.md。<!-- 反例 — reviewer 一头雾水 -->
## 改动
修复了用户登录的问题,更新了 auth 相关逻辑。
---
已测试。
<!-- 正例 — 背景、改动、验证三位一体 -->
## 背景
用户反馈使用 SSO 登录后跳转回错误页面(见 #342)。
根因:OAuth callback 处理时未正确解析 `state` 参数,导致 redirect_uri 丢失。
## 改动摘要
- 修复 `OAuthCallbackHandler.parseState()` 中 URL decode 顺序错误
- 新增 `state` 参数为空时的降级处理(重定向至首页)
- 补充了原先缺失的集成测试用例
## 验证步骤
1. 本地启动:`docker compose up`
2. 访问 `http://localhost:3000/login`
3. 点击"使用 SSO 登录",完成认证
4. 预期:跳转回 `/dashboard`,不再出现 404
也可运行自动化测试:`npm run test:integration -- auth`
Closes #342
<!-- 反例 — breaking change 埋在第三段,接入方看不到 -->
## 改动
重构了配置加载模块,提升了性能。现在支持多种格式。
注意:配置文件格式从 JSON 改为 TOML(在第三段才提到)。
<!-- 正例 — breaking change 置顶显著标注 -->
## ⚠️ Breaking Change
配置文件格式从 JSON 变更为 TOML。升级步骤:
1. 将 `config.json` 重命名为 `config.toml`
2. 将所有值改为 TOML 语法(字符串加引号,对象用 `[section]`)
3. 运行 `npx migrate-config` 可自动转换(见工具说明)
## 改动背景
…（后续内容）
做 Cocos Creator 多机型/多分辨率适配时使用。Canvas、Widget、安全区。
Cocos Creator 用 AssetBundle 做分包/远程资源时使用。加载、释放、依赖、缓存。
优化 Cocos Creator 渲染性能时使用。合批、图集、动静分离、Label。
给 Cocos Creator 原生包做热更新时使用。version manifest、增量、校验、回滚。
写 Cocos Creator 动效/动画时使用。tween、Animation、Spine、性能与清理。
做 Cocos Creator 大量条目列表时使用。虚拟列表、节点复用。