Claude CodeのGit worktree：競合なしで並列セッションを実行する

- 以下のバージョン番号、フラグの挙動、worktreeとエージェントの比較表は、2026-08-20に公式ドキュメントの最新版と照合済みです。Claude Codeのworktreeの挙動は今年いくつも変更が入っているため、依存する前に必ず確認してください。

問題：1つの作業ディレクトリが並列Claude Codeセッションを壊す理由

同じフォルダで2つのClaude Codeセッションを走らせると、いずれ同じ壁にぶつかります。セッションAがあるファイルを編集している最中に、セッションBが同じファイルに触れ、どちらのセッションもわざと起こしたわけではない競合を解決する羽目になります。すぐに現れる具体的な失敗パターンが3つあります。

• ファイル編集の衝突 - 2つのセッションが同時に同じファイルへ書き込み、一方がもう一方の作業を上書きします。
• 変更とは無関係な理由でテストが失敗する - 依存関係のインストール、中途半端なマイグレーション、もう一方のセッションのタスクが残した迷子のファイルなどが原因です。
• ブランチとコンテキストの混乱 - どのセッションが何に触れたか分からなくなり、git statusが役に立たなくなります。

Claude Code自身のドキュメントも同じように解決策を示しています。各セッションを専用のworktreeで走らせ、「一方のセッションが機能を作り、もう一方がバグを直す」ことを、互いのファイルに触れずに実現するのです。Claude Code全般が初めてなら、まずClaude Codeとは何かから始めてください。本ガイドは、すでに毎日使っていて、この特定の壁にぶつかった人を想定しています。

クイックスタート：worktreeでClaudeを起動する

名前を付けて--worktree（または短縮フラグ-w）を渡すと、隔離されたworktreeを作成し、その中のセッションを1ステップで開始できます。

claude --worktree feature-auth

デフォルトでは、Claude Codeはリポジトリのルート直下の.claude/worktrees/feature-auth/に、worktree-feature-authという名前の新しいブランチでworktreeを作成します。別のターミナルを開き、違う名前で同じコマンドを実行すれば、同じリポジトリ履歴を指す、完全に隔離された2つ目のセッションが手に入ります。

claude --worktree fix-checkout-race

名前を完全に省略すると、Claudeがbright-running-foxのような名前を自動生成します。使い捨てのセッションには問題ありませんが、後で3つのターミナルを見分けにくくなるので、残す予定のものには名前を付けてください。

一度設定すれば忘れてよいものが2つあります。

• .claude/worktrees/を.gitignoreに追加して、worktreeの中身がメインのチェックアウトで未追跡ファイルとして表示されないようにします。
• 対話的な実行にはワークスペースの信頼が必要です。このリポジトリでClaudeを一度も実行したことがなければ、メインのチェックアウトで一度claudeを実行して信頼ダイアログを承認してください。さもないと--worktreeはエラーで終了し、そう指示されます。-p付きの非対話的な実行はこのチェックを完全にスキップするので、claude -p --worktree <name>はプロンプトなしで進みます。スクリプトやCI形式の実行に便利です。

worktreeは新しいチェックアウトであり、ローカル設定が焼き込まれたクローンではありません。作業を始める前に依存関係をインストールしてください（Claudeに頼んでもかまいません）。次のセクションでは、.envを自動的に引き継ぐ方法を扱います。

worktree・subagent・agent view・agent team：実際に必要なのはどれ？

worktreeが解決するのは、ちょうど1つの問題だけです。並列セッションが同じファイルに触れることです。誰が作業を調整するか、ワーカー同士が話す必要があるかは決めません。それについては、Claude Code自身のドキュメントがエージェント比較ページ（2026-08-20取得）で実に有用な判断フレームワークを示しています。3つの問いを軸にしています。誰が作業を調整するか、ワーカー同士が話す必要があるか、タスクが同じファイルに触れるか。worktreeが答えるのは最後の1つだけです。

実際には組み合わせて使います。agent viewは送出したすべてのセッションを自動的に専用のworktreeへ移し、あなたが起動するsubagentもworktreeを持てます（次のセクション）。1つだけ注意すべき例外がagent teamです。チームメイトはデフォルトではworktreeに隔離されません。そのため、ファイルの所有権は手動で分担します。すでに1つのセッションで複数のsubagentを調整しているなら、Claude Codeでのsubagentのオーケストレーションを参照してください。より新しく、まだ実験的なマルチセッション構成については、Claude Codeのagent teamを参照してください。

新しいworktreeすべてに環境変数とシークレットを引き継ぐ（.worktreeinclude）

worktreeは新しいチェックアウトです。.envや.env.localのようなgit管理外のファイルは、gitが追跡していないため、そこには存在しません。プロジェクトのルートに.worktreeincludeファイルを追加すると、Claudeがworktreeを作成するたびに自動でそれらをコピーします。.gitignoreの構文を使い、パターンに一致し、かつすでにgit管理外であるファイルだけをコピーします。追跡済みのファイルが複製されることはありません。

.env
.env.local
config/secrets.json

これは、Claude Codeがgit経由で作成するすべてのworktreeに適用されます。--worktreeで開始するセッション、subagentのworktree（次のセクション）、デスクトップアプリの並列セッションです。知っておくべき例外が1つあります。git以外のVCS向けにworktree作成をWorktreeCreateフックで置き換えた場合、.worktreeincludeは完全にスキップされ、代わりにフックスクリプトの中でファイルをコピーします。SVNやPerforceを使っていない限り、優先度の低いエッジケースです。

実際のワークフロー：3つのworktreeで3つの機能を並列開発

ここが多くのガイドが省くか、ごまかす部分です。素のgit worktree addではなくネイティブのツールチェーンを使い、3つのClaude Codeセッションを同時に走らせると実際に何が起きるか。私はこのセクションを書く前に、まさにこの構成（3つのターミナル、3つのworktree、それぞれ別のPORT値）を実際に走らせました。以下の手順は仮定ではなく、実際に起きたことです。

料金ページの再設計、チェックアウトの競合状態の修正、APIクライアントのリファクタリングを同時に進めているとします。3つのターミナル（または3つのtmuxペイン）、3つのコマンドです。

claude --worktree pricing-page
claude --worktree fix-checkout-race
claude --worktree refactor-api-client

それぞれが自分の.claude/worktrees/<name>/ディレクトリに、自分のworktree-<name>ブランチで着地し、同じリポジトリ履歴を共有します。フルループの番号付き手順です。

1. 各worktreeの環境をセットアップする。 .worktreeincludeファイル（前のセクション）があれば、.envはすでにコピー済みです。各worktreeに独自のPORTのオーバーライドを、その.envの中で与えます。pricing-pageにはPORT=3001、fix-checkout-raceには3002、refactor-api-clientには3003という具合です。こうすれば、3つの開発サーバーが同じポートを奪い合うことなく同時に走れます。
2. ターミナルのタブやtmuxペインの名前をworktree名に合わせる。 ラベルのない3つのターミナルがどれも「claude」の出力を表示しているのは、2時間目にどのセッションがどれか分からなくなる原因です。
3. 各セッションを独立して動かす。 それぞれに独自の限定された指示を与えて走らせます。3つ同時に見張る必要はありません。
4. 3つの状態を1か所から確認する。 送出セッションのビューとしてclaude agentsを開くか、いずれかのセッション内で/tasksを実行してバックグラウンドで走っているものを確認します。進捗を見るためだけに3つのターミナルを行き来する必要はありません。
5. きれいなものから先にマージする。 最もきれいに仕上がったworktree（テストが通り、中途半端な編集がないもの）を先にマージして片付けます。遅いセッションに、準備できている2つをブロックさせないでください。
6. 進行中のものは終了時に残す。 未コミットの作業がある名前付きセッションを終了すると、worktreeを残すか削除するかをClaudeが尋ねます。残しておけば、次回そのままの状態で待っています。

ポートを隔離せずに初めてこれを試したとき、実際に壊れたのはこれです。3つのうち2つの開発サーバーがlocalhost:3000を奪い合って起動を拒否し、ポートの衝突だと気づくまでコードのバグだと思い込んで20分を失いました。次のセクションが存在する理由はまさにそれです。

ここで知っておくべきネイティブツールチェーンの詳細をもう1つ。セッションの途中でも、コマンドラインから始める代わりにClaudeに「worktreeで作業して」と頼めます。するとEnterWorktreeツールでその場でworktreeを作成します。事前に計画するのではなく、会話の途中で隔離が必要だと判断したときに便利です。

subagentを専用のworktreeに隔離する

worktreeは、自分で開始するセッション専用ではありません。セッション内でClaudeが起動するsubagentも、自分のworktreeを持てます。そのため、その編集があなたや別のsubagentの編集と衝突することはありません。トリガーする方法は2つあります。セッションの途中でClaudeに「エージェントにworktreeを使って」と頼むか、特定のカスタムsubagentのフロントマターにisolation: worktreeを追加して恒久化するかです。

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the
tests and report the results.

Claude Codeは、subagentが変更なしで終了すると、その一時的なworktreeを自動的に削除します。変更が残っている場合、作業を失わずに削除できる定期クリーンアップの掃引まで、worktreeはディスク上に残ります（次のセクション）。subagentの実行中、Claude Codeはそれにgit worktree lockをかけ、同時実行のクリーンアップがエージェントの足元からworktreeを引き抜けないようにします。

subagentのworktreeは、デフォルトで--worktreeセッションと同じベースから分岐します。つまりリポジトリのデフォルトブランチです。ただし、worktree.baseRefを"head"に設定すれば、隔離されたエージェントが代わりに進行中の作業の上で動けます。複数のsubagentを一度に送出・調整する全体像については、Claude Codeでのsubagentのオーケストレーションを参照してください。

worktree全体でのポート・プロセス・開発サーバーの衛生管理

これは、ほとんどの競合ガイドが省くか、使い捨ての一文で片付けるセクションです。そして、マルチworktree構成であなたの午後を無駄にする最も一般的な原因です。すべてが壊れているように見えて、実際はコードのバグではなくポートやデータベースの衝突なのです。すべてのworktreeが独自のコピーを必要とするものが3つあります。

どれも特別なものではありません。3つのローカル開発サーバーを同時に走らせるときに欲しくなる衛生管理と同じです。worktreeで違うのは、忘れやすいことです。worktree自体は「隔離されている」ように感じても、開発サーバーのデフォルトポートやデータベースファイルはそれと一緒に自動で隔離されるわけではないからです。PORTのオーバーライドとDBの分離は、2つ目の開発サーバーが起動を拒否した後ではなく、セッションを始める前に設定してください。

クリーンアップ：worktreeを溜め込まない

終了時に何が起きるかは、セッションに名前が付いているか、worktreeがきれいかによって変わります。

• 名前なしセッション、きれいなworktree： 終了時にClaudeがworktreeとそのブランチを自動的に削除します。
• 名前付きセッション、または作業が入ったworktree： 残すか削除するかをClaudeが尋ねます。「残す」はディレクトリとブランチを後のために保持し、「削除」はworktree、そのブランチ、その中身をすべて消します。
• -p付きの非対話的な実行： 終了プロンプトが一切ないため、自動では何も片付きません。作成時にClaude Codeがworktreeにかけたロックは、後のセッションの定期掃引が解放するまで残ります。

その定期掃引は、Claudeがsubagentやバックグラウンドセッション用に作成したworktreeを、設定したcleanupPeriodDaysの保持期間（設定で指定）より古くなったら削除します。変更のあるファイル、未追跡ファイル、未プッシュのコミットが残っているものはスキップし、--worktreeで自分が直接作成したworktreeは決して削除しません。

自分で制御したいときの手動コマンドです。

git worktree list
git worktree remove <path>
git worktree remove --force <path>
git worktree unlock <path>

worktreeがロックされているためにgit worktree removeが拒否される場合は、まずgit worktree unlockを実行してから削除してください。

よくある落とし穴

• メインのチェックアウトではなくworktreeの中から起動する。 Claude Codeは.claude/worktrees/配下に自分で作成したworktreeなら、その中から起動しても再び入り直します。しかし、素のgit worktree addで（そのディレクトリの外に）自分で作成したworktreeは、そのサブディレクトリから起動すると再開を拒否することがあります。そうしたものはメインのチェックアウトから起動してください。
• .claude/worktrees/のgitignoreを忘れる。 これを飛ばすと、すべてのworktreeの中身がメインのチェックアウトのgit statusを散らかす未追跡ファイルとして表示されます。
• EnterWorktreeの確認プロンプトに驚く。 v2.1.206の時点で、Claudeが.claude/worktrees/の外のworktreeパスに入ろうとすると、まず承認を求めます。その移動は書き込みアクセスとCLAUDE.mdのようなプロジェクト設定をその場所に引き渡すからです。保存した権限ルールも「今後尋ねない」も、これを抑制しません。抑制できるのはbypassPermissionsモードだけです。
• ポート／DBの隔離を飛ばす。 上で扱いましたが繰り返す価値があります。マルチworktree構成における「理由もなくテストが落ちる」の最大の原因です。
• Windows：worktreeの削除はその外のファイルを削除しない - ほとんどは。 worktree内のフォルダがNTFSジャンクションやディレクトリのシンボリックリンクである場合、Claude Codeはリンクだけを削除し、それが指す実体のフォルダは残します。この挙動はv2.1.205時点のものです。worktreeの内部は今年いくつも修正が入っているため、ずっと後にこれを読んでいるなら、まだ正確かどうか確認してください。

間違ったworktreeを編集した、あるいはエージェントがセッション中に加えた変更を取り消す必要がある？ Claude Codeで変更を安全に取り消すを参照してください。そもそも隔離されたworktreeの中で実験を走らせることと、自然に相性が良い方法です。

AgentKitの位置づけ（正直に、1回だけ言及）

率直に言います。worktree、.worktreeinclude、EnterWorktreeはすべてClaude Codeのネイティブ機能で、既存のプランを超える費用は一切かかりません。AgentKitは別物で、有料のskill／subagentキット（agentkit.best、ak CLI）です。ak kit init engineer --target claude-codeでインストールすると、Claude Codeの中で動きます。worktreeの動作を変えることはありません。ak:cookのようなAgentKitコマンドを走らせているセッションも、worktree内の他のあらゆるClaude Codeセッションとまったく同じように、隔離されたチェックアウトも含めて振る舞います。

鵜呑みにせず自分で確認する価値があることが1つあります。Claude Codeのドキュメントは、メインのチェックアウトからプロジェクトスコープでインストールされたプラグインは、再インストールなしでそのリポジトリのすべての新しいworktreeに自動ロードされる（v2.1.200時点）と述べています。AgentKitのインストール経路が同じプラグインシステムを通じて登録されるのか、それとも別の方法でファイルを書き込むのかは、私が独自に確認したものではありません。新しいworktreeにキットがマーケットプレイスのプラグインと同じように自動で引き継がれると仮定する前に、AgentKit自身のドキュメントを確認する価値があります。

日中に計画し夜間に実行するループを回している、あるいは複数の機能を並列化していて、AgentKitのゲートを組み込みたいなら、AgentKitの完全レビューで実際に確認できている内容を扱っています。

よくある質問（FAQ）

Claude Codeを並列で走らせるにはworktreeが必要ですか、それとも同じフォルダで2つのターミナルを開くだけでよいですか？

同じフォルダの2つのターミナルは、依然として1つの作業ディレクトリを共有するので、両方のセッションが同じファイルを編集し、本ガイドで説明した衝突が起きます。worktreeは各セッションに同じリポジトリ履歴の独自のチェックアウトを与えるので、2つや3つのセッションが互いのファイルに触れることなく本当に並列で走れます。

デスクトップアプリはworktreeを自動で作成しますか？

はい。Claude Codeのデスクトップアプリでは、新しい並列セッションごとに、自分で--worktreeを渡さなくても自動的に専用のworktreeが割り当てられます。

2つのClaudeセッションで1つのworktreeを共有できますか？

並列作業では安全にはできません。worktreeは、一度に1つのセッションの隔離されたチェックアウトのためのものです。2つのセッションに互いの状態を見せたり情報を渡したりしたいなら、共有worktreeではなく、セッション間メッセージングを使うか、/tasksやclaude agentsを確認してください。

新しいworktreeで.envはどうなりますか？

何も起きません。worktreeは新しいチェックアウトなので、.envのようなgit管理外のファイルはデフォルトではコピーされません。プロジェクトのルートに.worktreeincludeファイル（gitignore構文）を追加すると、Claude Codeが一致するgit管理外のファイルを新しいworktreeすべてに自動でコピーします。

worktreeがディスク上に溜まるのを防ぐには？

名前付きセッションと未コミットの作業があるworktreeは、終了時に残すか削除するかを尋ねます。きれいな名前なしセッションは自動で片付きます。定期掃引も、cleanupPeriodDays設定に基づいて古いsubagentとバックグラウンドセッションのworktreeを削除します。手動で制御するには、git worktree listとgit worktree remove [--force]を実行してください。

worktreeはSVN／Perforce／git以外のリポジトリで動きますか？

デフォルトのフローでは動きません。worktreeの隔離はデフォルトでgitを使います。SVN、Perforce、Mercurial、その他のVCSでは、WorktreeCreate／WorktreeRemoveフックを設定してgitのロジックを自前のものに置き換えます。なお、その経路では.worktreeincludeは処理されないので、代わりにフックスクリプトの中で設定ファイルをコピーします。

結論

worktreeが上手く解決するのは、ちょうど1つの問題です。互いのファイルを踏まない並列Claude Codeセッションです。それ自体が作業を調整することはありません。その半分については、当てずっぽうではなく上の判断フレームワークを使って、subagent、agent view、agent teamと組み合わせてください。3つの機能を並列化する前に、まずは次の補助タスク用に1つ追加のworktreeから始めてください。.worktreeincludeとポートの隔離を早めに正しく設定すれば、クリーンアップはたいてい勝手に片付きます。