finishing-a-development-branch

開発ブランチの作業を完了する

概要

開発ブランチでの作業を完了するための、検証、マージ戦略の選択、クリーンアップを含む、体系的で安全なプロセスを提供します。このスキルにより、テストに合格していないブランチがマージされることを防ぎ、破壊的な操作にはすべて、ユーザーによる明示的な確認が必要になります。

使用するタイミング

• フィーチャーブランチで予定していた作業がすべて完了したとき
• ブランチのコードレビューまたはマージの準備ができたとき
• 開発作業の完了後にクリーンアップするとき
• チームレビュー用のプルリクエストを準備するとき

フェーズ 1：すべてのテストに合格していることを確認する

[HARD-GATE] 検証に合格するまで、マージや PR 関連の作業に進んではいけません。

マージや PR 関連の作業を行う前に、verification-before-completion を呼び出して、以下を確認します。

• すべてのテストに合格していること（該当する場合、ユニット、統合、E2E）
• lint エラーや警告がないこと
• ビルドが成功すること
• コミットすべき未追跡ファイルがないこと

# Run the project's full verification suite
# Do NOT skip this step even if "tests were passing earlier"

検証に失敗した場合は、そこで停止します。先に失敗を修正してください。テストに失敗している状態で、PR を作成したりブランチをマージしたりしてはいけません。

停止 — フェーズ 2 に進む前に、検証に合格する必要があります。

フェーズ 2：ベースブランチを決定する

以下の検出ロジックを使用して、マージ先のブランチを特定します。

自動検出

# Check for common base branch names
git branch -a | grep -E 'remotes/origin/(main|master|develop)$'

# Check what branch was the fork point
git log --oneline --decorate --graph HEAD...main --first-parent 2>/dev/null
git log --oneline --decorate --graph HEAD...master --first-parent 2>/dev/null

ベースブランチ選択の判断表

条件	ベースブランチ	確度
main が存在する	main	高
master のみ存在する	master	高
develop が存在し、プロジェクトが GitFlow を採用している	develop	中
複数の候補が見つかった	ユーザーに確認する	必須
上記のいずれにも該当しない	ユーザーに確認する	必須

ベースブランチが最新であることを確認する

git fetch origin
git log HEAD..<base-branch> --oneline

フィーチャーブランチの作成後にベースブランチが進んでいる場合は、ユーザーに知らせます。先にベースブランチをフィーチャーブランチにリベースまたはマージすることを検討してもらいます。

ベースブランチとの分岐に関する判断表

分岐	対応
ベースブランチに新しいコミットが 0 件	通常どおり進める
ベースブランチに新しいコミットが 1～5 件	ユーザーに知らせ、リベースを提案する
ベースブランチに新しいコミットが 6 件以上	ユーザーに警告し、続行前にマージまたはリベースすることを推奨する
マージコンフリクトが検出された	停止 — 先にコンフリクトを解決する

停止 — 続行する前に、ベースブランチをユーザーに確認してください。

フェーズ 3：マージの選択肢を提示する

以下の 4 つの選択肢を、そのままユーザーに提示します。選択肢を追加または削除してはいけません。

How would you like to finish this branch?

  A) Create PR    -- push and open a pull request for review
  B) Merge        -- merge into <base> with a merge commit
  C) Squash merge -- squash into one commit, merge into <base>
  D) Leave as-is  -- keep the branch, decide later

選択肢選定の判断表

状況	推奨する選択肢	理由
コードレビューを行うチームプロジェクト	A) PR を作成	レビューワークフローを利用できる
履歴が整理された個人プロジェクト	B) マージ	ブランチの全履歴を保持できる
WIP コミットが多く、履歴が整理されていない	C) スカッシュマージ	ベースブランチにクリーンな単一コミットを作成できる
作業が未完了、または状況が不確か	D) そのままにする	リスクがなく、後で判断できる

停止 — ユーザーが選択するまで待ちます。既定の選択肢を決めつけてはいけません。

フェーズ 4：選択したオプションを実行する

オプション A：プルリクエストを作成する

# Push the branch
git push -u origin <branch-name>

# Generate PR title from branch name or recent commits
# Generate PR body from commit messages and diff summary
gh pr create --title "<title>" --body "<body>"

PR タイトルの作成：

• ブランチ名から作成します。例：feature/add-auth は Add authentication になります
• 70 文字以内にします
• 命令形を使用します

PR 本文の作成：

• 変更内容とその理由を要約します
• 主な変更点を列挙します
• 互換性を損なう変更があれば記載します
• テスト計画を含めます

オプション B：ローカルでマージする

# Switch to base branch
git checkout <base-branch>

# Merge feature branch
git merge <feature-branch>

# Delete the feature branch
git branch -d <feature-branch>

マージを実行する前に、確認が必要です。

オプション C：スカッシュマージする

# Switch to base branch
git checkout <base-branch>

# Squash merge
git merge --squash <feature-branch>

# Commit with a comprehensive message
git commit -m "<squash commit message>"

# Delete the feature branch
git branch -d <feature-branch>

スカッシュコミットのメッセージには、最後のコミットだけでなく、ブランチ内のすべての変更を要約します。

スカッシュマージを実行する前に、確認が必要です。

オプション D：ブランチをそのままにする

対応は不要です。ユーザーに次のように伝えます。

Branch <branch-name> left as-is.
You can return to it later with: git checkout <branch-name>

フェーズ 5：クリーンアップ

オプション A、B、C を実行した後に、クリーンアップを行います。

ワークツリーを削除する（該当する場合）

ブランチの開発に Git ワークツリーを使用した場合：

# Navigate out of the worktree first
git worktree remove <worktree-path>
git worktree prune

リモート追跡のクリーンアップ（オプション B と C のみ）

ブランチを以前にプッシュしていた場合：

# Delete remote branch after local merge
git push origin --delete <branch-name>

リモートブランチを削除する前に、確認が必要です。

最終状態を確認する

git status
git log --oneline -5

ベースブランチが想定どおりの状態であることを確認します。

確認が必要な操作

[HARD-GATE] 次の操作を実行するには、事前にユーザーの明示的な確認が必要です。確認なしに進めてはいけません。必ず確認してください。

操作	確認が必要な理由
ベースブランチへのマージ	ベースブランチの履歴が変更されます
スカッシュマージ	個々のコミット履歴が失われます
ローカルブランチの削除	プッシュしていない場合、元に戻せません
リモートブランチの削除	ほかの共同作業者に影響します
ワークツリーの強制削除	未コミットの変更が失われる可能性があります
更新されたベースへのリベース	コミット履歴が書き換えられます

アンチパターン／よくある間違い

アンチパターン	問題点	代わりに行うこと
テストを実行せずにマージする	壊れたコードがベースブランチに入ります	必ず最初に検証をすべて実行してください
ベースブランチの最新状態を確認しない	マージの競合が後から見つかります	git fetch を実行し、分岐状況を確認してください
マージ戦略を自動で選択する	ユーザーが別の方法を希望する場合があります	必ず4つの選択肢をすべて提示してください
確認せずにブランチを削除する	データ損失のリスクがあります	削除のたびに確認してください
CI が失敗したまま PR を作成する	レビュー担当者の時間を無駄にします	PR を作成する前に CI の問題を修正してください
最後のコミットだけをもとにスカッシュメッセージを作成する	ブランチで行った作業全体の背景が失われます	すべての変更をまとめてスカッシュメッセージに記載してください
古いリモートブランチを残す	リポジトリが煩雑になります	マージ後にリモートのブランチを整理してください
PR 作成後に強制プッシュする	レビューコメントが失われます	PR のブランチへの強制プッシュは避けてください

エラー処理

エラー	対応
マージの競合	競合を報告し、ユーザーに解決を依頼してください。自動で解決してはいけません
プッシュが拒否された	フェッチして、リベースまたはマージが必要か確認してください
PR の作成に失敗した	gh auth status を確認し、エラーの詳細を報告してください
ブランチがすでに削除されている	削除をスキップし、残りのクリーンアップを続けてください
テストが失敗した	直ちに停止し、マージも PR の作成も行ってはいけません
ベースブランチがリモートに存在しない	正しいベースブランチをユーザーに確認してください

統合ポイント

スキル	統合
verification-before-completion	マージ作業の前にフェーズ1で必ず呼び出してください
using-git-worktrees	該当する場合、クリーンアップにはワークツリーの削除も含まれます
git-commit-helper	スカッシュコミットメッセージは、Conventional Commits 形式に従います
code-review	PR の作成（オプション A）はコードレビューのワークフローにつながります
planning	ブランチの完了は、計画の実行における最後のステップです
deployment	main/release へのマージによって、デプロイパイプラインが起動する場合があります

スキルの種類

RIGID — この手順に厳密に従ってください。すべてのフェーズを順番に完了する必要があります。検証を省略してはいけません。ユーザーの確認なしにマージしてはいけません。マージ戦略を勝手に決めてはいけません。確認せずにブランチを削除してはいけません。