git-worktree-manager

git-worktree-manager skill の概要

git-worktree-manager でできること

git-worktree-manager は、複数のローカル Git worktree を、ブランチ、ポート、環境、クリーンアップの衝突なしに運用するためのエンジニアリング向け skill です。運用上のガイドラインに加えて、準備済みの worktree を作成し、決定的なポートを割り当て、ローカル環境ファイルをコピーし、必要に応じて依存関係をインストールし、削除前に古い worktree を確認する Python 補助スクリプトが含まれています。

通常の git worktree コマンドだけでは足りず、各ブランチをそれぞれ独立して起動できるアプリのように扱いたい場合に、この skill が役立ちます。

並行 Git ワークフローに向いているケース

最も相性がよいのは、機能開発、ホットフィックス、PR レビュー、移行テスト、複数エージェントによる実装などで、2 つ以上のブランチを同時に開いておく開発者、テックリード、コーディングエージェント運用者です。git-worktree-manager for Git Workflows は、各エージェントやターミナルセッションが 1 つのブランチと 1 つの分離された実行環境を持ち、単一の checkout を共有しない運用で特に有効です。

一方で、たまにブランチを切り替えるだけの場合、ローカルサービスを起動しない場合、または社内で成熟した worktree ラッパーがすでにある場合は、導入メリットは小さめです。

インストール前に見るべき違い

この skill の実用上の価値は、単に「worktree を作る」ことではありません。次のような反復可能な運用ルールを追加します。

• 決定的な worktree 名付けとブランチ作成
• アプリ、データベース、Redis の重複しないポート割り当て
• .env, .env.local, .env.development, .envrc の同期
• 一般的な lockfile からの依存関係インストール検出
• 古い worktree、dirty な worktree、マージ済みブランチのクリーンアップ確認
• worktree ごとにサービスを分離する Docker Compose パターン

そのため、git-worktree-manager skill は Git worktree に関する汎用的なプロンプトよりも、実運用に踏み込んだ内容になっています。

git-worktree-manager skill の使い方

git-worktree-manager のインストール方法

Claude 形式の skills 環境では、利用可能であれば skill manager を使ってリポジトリからインストールします。

npx skills add alirezarezvani/claude-skills --skill git-worktree-manager

手動でインストールする場合は、次の skill ディレクトリをコピーします。

engineering/skills/git-worktree-manager

コピー先は、~/.claude/skills/git-worktree-manager, ~/.codex/skills/git-worktree-manager、または互換性のある別のエージェント skill ディレクトリです。インストール後、SKILL.md, README.md, scripts/worktree_manager.py, scripts/worktree_cleanup.py と、references/ 配下の 2 つのファイルが存在することを確認してください。

最初に読むべきファイル

すばやく使い始めるには、次の順番で読むのがおすすめです。

1. README.md でコマンド形式とツール一覧を確認する。
2. SKILL.md で想定ワークフローと使うべき場面を把握する。
3. サービスポートを変更する前に references/port-allocation-strategy.md を読む。
4. アプリが Compose を使っている場合は references/docker-compose-patterns.md を読む。
5. 本番リポジトリで自動化を信頼する前に、scripts/worktree_manager.py と scripts/worktree_cleanup.py を確認する。

これは重要です。スクリプトは実際の checkout に触れ、env ファイルをコピーし、依存関係をインストールする場合があります。大規模な monorepo や、機密性の高いローカル設定を含むリポジトリで実行する前に、デフォルトの挙動を確認してください。

実践的な git-worktree-manager の使い方

典型的な作成・準備フローは次のようになります。

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

クリーンアップ確認のフローは次のとおりです。

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

どちらのツールも、--input <json-file> または stdin から JSON 入力を受け取れるため、自動化にも向いています。まずエージェントにコマンド計画を出させ、リポジトリパス、ブランチ名、ベースブランチ、依存関係インストールの扱い、クリーンアップ方針を確認してからスクリプトを実行してください。

出力を良くするプロンプト例

弱いプロンプト:

Set up a worktree for my feature.

よりよいプロンプト:

Use git-worktree-manager to prepare a new worktree for branch feature/billing-webhooks from main in repo /Users/me/app. Name it wt-billing-webhooks. I run app, Postgres, and Redis locally, so allocate non-conflicting ports and write the resulting mapping. Copy env files but do not install dependencies until I approve the command. Show the exact script command and any Docker Compose override I may need.

このように書くと、skill がブランチ戦略を選びやすくなり、ポート衝突を避け、.env* ファイルまわりの安全性を保ち、計画と実行を分けられます。

git-worktree-manager skill FAQ

git-worktree-manager は AI エージェント専用ですか？

いいえ。multi-agent 作業に最適化されていますが、スクリプトと運用ルールは人間の開発者にも役立ちます。主な利点は再現性です。場当たり的な shell 履歴に頼るのではなく、各 worktree に予測可能なブランチ、ディレクトリ、ポート、コピーされた env ファイル、クリーンアップ確認を持たせられます。

通常の git worktree と何が違いますか？

通常の git worktree add は、別の checkout を作成するだけです。ローカルアプリの衝突までは解決しません。git-worktree-manager は、その周辺ワークフローを追加します。ポートブロック、.worktree-ports.json、環境ファイルのコピー、任意の依存関係インストール、Docker Compose 分離の考え方、古いブランチやマージ済みブランチのクリーンアップ確認が含まれます。

初心者でも安全に使えますか？

はい。ただし、何も考えずにコマンドを実行するツールではなく、ガイド付きワークフローとして扱うことが前提です。初心者はまず一覧表示やレビュー操作から始め、--format text を使い、自動削除を避け、生成されたコマンドを実行前に確認してください。クリーンアップスクリプトは dirty な worktree をチェックしますが、どのブランチを削除してよいかは自分でも理解しておく必要があります。

この skill を使わないほうがよい場面は？

リポジトリの環境管理が特殊な場合、絶対にコピーしてはいけない secrets がある場合、依存関係のインストール方法が標準的でない場合、または社内プラットフォームがサービスポートを管理している場合は、そのまま使わないでください。その場合は、git-worktree-manager guide を出発点となるパターンとして使い、導入前にスクリプトやプロンプトをカスタマイズしてください。

git-worktree-manager skill の改善方法

git-worktree-manager により強いリポジトリ文脈を渡す

入力が具体的なほど、より安全な worktree 計画になります。次の情報を含めてください。

• 絶対リポジトリパス
• 対象ブランチとベースブランチ
• 希望する worktree ディレクトリ名
• package manager または lockfile に関する想定
• ポートが必要なサービス
• .env* ファイルをコピーしてよいか
• 依存関係インストールを許可するか
• クリーンアップの経過日数しきい値と、マージ確認用のベースブランチ

これにより推測が減り、エージェントがアプリに合わないデフォルトを前提にしてしまうリスクを抑えられます。

ポートと Docker Compose の運用ルールを調整する

参照戦略では、アプリ 3000、Postgres 5432、Redis 6379 などをデフォルトの基点とし、worktree ごとに 10 ずつずらす方式を使います。スタックにさらに多くのサービスがある場合は、より大きな連続ブロックを予約してください。worktree の外でローカルインフラを動かしている場合は、全体での衝突を避けるために基点ポートをずらします。

Docker Compose では、worktree ごとの override、.env によるポート指定、次のような一意の project name を使うのが望ましいです。

docker compose -p myapp_wt_auth up -d

これにより、ブランチ間で container、network、volume、database が衝突するのを避けられます。

よくある失敗パターンに注意する

よくある問題は、secrets のコピー、デフォルト database ポートの再利用、互換性のない migration 間での Docker volume 共有、誤った runtime での依存関係インストール、未コミット作業が残っている worktree の削除です。毎回の実行後に、dirty status、コピーされた env ファイル、選択されたポート、インストール操作をエージェントに報告させてください。

クリーンアップでは、まずレビューのみの出力から始めます。削除を有効にするのは、対象 worktree が古く、clean で、想定したベースブランチにマージ済みであることを確認してからにしてください。

最初の出力をもとに改善する

最初の計画やコマンドが出たら、最初からやり直すのではなく、焦点を絞って修正を依頼します。

Revise the git-worktree-manager command to skip dependency installation, use base branch develop, reserve ports for app, Postgres, Redis, and Mailhog, and output JSON for automation.

こうすると、skill をリポジトリ固有の実際の制約に沿わせたまま、安全性と再現性を高められます。