git-worktree-manager

Git Worktree Manager

Tier: POWERFUL
Category: エンジニアリング
Domain: 並列開発とブランチの分離

概要

このスキルを使うと、Git worktree を活用して機能開発を安全に並行して進められます。ブランチの分離、ポートの割り当て、環境の同期、クリーンアップを標準化し、各 worktree が別のブランチに影響を与えず、独立したローカルアプリのように動作するようにします。

このスキルは、各エージェントまたはターミナルセッションがそれぞれ 1 つの worktree を担当するマルチエージェントのワークフローに最適化されています。

主な機能

• 新規または既存のブランチから、決定論的な命名で worktree を作成
• worktree ごとに競合しないポートを自動割り当てし、割り当てを永続化
• メインリポジトリのローカル環境ファイル（.env*）を新しい worktree にコピー
• ロックファイルを検出して依存関係を任意でインストール
• クリーンアップ前に古くなった worktree と未コミットの変更を検出
• マージ済みブランチを特定し、古くなった worktree を安全に削除

使用する場面

• ローカルで 2 つ以上のブランチを同時に開く必要がある場合
• 機能開発、緊急修正、PR の検証用に分離された開発サーバーが必要な場合
• 同じブランチを共有してはならない複数のエージェントと作業している場合
• 現在のブランチがブロックされているものの、すぐに修正をリリースする必要がある場合
• 場当たり的な rm -rf 操作ではなく、再現可能なクリーンアップを行いたい場合

主なワークフロー

1. 必要な準備をすべて整えた worktree を作成する

1. ブランチ名と worktree 名を決めます。
2. マネージャースクリプトを実行します（ブランチが存在しない場合は作成します）。
3. 生成されたポートマップを確認します。
4. 割り当てられたポートを使ってアプリを起動します。

python scripts/worktree_manager.py \
  --repo . \
  --branch feature/new-auth \
  --name wt-auth \
  --base-branch main \
  --install-deps \
  --format text

JSON の自動化入力を使用する場合：

cat config.json | python scripts/worktree_manager.py --format json
# or
python scripts/worktree_manager.py --input config.json --format json

2. セッションを並行して実行する

推奨する規約：

• メインリポジトリ：統合ブランチ（main/develop）をデフォルトのポートで使用
• Worktree A：機能ブランチとオフセットポート
• Worktree B：緊急修正ブランチと次のオフセット

各 worktree には、割り当てられたポートが記録された .worktree-ports.json が含まれます。

3. 安全確認を行ってクリーンアップする

1. すべての worktree と古くなった期間をスキャンします。
2. 変更のあるツリーとブランチのマージ状況を確認します。
3. マージ済みかつ変更のない worktree のみを削除するか、明示的に強制します。

python scripts/worktree_cleanup.py --repo . --stale-days 14 --format text
python scripts/worktree_cleanup.py --repo . --remove-merged --format text

4. Docker Compose のパターン

割り当てられたポートを反映した worktree ごとのオーバーライドファイルを使用します。スクリプトは決定論的なポートマップを出力します。それを docker-compose.worktree.yml に適用してください。

具体的なテンプレートについては、docker-compose-patterns.md を参照してください。

5. ポート割り当て戦略

デフォルトの戦略は、競合チェックを伴う base + (index * stride) です。

• アプリ：3000
• Postgres：5432
• Redis：6379
• ストライド：10

戦略全体と特殊なケースについては、port-allocation-strategy.md を参照してください。

スクリプトのインターフェース

• python scripts/worktree_manager.py --help
  • worktree の作成と一覧表示
  • ポートの割り当てと永続化
  • .env* ファイルのコピー
  • 依存関係の任意のインストール
• python scripts/worktree_cleanup.py --help
  • 経過期間による古くなった worktree の検出
  • 変更状態の検出
  • マージ済みブランチの検出
  • 安全な削除（任意）

どちらのツールも、自動化パイプライン向けの標準入力 JSON と --input ファイルモードをサポートしています。

よくある落とし穴

1. メインリポジトリのディレクトリ内に worktree を作成する
2. すべてのブランチで localhost:3000 を使い回す
3. 分離された機能ブランチ間で 1 つのデータベース URL を共有する
4. 未コミットの変更がある worktree を削除する
5. ブランチの削除後、古いメタデータを整理し忘れる
6. 対象ブランチとの比較を確認せずに、マージ済みだと判断する

ベストプラクティス

1. worktree ごとにブランチを 1 つ、エージェントを 1 つ割り当てます。
2. worktree は短期間だけ使用し、マージ後に削除します。
3. 決定論的な命名パターン（wt-<topic>）を使用します。
4. ポートのマッピングはメモリやターミナルのメモではなく、ファイルに保存します。
5. アクティブなリポジトリでは、毎週クリーンアップスキャンを実行します。
6. 自動処理には --format json を、人による確認には --format text を使用します。
7. 変更を意図的に破棄する場合を除き、変更のある worktree を強制削除してはいけません。

検証チェックリスト

セットアップ完了と判断する前に、以下を確認してください。

1. git worktree list に想定したパスとブランチが表示される。
2. .worktree-ports.json が存在し、一意のポートが含まれている。
3. （元のリポジトリに存在する場合）.env ファイルのコピーが正常に完了している。
4. （有効化されている場合）依存関係のインストールコマンドが終了コード 0 で終了する。
5. クリーンアップのスキャンで、意図しない古いダーティツリーが報告されない。

参考資料

• port-allocation-strategy.md
• docker-compose-patterns.md
• クイックスタートとインストールの詳細については、README.md を参照してください。

判断マトリックス

新しいワークツリーを作成する前に、この簡易ガイドを使用してください。

• 依存関係とサーバーポートを分離する必要がある -> 新しいワークツリーを作成します
• ローカルの差分をすばやく確認するだけでよい -> 現在のツリーを使います
• フィーチャーブランチに未コミットの変更がある状態でホットフィックスが必要 -> 専用のホットフィックス用ワークツリーを作成します
• バグのトリアージ用に一時的な再現ブランチが必要 -> 一時的なワークツリーを作成し、同日中にクリーンアップします

運用チェックリスト

作成前

1. メインリポジトリにクリーンなベースラインがあること、または意図したWIPコミットがあることを確認します。
2. 対象ブランチの命名規則を確認します。
3. 必要なベースブランチ（main／develop）が存在することを確認します。
4. リポジトリに属さないサービスが、予約済みのローカルポートをすでに使用していないことを確認します。

作成後

1. git status に表示されるブランチが想定したブランチと一致することを確認します。
2. .worktree-ports.json が存在することを確認します。
3. 割り当てられたアプリポートでアプリが起動することを確認します。
4. データベースとキャッシュのエンドポイントが、分離されたポートを指していることを確認します。

削除前

1. ブランチにアップストリームが設定され、意図した場合はマージ済みであることを確認します。
2. コミットされていないファイルが残っていないことを確認します。
3. 実行中のコンテナーやプロセスが、このワークツリーのパスに依存していないことを確認します。

CIとチームの連携

• タスクIDに対応するワークツリーパスの命名規則を使用します（wt-1234-auth）。
• 誤ったウィンドウでコミットしないよう、ターミナルのタイトルにワークツリーパスを含めます。
• 自動化されたセットアップでは、作成時のメタデータをCIのアーティファクト／ログに保存します。
• スケジュールされたジョブでクリーンアップレポートを実行し、概要をチームチャンネルに投稿します。

障害からの復旧

• 既存のパスが原因で git worktree add に失敗した場合：パスを調査し、上書きしないでください。
• 依存関係のインストールに失敗した場合：ワークツリーは作成したままにし、ステータスを記録して手動での復旧を続けます。
• 環境変数ファイルのコピーに失敗した場合：警告と不足しているファイルの一覧を明示して続行します。
• 外部サービスとのポートの競合が発生した場合：ベースポートを調整して再実行します。