Claude Code Worktrees

問題: フィーチャーブランチでClaude Codeセッションが順調に進んでいるとき、本番のバグが舞い込んでくる。選択肢はどれも悪い。作業中の状態を失ってスタッシュするか、2つ目のターミナルを開いて2つのセッションが同じファイルを取り合うのを見るか、セッションを完全に中断するか。

素早い解決策: 独自のworktreeの中に2つ目のClaude Codeセッションを開く:

claude --worktree bugfix-123

新しい作業ディレクトリが.claude/worktrees/bugfix-123/に、専用のブランチworktree-bugfix-123として作成される。最初のセッションはそのまま。何もスタッシュされない。衝突もない。2つのClaude Codeセッションが並行して動き、お互いの存在を知らない。

エージェントのパターンを選ぶ場合、境界をシンプルに保つこと。1つのセッション内でサブエージェント、スラッシュコマンド、軽量な特化が必要ならAgent Fundamentalsを読む。ファイルシステムの分離、別々のブランチ、同じチェックアウトに触れてはいけない並行作業が実際の問題であれば本ページを読む。その分離の上でのオーケストレーションの形についてはAgent Patternsを読む。

Worktreesが変えること

サブエージェントやバックグラウンドエージェントを使ってClaude Codeを追い込んだことがある人なら、天井にぶつかったことがある。2つのエージェントが同時に同じファイルを編集し始める。一方がsrc/auth.tsを書き換えている間、もう一方が同じモジュールの途中にいる。戻ってくるのは半分だけ適用された変更、マージの混乱、あるいはそれ以上のひどい状態だ。

Worktreesはこれをファイルシステムレベルで解決する。それぞれが独自のブランチ、ディレクトリ、インデックスを持つリポジトリの別々のチェックアウトだ。Worktreeのサポートは Claude Code v2.1.50でファーストクラスとなり、CLIからDesktopアプリ、カスタムエージェントまで、作成、管理、削除をカバーしている。

CLI: `--worktree`フラグ

--worktreeフラグ付きでClaude Codeを起動するのが最速の入り口だ。

名前付きworktree

# 名前付きworktreeでClaudeを起動
claude --worktree feature-auth
 
# 作成されるもの:
# .claude/worktrees/feature-auth/  (作業ディレクトリ)
# Branch: worktree-feature-auth    (デフォルトのリモートブランチから分岐)

すべてのworktreeは.claude/worktrees/以下の専用フォルダに、専用ブランチとともに配置される。ディスクが許す限りいくつでも起動できる。

複数の並行セッション

# ターミナル1: 認証機能の作業
claude --worktree feature-auth
 
# ターミナル2: バグの修正
claude --worktree bugfix-123
 
# ターミナル3: リファクタリングの探索
claude --worktree experiment-new-router

3つのセッション。3つのブランチ。衝突ゼロ。各セッションはgitの全履歴を参照できるが、各セッション配下のファイルはそれぞれのtreeに存在する。

セッション途中でのworktree作成

起動時にフラグは必須ではない。実行中のセッション内で依頼できる:

You: work in a worktree
Claude: I'll create an isolated worktree for this session...

Claudeがworktreeをセットアップし、セッションをそこに移動する。会話の途中で、最初から作業を分離しておくべきだったと気づいたときに助かる。

デスクトップアプリ: 自動分離

Claude Code デスクトップアプリはさらに一歩進んでいる。すべての新しいセッションがデフォルトで独自のworktreeを持つ。

デフォルトでは、それらのworktreeは.claude/worktrees/に作成される。デスクトップの設定でパスを変更したり、Claudeが作成したブランチをグループ化するためのブランチプレフィックスを設定したりできる。セッションが終わったら、アーカイブアイコンをクリックするとworktreeとそのブランチが削除される。

つまりすべてのデスクトップセッションはデフォルトで安全だ。セッションは互いに上書きしないし、調整する必要もない。

サブエージェントのworktree分離

これがこの機能の真価だ。Claude が分散タスクのために生成する各サブエージェントは、独自のworktreeを持てる。

Claudeにエージェントを分離するよう依頼する

最も簡単な方法:

You: Use worktrees for your agents when doing this refactor

すべてのサブエージェントが独自のworktreeに配置される。編集なしで終了したworktreeは自動的に削除される。実際に変更を加えたworktreeはレビューのために残る。

並行実行で重要な理由

分離なしでは、並行サブエージェントはファイルを読み取るか、重複しないパス内に書き込むことしかできない。それは弱い境界だ。1つのエージェントが別のエージェントのレーンに入り込んだ瞬間、サイレントな衝突が発生する。

分離があれば、各エージェントはコードベース全体を単独で見られる。エージェントAがsrc/auth.tsをある方法で試みる一方、エージェントBが同じファイルを別の方法で試みることができる。両方のブランチを確認して、より良い方を選ぶ（あるいは両方のピースを組み合わせる）。

これはバッチマイグレーションで本当に輝く。1つのAPIから別のAPIに50ファイルを移行したいとする。5つのエージェントを起動し、それぞれ10ファイルを担当させ、すべて独自のworktreeで作業させる。並行して作業し、誰も邪魔されない。組み込みの/batchコマンドもこれと同じレールを使い、1つのプロンプトからworktreeで分離されたエージェントを起動してコードベース全体のマイグレーションを実行する。

分離を内蔵したカスタムエージェント

.claude/agents/以下のカスタムエージェントは、常にworktreeを使うようにピン留めできる:

---
name: refactor-agent
description: Agent that performs isolated refactoring work
isolation: worktree
---
You are a refactoring specialist. Analyze the target code,
plan the refactor, and implement changes.

フロントマターのisolation: worktreeはClaudeにこのエージェントが実行されるたびに新しいworktreeを作成するよう指示する。エージェントは完全な分離で作業し、実行終了時に空のworktreeは自動的に削除される。

Git以外のバージョン管理システムのサポート

Mercurial、Perforce、SVNを使うチームも締め出されない。Worktreeモードはカスタムフックを使って動作する。設定にWorktreeCreateとWorktreeRemoveフックを登録すると、VCS固有の分離ロジックがデフォルトのgitの動作を置き換える。

これらのフックが設定されると、--worktreeフラグとセッション内のworktreeリクエストはgitを呼び出す代わりにフックを通じてルーティングされる。フロー全体のその他の部分は変わらない。

盗む価値のある3つのWorktreeパターン

基本的なアイデアは一度見ればほとんどのチームが理解できる。通常その次に必要なのは、コピーできる動作するパターンだ。

1. フィーチャー作業を壊さずにホットフィックス

フィーチャーブランチの途中にいるとき、本番の認証バグが舞い込んでくる。

# 現在のフィーチャーセッションを生かし続ける
claude

# 2つ目の分離されたバグフィックスセッションを開く
claude --worktree hotfix-auth-timeout

これでホットフィックスはクリーンにリリースでき、フィーチャーセッションはその状態、todo、会話履歴を保持し続ける。これはworktreeの最もシンプルで価値の高い使い方であり、ほとんどのチームが最初に採用するものだ。

2. リスクのあるリファクタリングの競合実装

あるルーティングのリファクタリングに2つの可能な形があるとする。一方は現在のAPIサーフェスを保ちながら内部を移動する。もう一方は外部APIも単純化する。

両方を実行する:

claude --worktree router-safe-path
claude --worktree router-clean-slate

両方のセッションは同じファイルに触れられる。チェックアウトを共有していないからだ。後で両方のブランチをレビューして、より優れたデザインを採用する。これは1つのコンテキスト内で1つのエージェントに両方のパスを推論させようとするよりはるかに優れている。

3. 分離されたサブエージェントによるバッチマイグレーション

1つのロギングAPIを80ファイルで置き換える必要があるとする。5つのエージェントが同じチェックアウトを編集するのは避けたい。

明示的に分割を依頼する:

You: Use worktrees for agents. Split this migration into 5 batches of files.

各ワーカーに以下を与える:

リポジトリ全体のビュー
狭いファイルバッチ
分離されたブランチ
レビュー可能な結果

これがworktreeが便利な機能からではなく、実際の並行インフラとして機能し始めるポイントだ。

Worktreeを健全に保つ小さなルール

仕組みは簡単だ。チームの習慣こそがworktreeを有用に保つ:

Worktreeにはチケット番号だけでなく、成果にちなんだ名前をつける
空または放棄されたworktreeはすぐに削除する
アクティブな思考の流れごとに1つのworktreeを使う
ブランチのプレフィックスを一貫させてクリーンアップを明確にする
他のブランチと同様に、worktree間のマージ前にdiffをレビューする

Worktreeが煩雑に感じ始めたとすれば、たいていそれは多すぎるからではない。どれが使い捨てでどれが重要なのか、誰にも分からないからだ。

クリーンアップとハウスキーピング

Worktreeのクリーンアップ方法は、その中で実際に何かが変更されたかどうかによって異なる:

変更なし: セッション終了時にworktreeとそのブランチが自動的に削除される
変更あり: Claudeがworktreeを保持するか削除するかを確認する

Worktreeフォルダをバージョン管理から除外するには.gitignoreに1行追加する:

echo ".claude/worktrees/" >> .gitignore

Worktreeが積み重なってきたら、通常のgitコマンドでリストアップと剪定ができる:

git worktree list
git worktree prune

Worktreeを使うタイミング

シナリオ	Worktreeを使う？	理由
単一ファイルのクイックフィックス	いいえ	オーバーヘッドに見合わない
バグを直しながらフィーチャー作業	はい	フィーチャーとバグフィックスのブランチをクリーンに保つ
マルチエージェントの並行実行	はい	エージェント間のファイル衝突を防ぐ
多くのファイルのコードマイグレーション	はい	分離されたエージェントで作業を分割する
実験的なアプローチの探索	はい	自動クリーンアップ付きの使い捨てworktree
単一の集中したセッション	いいえ	通常のチェックアウトで十分

経験則として: 衝突を避けるために別のブランチを選ぶときは、代わりにworktreeを選ぼう。ブランチと、それに付随する別の作業ディレクトリの両方が手に入る。

覚えておこう: Worktreesは Claude Codeを1つのスレッドから並行開発環境に変える。分離されたセッションを起動する。分離されたエージェントをディスパッチする。準備ができたら勝者をマージする。