Claude Code ワークツリー：衝突なしで並列セッションを走らせる
コマンド 1 つで、Claude Code の各セッションにリポジトリの完全なコピーを渡せます。claude --worktree、.claude/worktrees の構成、サブエージェントのワークツリー分離、終了時のクリーンアップ、そして手動 git worktree add がまだ勝る場面まで解説します。
要点まとめ
- claude --worktree（省略形 -w）を使うと、セッションは .claude/worktrees/<name> に作られたリポジトリの新鮮なコピー内で始まり、worktree-<name> というブランチがチェックアウトされます。
- 別のターミナルでさらにセッションを起動すれば並列作業ができます — 各セッションは自分のディレクトリだけを編集しながら、同じ Git 履歴とリモートを共有します。
- サブエージェントにもワークツリーが渡されます：自然言語で頼むか、.claude/agents/*.md のフロントマターに isolation: worktree と書いて常時化します。
- 終了時、変更のない名前なしワークツリーは自動削除、作業中のものは保持/削除を尋ねられます。結果のマージは worktree-<name> を普通に git merge するだけ。
Claude Code Worktrees in 7 Minutes
チャンネル: Developers Digest7:10
I'm using claude --worktree for everything now
チャンネル: Matt Pocock7:57
Worktrees — official documentation
公式ドキュメント: code.claude.com/docs
このページのすべてのフラグ、パス、クリーンアップ動作は公式の worktrees ドキュメントに対して検証しています。上の動画がビジュアルと事実のソースです — 終了時の保持/削除プロンプトと main への push の罠も含めて。
スクリーンショットは各制作者に帰属し、該当タイムスタンプへ深リンクしています。顔出しフレームは使用していません。
Claude Code ワークツリーを使う、ステップごとに
パート 1 — 初めての分離セッション
- 1
コミット 1 つ以上ある Git リポジトリを用意する
ワークツリーは既存の履歴から分岐するため、worktree 機能には本物の Git リポジトリが必要です。新規フォルダで git init を実行し、ファイルを作り（デモは touch index.html を実行するだけ）、コミットします。省略すると、Claude Code には分岐元がありません。
git init と touch index.html — claude --worktree が動く前に必要なのはコミット 1 個だけ。1:06 から視聴 - 2
ワークツリーとは何かを理解する
Git ワークツリーとは、リポジトリの履歴とリモートを共有しつつ、独自のブランチをチェックアウトした第 2 の作業ディレクトリです。ブランチ切り替えと違って何も stash されません：メインのチェックアウトも各ワークツリーも同時に使えるまま — まさに並列エージェントが求めるものです。
1 つのリポジトリに複数の作業フォルダ：../main、../feature1、../feature2 がそれぞれ別ブランチに同時に載っています。0:30 から視聴 - 3
--worktree を付けて Claude Code を起動する
リポジトリ内で claude --worktree（短縮形 claude -w）を実行します。Claude Code は .claude/worktrees/<name> を作り、名前を渡さなければ bright-tumbling-rabbit のような名前を生成し、セッションをそのコピーへ直送します。デスクトップアプリでは、セッション開始時にワークツリーのオプションを選びます。
ウェルカムバナーの作業ディレクトリはすでに .claude/worktrees の中 — 以降のすべてはコピー内で起きます。1:22 から視聴 - 4
2 つ目のタスク用にセッションをもう 1 つ開く
別のターミナルでもう一度 claude --worktree を実行します。名前を渡さなければ独立したワークツリーがもう 1 つ手に入り、同じ名前を 2 回渡せば同じものを再オープンします。各エージェントは自分のディレクトリしか見えないため、2 つのエージェントが同じプロジェクトを同時に編集できます。
パート 2 — ファイルとコマンドの行き先
- 5
.claude/worktrees 配下の完全コピーを確認する
フォルダをファイラーで開いてみてください：各ワークツリーは完全なチェックアウトで、専用の index.html、専用の .claude/settings.local.json、専用の git ファイルを持ち、重いオブジェクトデータベースはメインの .git に共有されたままです。だからコピーをもう 1 つ作るのはほぼ無料なのです。
ディスク上の 2 つのワークツリー — clever-munching-toast と spicy-napping-otter — どちらも専用の git フォルダと index.html を持つ完全なプロジェクトコピーです。1:50 から視聴 - 6
コマンドがワークツリー内にとどまることを確認する
最初のセッションがブラウザでページを開くと、権限プロンプトはパスが .claude/worktrees/clever-munching-toast を指していることを示します — メインのチェックアウトではありません。Claude Code はサブエージェントがメインのチェックアウトを直接編集するのもブロックし、この分離チェックの 1 つはオフにできません。
承認ダイアログにはワークツリーの正確なパスが示され、セッション 1 が触れるのは自分のプロジェクトコピーだけだと証明しています。1:42 から視聴 - 7
ワークツリーに名前を付ける／PR から分岐する（任意）
claude --worktree feature-auth なら名前付きワークツリーが予測可能に作られ、同じ名前を再度実行すれば複製ではなく再オープンします。クォートした PR 番号（claude --worktree "#1234"）や GitHub/GitLab の PR URL を渡せば、そのプルリクエストのワークツリーが .claude/worktrees/pr-<number> に作られます。
パート 3 — 並列サブエージェントとクリーンアップ
- 8
ワークツリー分離付きの並列サブエージェントを頼む
分離はターミナルを超えてスケールします。「5 つの異なるサブエージェントを spawn して 5 つのバリエーションを作り、git worktree 分離を活用して」という 1 つのプロンプトで、Claude Code は Task エージェントをそれぞれ独立したワークツリーで起動し、衝突なく同じリポジトリに同時に取り組みます。
5 つの Task エージェントが並列に spawn — 各々が自分の分離 git worktree で作業すると告知されています。2:42 から視聴 - 9
各エージェントが自分のレーンで走るのを見る
タスクリストには 5 つのバリエーションすべてがツール使用とトークン数つきで並ぶため、ターミナルを 5 つ開かずとも進捗が見えます。サブエージェントのトランスクリプトはメインスレッドのコンテキストに載らないので、エージェントたちが重い持ち場を担う間も、指揮するセッションはコンパクトに保たれます。
走行中の 5 つのサブエージェント — Variation 1 はすでに 50.3k トークンで完了、他は各自のワークツリーでファイルを読んでいます。3:42 から視聴 - 10
バリエーションを比較し、勝者をマージする
エージェントが完了すると、Claude Code は各バリエーションとその .claude/worktrees/agent-<id>/ パスを一覧表示するので、ブラウザで並べて開けます。気に入ったものは、そのワークツリーブランチを普通に git merge する（または PR を出す）だけで出荷できます — 衝突があれば、他の Git マージと同じように解決します。
サマリーは各バリエーションと .claude/worktrees のパスを示し、レンダリング結果の 1 つがリストの隣に開いています。4:22 から視聴 - 11
分離を再利用可能なサブエージェントとして保存する
ワークツリー分離を常時化するには、お願いするだけです：「フロントエンド開発者のサブエージェントを作って、Haiku モデルを使い、ワークツリー分離を活用して」。Claude Code は自らのエージェントドキュメントを調べ、.claude/agents/ 配下に新しいファイルを書いてくれます。
自然言語で十分 — Claude Code はファイルを書く前に、カスタムエージェントの形式を自分のドキュメントで確認します。5:42 から視聴 - 12
isolation: worktree フロントマターを確認する
生成された frontend-dev.md には name、description、model: haiku、ツールのホワイトリスト、そして — 新しい行 — isolation: worktree が含まれます。以降、このサブエージェントの実行は毎回一時ワークツリーで行われ、変更なしで終われば自動削除されます。
フロントマター 8 行目の isolation: worktree — これがこのサブエージェントの全実行に専用ワークツリーを与えます。6:42 から視聴 - 13
マージしたら、クリーンアップは Claude に任せる
セッションを終了すると、Claude Code はワークツリーを点検します：クリーンな名前なしワークツリーは自動削除、作業のあるものは保持/削除を尋ねられ — 保持すれば後で使える claude --worktree <name> --resume コマンドを出力します。ヘッドレスの -p 実行は決してクリーンアップしないので、git worktree remove で削除してください。
Claude Code ワークツリー vs 手動 git worktree add
ワークツリー自体は何年も前から Git にあります — 新しいのは、Claude Code がそのライフサイクル全体を管理することです。効いてくる違いは：
- 1作成：手作業なら git worktree add ../project-feature -b feature を実行し、cd して、Claude を起動します。claude --worktree なら 1 ステップで .claude/worktrees/<name> 内にセッションが着地し、名前は自動でも自分でも付けられます。
- 2起点コミット：worktree.baseRef が開始点を制御 — fresh（デフォルト）はリモートのデフォルトブランチから、head は未 push のローカルコミットを引き継ぎます。特定ブランチを狙うフラグはなく、公式ドキュメントはその場合の手動 git worktree add を勧めています。
- 3ドットファイル：プロジェクトルートの .worktreeinclude ファイルが、.env など gitignore されたファイルを各新しいワークツリーにコピーします。手作りワークツリーにはこの扱いはありません。
- 4クリーンアップ：Claude Code は終了時にワークツリーを点検し、クリーンな名前なしものは自動削除、作業中のものは触る前に確認し、放置されたサブエージェントのワークツリーも定期的に掃除します。手動ワークツリーは完全に自己責任です。
- 5ガードレール：分離チェックがサブエージェントによるメインチェックアウトの編集を止め、セッション再開時はそのワークツリーに戻されます。素の git worktree add にこうした安全網はありません。
土台はあくまで普通の Git です。VS Code のソース管理パネルは各ワークツリーとその変更を一覧し、マージは普通の git マージ、手作りと Claude 作りのワークツリーは同じリポジトリに共存 — タスクごとに道具を選べばいいのです。
ワークツリーの調子がおかしいとき
落とし穴のほとんどは、機能のバグではなく Git の基本が顔を出したものです。この 5 つがほぼすべての角をカバーします：
- 1push が main に乗る。新鮮なワークツリーブランチは origin のデフォルトブランチを追跡するため、素の git push が main を狙えます。git push origin worktree-<name> と明示的に push し、main は保護しましょう。
- 2ファイルやツールがない。gitignore されたファイル（.env、vendor ディレクトリ）や LFS などリポジトリローカルのフィルタドライバは新しいワークツリーに伝播しません。.worktreeinclude に列挙するか、ワークツリー内で git lfs pull とセットアップコマンドを実行しましょう。
- 3起動が trust エラーで失敗する。信頼されていないディレクトリでは、claude --worktree はワークスペースの承認を促すエラーで終了します — 承認して再実行してください。（非対話の -p 実行はこのチェックをスキップします。）
- 4マージ時に 2 つのワークツリーが衝突する。両方のタスクが同じファイル（ルート、サイドバー、package.json）を編集したら、マージ時の衝突解消は他の Git ワークフローと同じです。ワークツリーが取り除くのは実行中の衝突であって、意図の重複ではありません。
- 5ヘッドレス実行後にワークツリーが残る。-p 実行は後片付けをしません。git worktree remove で手動削除してください（ロックされているなら先に git worktree unlock）。
セッションの足元からワークツリーを削除しても致命的ではありません：次の resume は起動ディレクトリにフォールバックし、紐付けが解消されるだけ。セッションの他の部分は壊れません。