git-branch-pr-workflow

Git ブランチと PR のワークフロー

このスキルを使用する場面

次のような場合にこのスキルを使用します…	次のような場合は代替手段を使用します…
ブランチと PR の全体的なワークフロー（main ブランチでの開発、MCP 統合）を設計する	単一のブランチ名を選択または監査する場合は、git-branch-naming を使用します
git switch、git restore、フィーチャーブランチへのプッシュパターンから選択する	直線的な履歴の整理や積み上げ型 PR には、git-rebase-patterns を使用します
gh pr create ではなく GitHub MCP ツールを使って PR を作成する	プッシュ済みのブランチから gh CLI を使って PR を作成する場合は、git-pr を使用します
コミットからプッシュ、PR までを一貫して調整する	コミット、プッシュ、PR をまとめたマクロには、git-commit-push-pr を使用します

最新の Git コマンドと直線的な履歴の手法を用いた、ブランチ管理、プルリクエストのワークフロー、GitHub 統合に関する専門的なガイダンスです。

主な専門分野

• main ブランチでの開発：ローカルでは main で作業し、PR 用にリモートのフィーチャーブランチへプッシュします
• 最新の Git コマンド：checkout の代わりに git switch と git restore を使用します
• ブランチ命名：git-branch-naming スキルを参照してください
• 直線的な履歴：リベース優先のワークフローとスカッシュマージについては、高度なパターンを git-rebase-patterns で確認してください
• GitHub MCP 統合：gh CLI の代わりに mcp__github__* ツールを使用します

main ブランチでの開発（推奨）

main で直接開発し、PR 用にリモートのフィーチャーブランチへプッシュします。これにより、ローカルでブランチを管理する負担がなくなります。

基本的なワークフロー

# All work happens on main
git switch main
git pull origin main

# Make changes, commit on main
git add file.ts
git commit -m "feat(auth): add OAuth2 support"

# Push to remote feature branch (creates PR target)
git push origin main:feat/auth-oauth2

# Create PR using GitHub MCP (head: feat/auth-oauth2, base: main)

複数 PR のワークフロー（連続したコミット）

main に複数の PR 用コミットがある場合、特定のコミット範囲を異なるリモートブランチへプッシュします。

# Commits on main:
# abc1234 feat(auth): add OAuth2 support       <- PR #1
# def5678 feat(auth): add token refresh        <- PR #1
# ghi9012 fix(api): handle timeout edge case   <- PR #2

# Push first 2 commits to auth feature branch
git push origin abc1234^..def5678:feat/auth-oauth2

# Push remaining commit to fix branch
git push origin ghi9012^..ghi9012:fix/api-timeout

# Alternative: push from a specific commit to HEAD
git push origin def5678..HEAD:fix/api-timeout

コミット範囲のパターン：

• git push origin <start>^..<end>:<remote-branch> - コミット範囲をプッシュします（両端を含む）
• git push origin <commit>..<commit>:<remote-branch> - 範囲をプッシュします（開始位置を含まない）
• git push origin <commit>..HEAD:<remote-branch> - コミットから現在の HEAD までをプッシュします
• git push origin main:<remote-branch> - main 全体をリモートブランチへプッシュします

メリット

• ローカルでブランチを切り替える必要がない - 常に main にいます
• 常に最新の main を使用 - ブランチが古くなりません
• ローカルの状態がクリーン - クリーンアップが必要な古いブランチがありません
• リモートブランチは一時的 - PR のマージ後に削除されます
• 考え方がシンプル - ローカルブランチは 1 つ、プッシュ先は複数です

最新の Git コマンド（2025）

ブランチには git switch、ファイルには git restore を使用し、git checkout / git reset は使用しないでください。コマンドの形式と従来のコマンドから最新のコマンドへの移行表については、references/modern-git-commands.md を参照してください。

ブランチ命名

種類の接頭辞、Issue との紐付け、検証パターンを含む包括的なブランチ命名規則については、git-branch-naming を参照してください。

クイックリファレンス： {type}/{issue}-{description}（例：feat/123-user-auth）

直線的な履歴のワークフロー

上記のとおり、main ブランチでの開発を推奨します。ローカルのフィーチャーブランチ（数日間の作業または実験的な作業）、スカッシュマージ、インタラクティブなリベースによる整理については、references/local-feature-branches.md を参照してください。

高度なリベースパターン

--reapply-cherry-picks、--update-refs、--onto、積み上げ型 PR のワークフロー、フラグの組み合わせなど、高度なリベース手法については、git-rebase-patterns を参照してください。

GitHub MCP 統合

すべての GitHub 操作には GitHub MCP ツールを使用します。

# Get repository information
mcp__github__get_me()  # Get authenticated user info

# List and create PRs
mcp__github__list_pull_requests(owner="owner", repo="repo")
mcp__github__create_pull_request(
  owner="owner",
  repo="repo",
  title="feat: add authentication",
  head="feat/auth",
  base="main",
  body="## Summary\n- JWT authentication\n- OAuth support\n\nCloses #123"
)

# Update PRs
mcp__github__update_pull_request(
  owner="owner",
  repo="repo",
  pullNumber=42,
  title="Updated title",
  state="open"
)

# List and create issues
mcp__github__list_issues(owner="owner", repo="repo")

ベストプラクティス

main や共有ブランチには決して強制プッシュせず、強制プッシュする場合は必ず --force-with-lease を使用します。日々の main へのリベース手順とリベース時の競合処理については、references/local-feature-branches.md を参照してください。

main ブランチの保護

GitHub MCP を使って、直線的な履歴を実現するブランチルールを設定します。

# Require linear history (disable merge commits)
# Configure via GitHub settings or MCP tools
# - Require pull request reviews
# - Require status checks to pass
# - Enforce linear history (squash merge only)

ブランチの比較：常に origin/main を使用する

重要： PR 作成のためにブランチを比較する場合は、必ず origin/main（または origin/<base-branch>）と比較してください。ローカルの main とは絶対に比較しないでください。ローカルの main にリモートへマージされていないコミットが含まれていると、PR に無関係な変更が含まれる可能性があります。

これが重要な理由

# WRONG: compares against local main (may include unpushed commits)
git log main..HEAD --format='%s'
git diff main...HEAD --stat

# CORRECT: compares against remote main (matches what GitHub will show)
git fetch origin main
git log origin/main..HEAD --format='%s'
git diff origin/main...HEAD --stat

よくある状況： ある PR のためにローカルの main で変更をコミットし、フィーチャーブランチにプッシュしてから、2 つ目の PR の作業を始めます。ローカルの main と比較すると、2 つ目の PR の差分は正しく見えます。しかし、1 つ目の PR がまだマージされていない場合、origin/main は更新されていません。これと比較すると、両方の PR の変更が含まれることが分かります。

ルール

1. 比較する前に必ずフェッチする： git fetch origin main
2. PR のコンテキストでは、すべての diff／log コマンドで origin/main を使用する
3. ブランチを作成するときは、origin/main を基点に PR を作成する：git switch -c feat/foo origin/main
4. pr-context.sh スクリプトがこれを自動的に処理します

PR のコンテキスト収集（推奨）

PR を作成する前に、次の 1 つのコマンドですべてのコンテキストを収集します。

# Gather PR context (defaults to main as base, compares against origin/main)
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-branch-pr-workflow/scripts/pr-context.sh"

# Specify different base branch (compares against origin/develop)
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-branch-pr-workflow/scripts/pr-context.sh" develop

このスクリプトは最新のリモート状態をフェッチし、origin/<base> と比較して、正確な PR コンテキストを確認します。ブランチ情報、リモートの状態、コミット範囲と種類、差分の統計、コミット内で見つかった Issue の参照、既存の PR の検出結果、CI チェックの結果が出力されます。この出力を使って PR のタイトルと本文を作成してください。詳しくは scripts/pr-context.sh を参照してください。

プルリクエストのワークフロー

PR タイトルの形式

PR のタイトルには、Conventional Commits の形式を使用してください。

• feat: add user authentication
• fix: resolve login validation bug
• docs: update API documentation
• chore: update dependencies

PR 本文のテンプレート

## Summary
Brief description of changes

## Changes
- Bullet points of key changes
- Link related work

## Testing
How changes were tested

## Issue References

Closes #123

Issue 参照のガイドライン：

• マージ時に Issue を自動でクローズするには、Closes #N／Fixes #N／Resolves #N を使用します
• 自動クローズせずにコンテキストを示すには、Refs #N／Related to #N を使用します
• リポジトリをまたぐ場合：Fixes owner/repo#N
• 複数の場合：Fixes #1, fixes #2, fixes #3（キーワードを繰り返します）

PR 作成のベストプラクティス

• PR ごとに焦点を 1 つにする - 論理的にまとまった変更を 1 つにします
• 小さな PR にする - レビューが容易になります（400 行未満を推奨）
• 必ず Issue をリンクする - 追跡できるよう、GitHub の自動リンク形式を使用します：
  • クローズするキーワード：Closes #123、Fixes #456、Resolves #789
  • クローズせずに参照する場合：Refs #234、Related to #567
  • リポジトリをまたぐ場合：Fixes owner/repo#123
  • 複数の Issue：Fixes #1, fixes #2（それぞれにキーワードを繰り返します）
• ラベルを追加する - 分類には GitHub のラベルを使用します
• レビュアーを依頼する - 必要に応じて特定のレビュアーを指定します

トラブルシューティングと復旧

トラブルシューティング（ブランチの分岐、想定されるワークフローで main にコミットした場合、複雑なリベースの競合）、安全な操作に関するガイダンス（通常の状態の見分け方、確認が必要なコマンド）、復旧のワークフロー（コミット前にファイルが変更された場合、プッシュが拒否された場合、コミットに失敗した場合）については、REFERENCE.md を参照してください。