Claude Worktree 完全ガイド

はじめに

Claude Code で複雑なタスクを処理する際、こんな困りごとに遭遇したことはありませんか？3つの独立したタスクを処理する必要があるのに、同じディレクトリで複数の Claude インスタンスを実行するとコードが衝突する——一つの Agent がファイルを修正中に、もう一つも同じファイルを変更し、最後のマージ時に大混乱になる。

2025年2月、Anthropic は --worktree コマンドをリリースし、この状況を根本的に変えました。これで、3つのターミナルでそれぞれ claude -w feature-1、claude -w feature-2、claude -w bugfix-1 を実行でき、3つの Agent がそれぞれ隔離された環境で作業し、互いに干渉しません。

Worktree を理解する

あなたが建築家で、同時に3つの異なる部屋を設計していると想像してください。従来の方法は同じ図面上で描くことですが、修正を繰り返すと混乱しやすくなります。Worktree のアプローチは、3枚の独立した図面を提供し、各図面を1つの部屋の設計に専用し、最後にメイン図面に統合するというものです。

技術的に言えば、Worktree は Git のネイティブ機能です。Claude Code の --worktree コマンドはこの機能をよりシンプルに使えるようにラップしています——1つのコマンドで隔離環境の作成、Claude インスタンスの起動、完了後の自動クリーンアップが行えます。

なぜ直接複数回 Clone しないのか

こう思うかもしれません：なぜ直接コードを複数回 clone しないのか？

Worktree は同じ .git データベースを共有し、すべてのコミット履歴やブランチ情報が共有されます。これは、1つの worktree で作成した commit が他の worktree ですぐに表示されることを意味します。

いつ Worktree を使うべきか

作業を始める前に、タスクが worktree に適しているかどうかを判断しましょう。

経験則：タスクが30分以上かかるなら、worktree の使用を検討しましょう。短いタスクでは worktree はかえって時間の無駄です——環境の作成、依存関係のインストール、最後のマージを合計すると、タスク自体より長くかかる可能性があります。しかし、深い作業が必要なタスクでは、worktree の隔離性は非常に価値があります。

前提条件

worktree を使用する前に、以下の条件を満たしていることを確認してください：

完全なワークフロー：作成からクリーンアップまで

以下、実際の開発順序に沿って、Worktree の作成から最終的なクリーンアップまでの完全なフローを見ていきましょう。

ステップ1：Worktree の作成

リモートデフォルトブランチからの作成

-w または --worktree パラメータで Claude を起動します：

# "feature-auth" という名前の worktree を作成し Claude を起動
claude -w feature-auth

# ランダム名を自動生成（例："bright-running-fox"）
claude -w

このコマンドは実際に4つのことを行います：

1. <repo>/.claude/worktrees/feature-auth/ に新しい作業ディレクトリを作成
2. worktree-feature-auth という名前の新しいブランチを作成
3. リモートデフォルトブランチ（例：origin/main や origin/master）からコードをチェックアウト——注意：現在いるブランチではありません
4. 新しいディレクトリで Claude Code を起動

すべての worktree は .claude/worktrees/ ディレクトリ下にあります：

your-project/
├── .claude/
│   └── worktrees/
│       ├── feature-auth/      ← 最初の worktree
│       ├── bugfix-123/        ← 2番目の worktree
│       └── refactor-api/      ← 3番目の worktree
├── src/
└── package.json

このパスを .gitignore に追加することをお勧めします：

# .gitignore
.claude/worktrees/

現在の/特定のブランチからの作成

-w は常にリモートデフォルトブランチからチェックアウトし、現在はベースブランチの指定をサポートしていません。現在のブランチ（または特定のブランチ）をベースに worktree を作成したい場合は、3つの方法があります：

方法1：手動で Git を使って作成

# 現在の HEAD をベースに worktree を作成
git worktree add -b my-feature .claude/worktrees/my-feature HEAD

# または特定のブランチをベースに
git worktree add -b hotfix .claude/worktrees/hotfix origin/release-v2

# そのディレクトリで Claude を起動
cd .claude/worktrees/my-feature && claude

この方法は完全な制御を提供します——任意のブランチ、任意の commit をベースに worktree を作成でき、作業ディレクトリは最初から正しいブランチにあります。公式ドキュメントでも推奨されています：「ブランチと場所のより細かい制御が必要な場合は、Git で直接 worktree を作成し、そのディレクトリで Claude を実行してください。」

方法2：会話中に作成（推奨）

既存の Claude セッション内で、直接 Claude に worktree を作成させます：

> 現在のブランチから worktree を開いて
> start a worktree

-w コマンドとは異なり、会話中に作成された worktree は自動的に現在のブランチをベースにし、リモートデフォルトブランチではありません。Claude は自動的に worktree の作成と切り替えを完了し、Git コマンドを手動で操作する必要はありません。すでに feature ブランチで作業中なら、これが最も便利な方法です——一言で現在のブランチベースの隔離環境を作れます。

方法3：先に -w で作成し、会話中にブランチを切り替え

先に claude -w で worktree を作成し、会話に入ってから Claude にターゲットブランチへの切り替えを指示します。この方法の欠点は、まずリモートデフォルトブランチをプルしてから切り替えるため、一手間多くなることです。最初の2つの方法ほどクリーンではありません。また、ターゲットブランチが他の worktree で既に使用されている場合、ブランチの衝突に遭遇します：

スクリーンショットに示されているように、Claude はブランチの衝突を検出し、2つの選択肢を提示します：メインディレクトリに戻って操作するか、ターゲットブランチをベースに新しい作業ブランチを作成するか。最終的には動作しますが、方法1と方法2ほどダイレクトではありません。

応用：Makefile でワンコマンド化

現在のブランチから worktree を頻繁に作成する場合は、プロジェクトルートの Makefile にショートカットコマンドを追加し、作成 + エディタ起動 + Claude 起動を確定的なパイプラインとして連結できます：

# 現在のブランチから worktree を作成し、開発環境を起動
# 使い方: make worktree name=my-feature
worktree:
	@if [ -z "$(name)" ]; then \
		echo "使い方: make worktree name=<worktree-name>"; \
		echo "例: make worktree name=fix-login-bug"; \
		exit 1; \
	fi
	@echo "→ $$(git branch --show-current) から worktree を作成: $(name)"
	git worktree add -b $(name) .claude/worktrees/$(name) HEAD
	@echo "→ 環境を初期化"
	cd .claude/worktrees/$(name) && npm install
	@echo "→ Zed で開く"
	zed .claude/worktrees/$(name)
	@echo "→ Claude を起動"
	cd .claude/worktrees/$(name) && claude

使い方は非常にシンプルです：

# 現在のブランチベースで worktree を作成、Zed で開き、Claude を起動
make worktree name=fix-login-bug

# 複数の並行タスクを開始
make worktree name=feature-search
make worktree name=refactor-api

複数の Git/cd/claude コマンドを手動で入力するのと比べ、make worktree name=xxx は1行で済み、毎回実行するフローが完全に一貫します——ステップを忘れることも、パスを間違えることもありません。注意点として、Makefile はネイティブの git worktree add を使用するため、Claude Code の WorktreeCreate Hook はトリガーされません（このフックは claude -w または会話中に worktree を作成する場合のみ有効）。そのため、環境初期化ステップ（依存関係のインストール、.env のコピーなど）は上記の例の npm install のように、Makefile に直接記述する必要があります。

ステップ2：環境の初期化

Worktree の作成が完了したら、最初にやるべきことは開発環境の初期化です。各新しい worktree は独立したディレクトリであり、node_modules、仮想環境、.env ファイルなどは自動的に持ち込まれません。

Claude Code は WorktreeCreate Hook を提供して環境セットアップを自動化します：

{
  "hooks": {
    "WorktreeCreate": [
      {
        "command": "npm install && cp ../.env .env"
      }
    ]
  }
}

これにより worktree 作成時に依存関係が自動インストールされ、環境変数ファイルが自動コピーされます。一般的な初期化ステップ：

Hook を設定していない場合は、各 worktree セッションの開始時に /init を実行して、Claude が現在の作業ディレクトリのコンテキストを正しく理解し、プロジェクト構造と CLAUDE.md 設定を再読み込みするようにできます。

ステップ3：コミットとマージ

環境が整い、開発が完了したら、次のステップは変更をターゲットブランチにマージすることです。

main ブランチへのマージ

最も一般的なケース——worktree が origin/main から分岐し、変更も main にマージする。worktree の Claude セッション内で直接言います：

> すべての変更をコミットして、リモートにプッシュして、main への PR を作成して

Claude が自動的に commit → push → gh pr create の全フローを完了します。

feature ブランチへのマージ

feature-x ブランチで開発していて、worktree の変更を main ではなく feature-x にマージする必要がある場合：

> 変更をコミットしてプッシュして、feature-x ブランチへの PR を作成して

Claude は gh pr create --base feature-x を実行し、feature ブランチを指す PR を直接作成します。

worktree セッションを終了した後（worktree を保持する選択をした場合）、メインディレクトリに戻って Claude を起動することもできます：

> worktree-my-task ブランチの変更を現在のブランチにマージして

worktree 内の一部のコミットが不要な場合は、選択的に cherry-pick できます：

> worktree-my-task ブランチのコミット履歴を確認して、認証モジュールに関するコミットを現在のブランチに cherry-pick して

ヒント：すべての worktree は同じ .git データベースを共有しているため、worktree で作成したコミットはメインディレクトリですぐに表示されます。追加の push/pull 操作は不要です。

ステップ4：終了とクリーンアップ

コードのマージが完了したら、worktree セッションを終了できます。

worktree セッション終了時、Claude は状況に応じて自動的に処理します：

保持された worktree はそのまま残り、後で作業を続けるのに便利です。

WorktreeRemove Hook を設定してクリーンアップを自動化することもできます：

{
  "hooks": {
    "WorktreeRemove": [
      {
        "command": "echo 'Worktree cleaned up'"
      }
    ]
  }
}

手動管理コマンド

worktree を手動で管理する必要がある場合は、標準の Git コマンドを使用できます：

# すべての worktree を一覧表示
git worktree list

# 特定の worktree を手動削除
git worktree remove .claude/worktrees/feature-auth

# 古い worktree 参照をクリーンアップ
git worktree prune

注意：worktree ディレクトリを直接 rm -rf で削除しないでください。正しい方法は git worktree remove を使用することです。誤って削除した場合は、git worktree prune を実行して残留する参照をクリーンアップしてください。

並行開発モード

基本的なワークフローをマスターしたら、worktree を活用して並行開発を実現する方法を見てみましょう。

マルチターミナル並行

最も一般的な使い方は、複数のターミナルタブで同時に実行することです：

# ターミナル1：ユーザー認証機能の処理
claude -w feature-auth

# ターミナル2：決済バグの修正
claude -w bugfix-payment

# ターミナル3：API モジュールのリファクタリング
claude -w refactor-api

各 Claude インスタンスは自身の worktree で動作し、変更は互いに影響しません。以下のことができます：

• 1つのターミナルで Claude に新機能を開発させる
• もう1つのターミナルで Claude にバグを修正させる
• 3番目のターミナルで自分のコードレビューを続ける

競合的実装

効率的な使い方の1つは、複数の Agent に同じ機能を独立して実装させることです：

# 3つのターミナルでそれぞれ実行
claude -w feature-search-v1
claude -w feature-search-v2
claude -w feature-search-v3

同じ要件説明を与え、各自に実装させます。最後に3つの方案を比較し、最良のものをマージします。これは LLM の非決定性を活用しています——同じ入力から異なる出力が生まれ、時には2番目のバージョンの方が良いこともあります。

UI デザイン探索にもこのモードは非常に適しています。アプリケーションのインターフェースを再デザインしたいが、どのスタイルが良いか分からない場合：

# 3つの Agent にそれぞれ異なるスタイルで実装させる
claude -w ui-minimal    # ミニマリストスタイル
claude -w ui-colorful   # 鮮やかな配色
claude -w ui-glassmorphism  # すりガラスモーフィズムスタイル

完了後、3つのバージョンの開発サーバーを同時に実行（異なるポート）し、並べて効果を比較し、最も満足できる方案をメインブランチにマージします——従来の「1版作って、効果を見て、不満なら再修正」のフローよりはるかに効率的です。

Subagent の隔離

Worktree はメインの Claude インスタンスだけでなく、Subagent にも適用できます。カスタム Subagent の frontmatter に isolation: worktree を追加します：

---
name: code-migrator
description: Handles large-scale code migrations. Use for batch refactoring.
tools: Read, Write, Edit, Bash, Grep, Glob
isolation: worktree
---

You are a code migration specialist...

会話中に直接 Claude に伝えることもできます：

> agent を隔離するために worktree を使って
> use worktrees for your agents

Subagent が worktree 隔離で設定されている場合：

メイン Agent（メインディレクトリ）
│
├── Migration Agent 1 を起動 ──→ worktree-migration-1/
│   └── src/auth/ ディレクトリを処理
│
├── Migration Agent 2 を起動 ──→ worktree-migration-2/
│   └── src/api/ ディレクトリを処理
│
└── Migration Agent 3 を起動 ──→ worktree-migration-3/
    └── src/utils/ ディレクトリを処理

各 Subagent は自身の worktree で独立して動作し、互いに干渉しません。完了後、worktree は自動的にクリーンアップされます（未コミットの変更がない場合）。

Tmux と IDE の組み合わせ

--tmux パラメータと組み合わせることで、新しい Tmux セッション内で自動起動でき、ターミナルを閉じても Claude はバックグラウンドで実行し続けます：

claude -w feature-auth --tmux

VS Code や Cursor を使用している場合、ソースコントロールパネルがすべての worktree を自動認識します——メインリポジトリが1つの repo として表示され、各 worktree が独立した repo として表示され、IDE 内で直接切り替え、コミット、プッシュができます。Worktree は Ralph ループと組み合わせることもでき、各 Ralph ループが独自の worktree で実行され、ループが失敗してもメインブランチに影響しません。

注意事項とベストプラクティス

よくある落とし穴

1. ブランチの出自を間違えやすい：-w で作成された worktree はリモートデフォルトブランチからチェックアウトされ、現在いるブランチではありません。feature-x ブランチで claude -w my-task を実行すると、新しい worktree のコードは origin/main から取得され、feature-x の変更は含まれません。現在のブランチベースで作業したい場合は、現在の/特定のブランチからの作成を参照してください。
2. 未コミットの変更は持ち込まれない：worktree 作成時、メインディレクトリ内の未ステージングまたは未コミットの変更は新しい worktree に表示されません。Worktree はコミット履歴のみに基づいて作成されるため、重要な変更は必ずコミットしておきましょう。
3. 同一ブランチを複数の Worktree で使用できない：Git は2つの worktree が同時に同じブランチをチェックアウトすることを許可しません。メインディレクトリで既に feature-x ブランチにいる場合、worktree で feature-x をチェックアウトしようとするとエラーになります。各 worktree は異なるブランチにある必要があります。
4. 環境の再初期化が必要：各新しい worktree には node_modules などのランタイム依存関係が含まれないため、WorktreeCreate Hook を設定して自動化することをお勧めします（ステップ2：環境の初期化を参照）。

使用上のアドバイス

欲張りすぎないこと。技術的には多くの worktree を開けますが、各 Claude インスタンスは API クォータを消費し、あまりに多くの並行タスクは追跡が難しくなり、最終的なマージ時のコンフリクトもより複雑になります。

命名規則：良い命名習慣を身につけると、後の管理が楽になります：

# 良い命名
claude -w feature-user-auth
claude -w bugfix-payment-123
claude -w refactor-api-v2

# 悪い命名
claude -w test
claude -w temp
claude -w 1

非 Git バージョン管理

SVN、Perforce、Mercurial を使用している場合は、WorktreeCreate と WorktreeRemove Hook を設定して同様の隔離効果を実現できます。これらの Hook を設定すると、--worktree 使用時にデフォルトの Git 動作の代わりにカスタムコマンドが呼び出されます。

おわりに

Worktree は Claude Code チームが毎日使用している機能で、Boris Cherny は「ナンバーワンの生産性テクニック」と呼んでいます。核心的な価値はシンプルです：複数の Agent が互いに干渉することなく並行して作業できるようにすること。

始め方はシンプルです：

claude -w your-task-name

関連記事：

• Claude Subagent 完全ガイド — Subagent と Worktree の連携を理解する
• Ralph Wiggum 深層解析 — AIプログラミング効率を向上させるもう1つの方法
• Claude システムアーキテクチャ全解析 — アーキテクチャ全体における Worktree の位置を理解する

参考資料：

• Claude Code 公式ドキュメント - Common Workflows
• Boris Cherny の Worktree リリース告知
• Git Worktree 公式ドキュメント
• incident.io - Shipping faster with Claude Code and Git Worktrees
• Dev.to - Git worktree + Claude Code: My Secret to 10x Developer Productivity

動画チュートリアル：

• I'm using claude --worktree for everything now — worktree 完全ワークフローの実践デモ
• Git Worktrees: The secret sauce to Claude Code! — 手動 worktree 作成の方法
• Native Worktrees Just Killed Traditional Claude Code Workflows — ネイティブ worktree 機能の詳細解説
• Claude Code Worktrees in 7 Minutes — クイックスタートチュートリアル、Subagent の使い方を含む
• Stop Using Claude Code on One Branch — マルチ worktree 並行開発の利点