git-worktrees

Claude Code の Git Worktree

概要

Git worktree を使って、異なるブランチで複数の Claude Code セッションを並行して実行できます。このスキルでは、worktree のセットアップ、管理、クリーンアップに使えるシンプルなスクリプトとワークフローを提供し、競合のない真の並行開発を実現します。

Worktree を使う理由

• 並行開発：複数の Claude Code インスタンスを同時に実行できます
• 競合ゼロ：各 worktree はそれぞれ独立したファイル状態を持ちます
• すばやいコンテキスト切り替え：タスクを切り替える際に stash や commit をする必要がありません
• 隔離された実験：メインの作業に影響を与えずに、異なるアプローチを試せます
• 長時間実行するタスク：メインで作業を続けながら、Claude をバックグラウンドで作業させられます

---

クイックスタート

1. 新しい Worktree を作成する（とても簡単です！）

インタラクティブスクリプトを実行するだけです。

scripts/create_worktree.sh

次の処理が実行されます。

• ✅ 機能名の入力を求めます
• ✅ 新しいブランチを作成します
• ✅ worktree をセットアップします
• ✅ VS Code／エディターで開きます
• ✅ Claude Code のセットアップコマンドを表示します

これだけです！ 複雑な処理はすべてスクリプトが行います。

---

2. すべての Worktree を表示する

scripts/list_worktrees.sh

ブランチとステータスを含む、すべての worktree の見やすく整形された一覧が表示されます。

---

3. 古い Worktree をクリーンアップする

scripts/cleanup_worktrees.sh

マージ済みまたは放棄された worktree を対話形式で削除します。

---

基本的なワークフロー

パターン 1：機能の並行開発

シナリオ： 機能 A の実装を Claude に任せながら、自分は機能 B に取り組みたい場合。

手順：

1. 機能 A 用の worktree を作成します。

   scripts/create_worktree.sh
   # Enter: feature-a
   # Script creates: ../repo-feature-a/
   

2. 新しい worktree で Claude Code を開きます。

   • スクリプトがパスを出力します
   • Claude Code を開き、そのディレクトリに移動します
   • /init を実行して、Claude が作業内容を把握できるようにします

3. Claude にタスクを指示します。

   "Build the user authentication feature with OAuth support"
   

4. メインで作業を続けます。

   • 元のディレクトリに変更はありません
   • 競合も待ち時間もありません
   • Claude が並行して作業します

5. 両方の作業が終わったら、マージします。

   # Review Claude's work
   cd ../repo-feature-a
   git log
   
   # If good, merge back
   git checkout main
   git merge feature-a
   
   # Clean up
   scripts/cleanup_worktrees.sh
   

---

パターン 2：長時間実行するリファクタリング

シナリオ： 開発を続けながら、大きなモジュールのリファクタリングを Claude に任せたい場合。

手順：

1. リファクタリング用の worktree を作成します。

   scripts/create_worktree.sh
   # Enter: refactor-auth-module
   

2. リファクタリング用の worktree で Claude を起動します。

   "Refactor the authentication module to use dependency injection"
   

3. メインで日々の作業を続けます。

   • 作業を中断する必要はありません
   • マージ競合もありません
   • 定期的に進捗を確認します

4. 準備ができたらレビューして取り込みます。

   cd ../repo-refactor-auth-module
   git log --oneline
   # Review changes
   
   # Merge when satisfied
   git checkout main
   git merge refactor-auth-module
   

---

パターン 3：複数の AI エージェント（上級者向け）

シナリオ： 3 つの Claude インスタンスに、それぞれ異なる機能を同時に作業させたい場合。

手順：

1. worktree を 3 つ作成します。

   scripts/create_worktree.sh  # feature-api-endpoints
   scripts/create_worktree.sh  # feature-ui-dashboard
   scripts/create_worktree.sh  # feature-email-notifications
   

2. Claude Code のセッションを 3 つ開きます。

   • セッション 1：../repo-feature-api-endpoints/
   • セッション 2：../repo-feature-ui-dashboard/
   • セッション 3：../repo-feature-email-notifications/

3. それぞれの Claude にタスクを割り当てます。

   • Claude 1：「ユーザー管理用の REST API エンドポイントを構築する」
   • Claude 2：「管理ダッシュボードの UI を作成する」
   • Claude 3：「メール通知システムを実装する」

4. 進捗を確認します。

   scripts/list_worktrees.sh
   

5. 各機能の完了に合わせてマージします。

   # Feature by feature
   git checkout main
   git merge feature-api-endpoints
   git merge feature-ui-dashboard
   git merge feature-email-notifications
   
   # Clean up
   scripts/cleanup_worktrees.sh
   

---

パターン 4：開発を続けながらホットフィックスを行う

シナリオ： Claude が機能の実装中に、本番環境のバグをすぐに修正する必要がある場合。

手順：

1. Claude はすでに機能用の worktree で作業しています。

   • 中断せず、そのまま続けさせます

2. main からホットフィックス用の worktree を作成します。

   scripts/create_worktree.sh
   # Enter: hotfix-login-bug
   # Choose base branch: main
   

3. 自分で、または別の Claude セッションでバグを修正します。

   cd ../repo-hotfix-login-bug
   # Make fixes
   git add .
   git commit -m "Fix login redirect bug"
   

4. ホットフィックスを main にマージします。

   git checkout main
   git merge hotfix-login-bug
   git push origin main
   

5. 機能用の worktree を最新の main と同期します。

   cd ../repo-feature-xyz
   scripts/sync_worktree.sh
   # Merges latest main into feature branch
   

---

必須スクリプト

scripts/create_worktree.sh

適切なデフォルト設定で、対話形式で worktree を作成します。

実行内容：

1. 機能名の入力を求めます
2. Git リポジトリかどうかを検証します
3. main（または指定されたベース）からブランチを作成します
4. 並行作業用のディレクトリに worktree をセットアップします
5. セットアップ手順を表示します

使い方：

scripts/create_worktree.sh

# Prompts:
# Feature name: my-feature
# Base branch (default: main):
#
# Creates: ../repo-my-feature/
# Branch: my-feature

高度な使い方：

# Create from specific branch
scripts/create_worktree.sh --base develop

# Specify location
scripts/create_worktree.sh --dir ~/worktrees/my-feature

---

scripts/list_worktrees.sh

アクティブな worktree とそのステータスをすべて表示します。

出力：

╔════════════════════════════════════════════════╗
║            Active Git Worktrees                ║
╚════════════════════════════════════════════════╝

📁 Main Worktree
   Path: /home/user/project
   Branch: main
   Status: clean

📁 Feature Worktrees
   Path: /home/user/project-feature-api
   Branch: feature-api
   Status: 2 uncommitted changes

   Path: /home/user/project-refactor
   Branch: refactor-auth
   Status: clean

---

scripts/cleanup_worktrees.sh

古い worktree を対話形式でクリーンアップします。

機能：

• マージ状況とともにすべての worktree を一覧表示します
• マージ済みのブランチ（安全に削除できます）を特定します
• 確認を求めます
• worktree とブランチを安全に削除します

使用方法：

scripts/cleanup_worktrees.sh

# Output:
# Found 3 worktrees
#
# 1. feature-api (merged to main) - Safe to remove
# 2. feature-dashboard (not merged) - Keep
# 3. old-experiment (not merged, 30 days old) - Consider removing
#
# Which worktrees to remove? (1,3): 1

---

scripts/sync_worktree.sh

worktree を main ブランチと同期した状態に保ちます。

処理内容：

1. リモートから最新の変更を取得します
2. main を現在の worktree のブランチにマージします
3. ガイダンスを示しながら競合に対処します

使用方法：

# From within a worktree
cd ../repo-feature-api
scripts/sync_worktree.sh

# Or specify worktree
scripts/sync_worktree.sh ../repo-feature-api

---

Claude Code との連携

重要：各 worktree で /init を実行する

worktree で新しい Claude Code セッションを開いたら、必ず最初に /init を実行してください：

/init

これにより、Claude は次のことができるようになります：

• コードベースの構造を理解します
• 適切なコンテキストを把握します
• ファイルを正しく参照できます

Claude Code の推奨ワークフロー

1. worktree を作成する（スクリプトを使用）
2. worktree ディレクトリで Claude Code を開く
3. Claude に状況を把握させるため /init を実行する
4. Claude に タスクを指示する
5. git log またはファイルの監視で 進捗を確認する
6. 完了したら レビューする
7. 問題がなければ マージする
8. worktree を クリーンアップする

---

ベストプラクティス

命名規則

良い名前：

• feature-user-auth ✅
• refactor-api-layer ✅
• hotfix-login-bug ✅
• experiment-new-db ✅

悪い名前：

• test ❌（曖昧すぎます）
• wt1 ❌（意味がありません）
• fixes ❌（不明瞭です）

推奨形式：

<type>-<short-description>

Types:
- feature-*
- refactor-*
- hotfix-*
- experiment-*
- review-*

---

ディレクトリ構成

推奨レイアウト：

~/projects/
  └── myapp/              # Main worktree (main branch)
      ├── myapp-feature-api/      # Feature worktree
      ├── myapp-refactor-auth/    # Refactor worktree
      └── myapp-hotfix-bug/       # Hotfix worktree

スクリプトはデフォルトで、メインディレクトリと同じ階層に、<repo>-<branch-name> という命名パターンで worktree を作成します。

---

worktree を使用する場面

✅ 次の場合は worktree を使用します：

• 複数の Claude Code セッションを並行して実行する場合
• 独立した機能を同時に開発する場合
• 長時間にわたるリファクタリングを行う場合
• 大規模な変更を試す場合
• 機能開発中に素早くホットフィックスを適用する場合
• 作業を中断せずにコードレビューを行う場合

❌ 次の場合は worktree を使用しないでください：

• 単純なブランチ切り替え（git checkout を使用してください）
• 小規模な変更（代わりに stash を使用してください）
• 単一タスクのワークフロー
• 寿命が非常に短いブランチ（1 時間未満）

---

worktree の同期を維持する

**問題：**機能ブランチが main に対して古くなることがあります。

**解決策：**worktree を定期的に同期します：

# Option 1: Use the sync script
cd ../repo-feature-api
scripts/sync_worktree.sh

# Option 2: Manual sync
cd ../repo-feature-api
git fetch origin
git merge origin/main

推奨頻度：

• 長期にわたる機能開発では毎日
• main に大きなマージがあった後
• PR を作成する前

---

多数の worktree の管理

すべての worktree の簡易ステータス：

scripts/list_worktrees.sh

定期的なクリーンアップ（毎週）：

scripts/cleanup_worktrees.sh

古い worktree の検索：

# Worktrees with old commits
git worktree list | while read path branch commit; do
  cd "$path"
  last_commit=$(git log -1 --format=%cr)
  echo "$branch: Last commit $last_commit"
done

---

トラブルシューティング

問題：「fatal: invalid reference」

**原因：**ブランチ名に無効な文字が含まれています

**解決策：**英数字とハイフンのみを使用してください：

# Bad
feature/my_feature  ❌

# Good
feature-my-feature  ✅

---

問題：「cannot remove worktree, path is not a working tree」

**原因：**worktree ディレクトリが手動で削除されました

**解決策：**worktree の参照を整理します：

git worktree prune

---

問題：worktree 内で Claude が「迷子」になったように見える

**原因：**worktree を開いた後に /init を実行していません

**解決策：**新しい worktree で Claude を起動するときは、必ず /init を実行してください：

/init

---

問題：worktree の同期時にマージ競合が発生する

**原因：**worktree 内の変更が main と競合しています

**解決策 1：**競合を手動で解決します：

cd ../repo-feature-api
git fetch origin
git merge origin/main
# Fix conflicts in editor
git add .
git commit -m "Merge main and resolve conflicts"

**解決策 2：**worktree の変更を破棄してやり直す場合：

cd ../repo-feature-api
git fetch origin
git reset --hard origin/main
# Start feature over

---

問題：「Cannot lock ref」エラー

**原因：**複数の worktree に同じブランチが存在しています

**解決策：**同じブランチを複数の worktree でチェックアウトすることはできません。新しいブランチを作成してください：

scripts/create_worktree.sh
# Use a different branch name

---

問題：worktree がディスク容量を使いすぎる

**原因：**Git worktree は .git ディレクトリを共有しますが、ファイルは複製されます

**解決策 1：**古い worktree をクリーンアップします：

scripts/cleanup_worktrees.sh

**解決策 2：**大規模なリポジトリでは、スパースチェックアウトを使用します：

git -C ../repo-feature-api sparse-checkout set src/ tests/

---

高度な使い方

カスタムスラッシュコマンド

Claude Code 用の /worktree コマンドを作成します。設定の全手順については、references/slash_command_template.md を参照してください。

設定後の使い方：

/worktree feature-new-api

Claude は次の操作を行います。

1. worktree を作成します
2. セットアップ手順を提示します
3. 新しい worktree で会話を続けるかどうかを尋ねます

---

チームでの worktree の共有

worktree はローカルにのみ存在しますが、ワークフローは共有できます。

1. worktree ではなくブランチを共有します。

   cd ../repo-feature-api
   git push origin feature-api
   
   # Teammate creates their own worktree
   git worktree add ../repo-feature-api feature-api
   

2. チームのドキュメントに worktree の構成を記載します

3. チーム内で一貫した命名規則を使用します

---

worktree のパフォーマンス最適化

大規模なリポジトリの場合：

1. sparse-checkout を使用します（必要なファイルのみをチェックアウトします）。

   git -C ../repo-feature-api sparse-checkout init
   git -C ../repo-feature-api sparse-checkout set src/ tests/
   

2. worktree prune を定期的に実行します。

   git worktree prune
   

3. 最適なパフォーマンスを得るため、同時に使用する worktree は 3～5 個に制限します

---

よく使うワークフローのまとめ

クイックリファレンス

タスク	コマンド
新しい worktree を作成	scripts/create_worktree.sh
すべての worktree を一覧表示	scripts/list_worktrees.sh
worktree をクリーンアップ	scripts/cleanup_worktrees.sh
main と同期	scripts/sync_worktree.sh
手動で作成	git worktree add ../path branch-name
手動で一覧表示	git worktree list
手動で削除	git worktree remove ../path
参照を整理	git worktree prune

---

実際の使用例

例 1：API と UI の並行開発

セットアップ：

# Create API worktree
scripts/create_worktree.sh
# Name: feature-api

# Create UI worktree
scripts/create_worktree.sh
# Name: feature-ui

実行：

• ../repo-feature-api の Claude 1：「ユーザー管理用の REST API を構築する」
• ../repo-feature-ui の Claude 2：「ユーザー管理用の React UI を作成する」
• main のあなた：ほかの作業を続ける

マージ：

git checkout main
git merge feature-api
git merge feature-ui
scripts/cleanup_worktrees.sh

---

例 2：コンテキストを切り替えずにコードレビュー

シナリオ： Claude が機能開発を進めている間に、PR をレビューする必要がある

セットアップ：

# Claude is working in feature worktree
# You need to review PR #123

scripts/create_worktree.sh
# Name: review-pr-123
# Base: pr-branch-name

実行：

• ../repo-review-pr-123 でコードをレビューする
• Claude は ../repo-feature-xyz で作業を続ける
• コンテキストを切り替える必要はありません

クリーンアップ：

# After review
scripts/cleanup_worktrees.sh
# Select review-pr-123

---

例 3：リスクを避けた実験

シナリオ： 現在の作業を壊さずに、大幅なリファクタリングを試したい

セットアップ：

scripts/create_worktree.sh
# Name: experiment-new-architecture

実行：

• ../repo-experiment-new-architecture で自由に実験する
• メインの worktree は安定した状態を維持する
• 実験が失敗した場合は、worktree を削除するだけです

判断：

# If experiment succeeded
git checkout main
git merge experiment-new-architecture

# If experiment failed
scripts/cleanup_worktrees.sh
# Delete experiment worktree (no harm done)

---

生産性を最大限に高めるヒント

1. worktree にわかりやすい名前を付ける

• worktree を 5 個開くようになったとき、きっと助かります

2. 必ず /init を実行する

• 新しい worktree で Claude を開いたら、最初に実行します

3. こまめにマージする

• worktree を何週間も別々の状態にしないでください
• 定期的に main と同期します

4. 毎週クリーンアップする

• 毎週金曜日に scripts/cleanup_worktrees.sh を実行します
• 作業環境を整理しておきます

5. スクリプトを使用する

• git worktree のコマンドを暗記する必要はありません
• スクリプトが特殊なケースや検証を処理します

6. 進捗を確認する

• scripts/list_worktrees.sh を使用して、アクティブな worktree を確認します
• worktree の git ログを定期的に確認します

7. 同時に実行するセッション数を制限する

• 最適なパフォーマンスを得るため、worktree は最大 3～5 個にします
• それ以上になると管理が難しくなります

---

リソース

スクリプト

• create_worktree.sh - 対話形式で worktree を作成します
• list_worktrees.sh - アクティブな worktree をすべて表示します
• cleanup_worktrees.sh - 古い worktree を削除します
• sync_worktree.sh - worktree を同期した状態に保ちます

参考資料

• worktree_commands.md - Git worktree コマンドの完全なリファレンス
• best_practices.md - ベストプラクティスとパターンの詳細
• slash_command_template.md - カスタム /worktree コマンドの作成

---

まとめ

Git worktree を使うと、Claude Code で真の並行開発が可能になります。

✅ 複数の Claude セッションを競合なく実行できます
✅ stash せずに、すぐにコンテキストを切り替えられます
✅ メインの作業を壊すことなく、安全に実験できます
✅ シンプルなスクリプトが、複雑な処理をすべて担います
✅ よくあるシナリオに対応した、すっきりしたワークフローを実現できます

始めましょう：

scripts/create_worktree.sh

以上です！ スクリプトを使えば、worktree を簡単かつ実用的に利用できます。