creating-pull-requests

用途

Creating Pull Requests 是一个用于创建高质量、对评审友好的 Pull Request（PR）的技能。其目标是通过提供充分的上下文，加速代码评审过程，让评审者能够快速理解变更意图并给出反馈。文档指出，高质量 PR 的价值包括：加快评审速度、获得更好的反馈、促进知识共享、形成可检索的历史记录，以及营造重视代码质量的团队文化。

何时激活

该技能在以下情况被激活：

用户说“create PR”“make pull request”
用户说“ready to merge”或“ready for review”
功能开发完成且测试通过
用户询问 PR 最佳实践
有重要变更准备分享

主要能力

该技能围绕 PR 的完整生命周期提供指导，主要包括：

分析变更：通过 git 命令检查当前分支和状态、查看从基准分支分叉以来的全部提交、查看完整 diff、检查已暂存和未暂存的更改。同时提出关键问题：实现了什么功能或修复、变更范围、是否有相关提交、是否全部已提交。
验证质量：运行测试、运行 lint、检查构建，并给出预检清单，包括测试通过、lint 通过、无意外变更、无调试代码、无密钥凭据、分支与 main 保持同步。
撰写 PR 描述：提供结构化描述模板，包含 Summary（摘要）、Changes（变更）、Motivation（动机）、Implementation Details（实现细节）、Testing（测试）、Screenshots/Videos（截图/视频）、Breaking Changes（破坏性变更）、Rollout Plan（上线计划）、Related（关联信息）等部分。
创建 PR：通过 git push 推送分支，并使用 gh CLI 创建 PR，指定标题和正文。
自我评审：在提交前以评审者视角阅读 diff，检查明显错误，确认所有变更都是有意为之，并为复杂部分添加注释。

使用方式

技能内嵌了可直接运行的命令示例，例如：

git status
git branch --show-current
git log main..HEAD --oneline
git diff main...HEAD
git diff HEAD
git diff --staged
npm test
npm run lint
npm run build
git push -u origin feature-branch
gh pr create \
  --title "Clear, descriptive title" \
  --body "$(cat <<'EOF'
[PR description from step 3]
EOF
)"

标题与描述规范

PR 标题建议格式为 <type>: <short description>，类型包括 feat、fix、docs、refactor、perf、test、chore。文档列出了正例和反例，建议标题具有描述性、简洁（50-72 个字符）、以动词开头且足够具体。

描述方面提供两套模板：完整模板（适用于较复杂 PR，包含问题、解决方案、变更分类、关键决策、权衡、备选方案、测试覆盖、评审者测试计划、边界情况、性能影响、安全考量、破坏性变更、部署说明、截图、清单、关联信息）和精简模板（适用于小型 PR，仅含摘要、变更、测试、关联）。

适用场景

适用于开发者完成功能开发、修复或重构后，需要向团队提交代码评审请求的场景，尤其是希望写清楚变更意图、测试情况和上下文，以缩短评审往返次数的情况。文档也描述了示例工作流：用户表示购物车功能完成并请求创建 PR，技能会分析变更、运行预检、生成标题与描述、提出后续步骤。

体量建议与限制

文档给出 PR 体量建议：小型（<200 行）易评审、审批快；中型（200-500 行）可管理；大型（500-1000 行）需要额外精力；过大（>1000 行）建议拆分。当存在多个不相关变更、可独立部署、大重构与功能新增混合、不同部分需要不同评审者时，应考虑拆分。

此外，文档列出常见错误：描述含糊、体量过大、缺少上下文、不做自我评审、缺少测试、没有截图。还给出成功标准，例如评审者无需提问即可理解、评审在 24 小时内完成、往返沟通少、无需重大修改即可通过。

该技能会调用 git 命令、gh CLI 和代码分析，并可升级到 Reviewing Code 和 Testing Code 技能。文档中提及的 PR 示例路径为 Examples/GoodPRs/，并建议参考项目专属的 PR 规范。