finishing-a-development-branch

開発ブランチの仕上げ

概要

基本原則： テストを検証 → 環境を検出 → 選択肢を提示 → 選択を実行 → クリーンアップ。

開始時に伝える：「この作業を完了するために、開発ブランチの仕上げスキルを使用します。」

ステップ 1：テストを検証する

プロジェクトのテストスイート全体を実行します（npm test / cargo test / pytest / go test ./...）。

テストが失敗した場合は、失敗内容を報告して中止します。メニューの提示は、テストスイートがすべて成功してからです。

Tests failing (<N> failures). Must fix before completing:

[Show failures]

テストが成功した場合： ステップ 2 に進みます。

ステップ 2：環境を検出する

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
# Capture now, while still inside the workspace — Step 5 changes directory
# before cleanup (Step 6) needs this value
WORKTREE_PATH=$(git rev-parse --show-toplevel)

これにより、表示するメニューとクリーンアップの方法が決まります。

状態	メニュー	クリーンアップ
GIT_DIR == GIT_COMMON（通常のリポジトリ）	標準の 3 つの選択肢	クリーンアップするワークツリーはありません
GIT_DIR != GIT_COMMON、名前付きブランチ	標準の 3 つの選択肢	出所に基づいて処理します（ステップ 6 を参照）
GIT_DIR != GIT_COMMON、detached HEAD	2 つの選択肢に縮小（マージなし）	外部管理のため、そのまま残します

ステップ 3：ベースブランチを決定する

ベースブランチとは、この作業の分岐元です。通常は、計画、会話、またはブランチのアップストリームに記載されています。まだ分からない場合は、「このブランチは から分岐しました。これで合っていますか？」と尋ねます。マージする前に確認してください。誤ったベースブランチへのマージは、取り消すのに多大な手間がかかります。

ステップ 4：選択肢を提示する

通常のリポジトリおよび名前付きブランチのワークツリーでは、次の 3 つの選択肢をそのまま提示します。

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)

Which option?

detached HEAD の場合は、次の 2 つの選択肢をそのまま提示します。

Implementation complete. You're on a detached HEAD (externally managed workspace).

1. Push as new branch and create a Pull Request
2. Keep as-is (I'll handle it later)

Which option?

メニューは記載どおりに提示してください。簡潔にまとめ、すべての選択肢は上記のリストから選びます。作業を破棄するのは、人間のパートナーから明示的に依頼された場合に限ります（下記の「人間のパートナーから作業を破棄するよう依頼された場合」を参照）。回答を待ってください。統合するかどうかは、相手が決めます。

ステップ 5：選択を実行する

選択肢 1：ローカルでマージする

# Get main repo root for CWD safety
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# Merge first — verify success before removing anything
git checkout <base-branch>
git pull
git merge <feature-branch>

# Verify tests on merged result
<test command>

マージ後の結果でテストが失敗した場合は、中止して、ワークツリーとブランチを残したまま調査します。何もプッシュされていないため、マージはローカルにあり、復旧可能です。

マージ後の結果でテストがすべて成功したら、ワークツリーをクリーンアップして（ステップ 6）、ブランチを削除します。

git branch -d <feature-branch>

選択肢 2：プッシュして PR を作成する

git push -u origin <feature-branch>
# From a detached HEAD, name the new branch on the remote:
# git push origin HEAD:refs/heads/<new-branch>

次に、フォージのツールを使って を対象にプルリクエスト／マージリクエストを作成します。利用可能であれば CLI を使い、そうでなければプッシュ時に多くのフォージが表示する作成 URL を使います。リポジトリに PR テンプレートや規約がある場合は、それに従い、URL を人間のパートナーに報告します。

ワークツリーは残してください。人間のパートナーはそこで PR のフィードバックに対応します。

選択肢 3：現状のまま保持する

「ブランチ を保持します。ワークツリーは に残してあります。」と報告します。

人間のパートナーから作業を破棄するよう依頼された場合

この手順を使うのは、作業を破棄するよう明示的に依頼された場合に限ります。まず確認してください。

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'discard' to confirm.

その確認と完全に一致する返答を待ちます。確認が得られたら、次のようにします。

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

次に、ワークツリーをクリーンアップして（ステップ 6）、ブランチを強制削除します。

git branch -D <feature-branch>

ステップ 6：ワークスペースをクリーンアップする

選択肢 1 および確認済みの破棄で実行します。 選択肢 2 と 3 では、必ずワークツリーを残します。どちらの場合も、呼び出し元はすでにメインリポジトリのルートディレクトリに移動しています。ワークツリーの削除はワークツリーの外から実行する必要があります。また、ディレクトリを移動する前にステップ 2 で取得した GIT_DIR／GIT_COMMON／WORKTREE_PATH の値を使います。

GIT_DIR == GIT_COMMON の場合： 通常のリポジトリで、クリーンアップするワークツリーはありません。完了です。

WORKTREE_PATH が .worktrees/ または worktrees/ の下にある場合： Superpowers が作成したワークツリーなので、こちらでクリーンアップします。

git worktree remove "$WORKTREE_PATH"
git worktree prune  # Self-healing: clean up any stale registrations

削除を拒否された場合（contains modified or untracked files）：ワークツリーには、他の場所には存在しないファイルが含まれています。未コミットの計画、メモ、作業用ファイルなどです。自分の判断で --force を実行してはいけません。何が失われる可能性があるかを人間のパートナーに示し、次のように尋ねます。

git -C "$WORKTREE_PATH" status --porcelain -uall

Worktree removal refused — these files were never committed:

<file list>

1. Commit them to <branch> before cleanup
2. Move them into <main repo root>
3. Delete them (unrecoverable)

Which?

選択された対応を実行してから、ワークツリーを削除します。

それ以外の場合： このワークスペースはホスト環境が管理しているため、そのまま残します。プラットフォームにワークスペース終了ツールが用意されている場合は、それを使用します。

クイックリファレンス

選択肢	マージ	プッシュ	ワークツリーを保持	ブランチをクリーンアップ
1. ローカルでマージ	はい	-	-	はい
2. PR を作成	-	はい	はい	-
3. 現状のまま保持	-	-	はい	-
破棄（明示的な依頼がある場合のみ）	-	-	-	はい（強制）

よくある正当化

言い訳	実態
「このセッションの早い段階でテストに合格した」	統合しようとしているツリーでテストスイートを実行してください。テストが成功したという事実が証明するのは、そのテストを実行したツリーだけです。
「明らかにマージしてほしいと思っている」	統合するかどうかは、人間のパートナーが決めることです。選択肢を提示して、返答を待ってください。
「この機能はもう完成したようだし、破棄するか尋ねてみよう」	選択肢は記載のとおりで完結しています。人間のパートナーがはっきりと言葉で依頼した場合にのみ、破棄します。
「『うん、消して』で確認したことになる」	入力された単語 discard だけが削除を許可します。
「PR は作成済みだから、ワークツリーはもう不要だ」	PR へのフィードバックは、そのワークツリーで修正します。作業が取り込まれるまで保持します。
「この別のワークツリーは古そうだから、これもクリーンアップしよう」	.worktrees/ または worktrees/ 内のワークツリーだけをクリーンアップしてください。それ以外はホストに属します。
「削除を拒否された。--force はクリーンアップの仕上げにすぎない」	拒否されたということは、ファイルがそのワークツリーにしか存在しないということです。--force を使うと完全に破壊されます。人間のパートナーに見せて、確認してください。
「マージ後の結果の失敗は、おそらく不安定なテストだ」	マージ後の結果が失敗したら、すべての作業を止めてください。調査中はブランチとワークツリーをそのままにします。
「ベースブランチは明らかに main だ」	フォークポイントを確認するか、尋ねてください。誤ったベースへのマージは元に戻すのに大きなコストがかかります。
「プッシュが拒否された。強制プッシュすれば解決する」	プッシュが拒否されたということは、リモートが更新されたということです。調査してください。強制プッシュは、人間のパートナーから明示的な依頼があった場合にのみ行ってください。