name: github-pr-best-practices description: 创建GitHub拉取请求的最佳实践，包括约定式提交、PR格式化和多语言支持（英文/日文）。在创建PR、编写PR描述或格式化提交消息时使用。

GitHub拉取请求最佳实践

本技能提供全面的指导，帮助您遵循行业最佳实践和约定式提交标准创建高质量的拉取请求。

功能

生成符合约定式提交格式的PR标题
使用适当章节结构化PR描述
支持多语言（英文/日文）
遵循GitHub PR模板约定
避免常见PR错误

使用时机

在以下情况下使用本技能：

创建新的拉取请求
编写PR标题和描述
格式化提交消息
遵循约定式提交标准
生成英文或日文的PR内容

PR标题格式

约定式提交标准

PR标题必须遵循约定式提交格式：

<类型>(<范围>): <描述>

重要：PR标题或描述中不要使用表情符号。

常见类型

feat：新功能
fix：错误修复
docs：文档变更
style：代码风格变更（格式化，无逻辑变更）
refactor：代码重构
test：添加或更新测试
chore：维护任务、依赖项

范围（可选但推荐）

范围应指示代码库的哪部分受到影响：

模块名称：feat(auth): 添加OAuth2支持
组件名称：fix(button): 解决点击处理程序问题
代码区域：docs(api): 更新端点文档

描述

使用祈使语气（“add"而非"added"或"adds”）
首字母不大写
结尾不加句号
清晰简洁（尽可能少于50个字符）

示例

良好：

feat(auth): 添加OAuth2身份验证
fix(api): 解决大请求超时问题
docs(readme): 更新安装说明
refactor(database): 优化查询性能
test(auth): 为登录流程添加集成测试
chore(deps): 更新依赖项至最新版本

不佳：

✨ 添加新功能  （有表情符号）
修复错误  （未遵循格式，时态错误）
更新。  （模糊，有句号）
FEAT: 新功能  （全大写，模糊）

PR描述结构

标准模板

## 概要
- 变更的简要描述（1-3个要点）
- 关注内容和原因，而非方法
- 保持每个要点简洁

## 测试计划
- [ ] 测试用例1
- [ ] 测试用例2
- [ ] 验证无回归问题

🤖 由[Claude Code](https://claude.com/claude-code)生成

关键原则

概要部分
- 最多1-3个要点
- 解释变更内容和原因
- 避免实现细节（这些在代码中）
- 使用现在时态
测试计划部分
- 使用复选框格式（- [ ]）
- 列出具体的测试场景
- 包括回归测试
- 具体且可操作
签名
- 始终包含Claude Code签名
- 放置在底部

详细说明（需要时）

对于复杂的PR，在签名前添加额外部分：

## 概要
- 主要变更

## 背景
变更的背景或动机

## 实现细节
方法的高级概述

## 测试计划
- [ ] 测试

🤖 由[Claude Code](https://claude.com/claude-code)生成

多语言支持

英文（默认）

当未指定语言或语言为en时使用英文：

## Summary
- Add user authentication with OAuth2
- Implement token refresh mechanism
- Add comprehensive error handling

## Test plan
- [ ] Test OAuth2 login flow
- [ ] Test token refresh
- [ ] Test error scenarios

日文

当语言为ja时使用日文：

## 概要
- OAuth2によるユーザー認証を追加
- トークンリフレッシュ機能を実装
- 包括的なエラーハンドリングを追加

## テスト計画
- [ ] OAuth2ログインフローのテスト
- [ ] トークンリフレッシュのテスト
- [ ] エラーシナリオのテスト

语言选择指南

如果未指定语言，默认使用英文
使用调用者指定的语言
在整个PR中保持一致
不要在单个PR中混合语言

PR模板集成

使用项目模板

如果项目在.github/pull_request_template.md有PR模板：

读取模板文件
完全遵循其结构
不要修改章节标题
不要添加自定义章节
填写所有必需部分（如果不适用，使用"N/A"）

模板最佳实践

保留章节标题：保持与模板完全一致
完成所有部分：即使标记为"N/A"
遵循顺序：保持模板的章节顺序
不要即兴创作：坚持模板结构

GitHub CLI最佳实践

使用gh创建PR

基本命令结构：

gh pr create --draft --title "feat(scope): description" --body "$(cat <<'EOF'
## Summary
- Changes

## Test plan
- [ ] Tests

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

重要注意事项：

对多行描述使用HEREDOC格式
对于进行中的工作，以--draft标志开始
使用cat <<'EOF'（带引号）防止变量扩展
gh pr create自动推送分支（无需手动推送）

草稿与就绪

在以下情况下以草稿开始：

工作仍在进行中
测试未完成
需要早期反馈

转换为就绪时：

gh pr ready <PR-编号>

要避免的常见错误

PR创建前手动推送
- ❌ git push -u origin branch && gh pr create
- ✅ gh pr create（自动处理推送）
包含表情符号
- ❌ ✨ feat: 添加新功能
- ✅ feat: 添加新功能
错误的约定式提交格式
- ❌ 添加新功能
- ✅ feat: 添加新功能
模糊的描述
- ❌ `## 概要

更新内容`
- ✅ `## 概要
添加OAuth2身份验证支持`

忽略语言参数
- ❌ 总是使用英文
- ✅ 使用指定的语言（en/ja）
修改模板结构
- ❌ 向模板添加自定义章节
- ✅ 完全遵循模板结构

分析提交以创建PR

使用所有提交，而不仅是最新提交

创建PR时，分析来自合并基点的所有提交：

# 获取合并基点
MERGE_BASE=$(git merge-base origin/main HEAD)

# 获取合并基点后的所有提交
git log $MERGE_BASE..HEAD

为什么这很重要：

PR应代表分支上的所有工作
最新提交可能无法捕获完整范围
用户期望PR反映整个分支

从提交中提取PR内容

# 获取提交消息以用于概要
git log --format="- %s" $MERGE_BASE..HEAD

# 获取变更文件以了解上下文
git diff --name-only $MERGE_BASE..HEAD

# 获取提交计数
git log --oneline $MERGE_BASE..HEAD | wc -l

质量检查清单

创建PR前，验证：

[ ] 标题遵循约定式提交格式
[ ] 标题或描述中没有表情符号
[ ] 概要清晰简洁（1-3个要点）
[ ] 测试计划具体且可操作
[ ] 语言匹配指定偏好
[ ] 遵循模板结构（如果存在）
[ ] 分析了所有提交（不仅是最新提交）
[ ] 包含Claude Code签名

其他资源

请参阅REFERENCE.md了解：

详细的约定式提交规范
语言特定示例
高级PR模式
GitHub CLI命令参考

GitHub拉取请求最佳实践Skill github-pr-best-practices