القائمة
写 Pull Request 描述时使用。让 reviewer 快速理解与审查。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
做 Cocos Creator 多机型/多分辨率适配时使用。Canvas、Widget、安全区。
Cocos Creator 用 AssetBundle 做分包/远程资源时使用。加载、释放、依赖、缓存。
优化 Cocos Creator 渲染性能时使用。合批、图集、动静分离、Label。
给 Cocos Creator 原生包做热更新时使用。version manifest、增量、校验、回滚。
写 Cocos Creator 动效/动画时使用。tween、Animation、Spine、性能与清理。
做 Cocos Creator 大量条目列表时使用。虚拟列表、节点复用。
| 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` 可自动转换(见工具说明)
## 改动背景
…（后续内容）