Claude Codeのworktreesで並列CLIセッションを安全に動かす：--worktreeとサブエージェント隔離

Claude Codeはgit worktreeを一級市民として扱い、並列セッションの編集が衝突しないように設計されています。本記事は、--worktreeフラグ、ベースブランチ設定、PR起点のworktree、サブエージェントのisolation: worktree、.worktreeinclude、自動クリーンアップの仕組み、Git以外のVCS向けのフックまで、運用に必要な観点を一通り整理します。

結論：「並列に進めたいが衝突は避けたい」のための既定の解

Claude Codeで並列に作業を回すなら、複数クローンを作るよりworktreesが公式の推奨です。理由は単純で、リポジトリ履歴を共有しつつワーキングディレクトリだけ分けられるからです。次の表が分かりやすい比較です。

サブエージェント並列実行（「複数のAIエージェントで調査を並列化する実践パターン」）や、複数機能を平行して進める実装（「Claude Codeで複数ファイルの変更を安全に進めるコツ」）と組み合わせると、衝突を起こさずに作業量を増やせます。

--worktreeの基本

最も簡単な使い方は、起動時にworktreeを作る方法です。

省略記法も使えます。

引数を省略すると、bright-running-foxのような自動命名のworktreeが作られます。

デフォルトのworktreeは.claude/worktrees/<value>/に作られ、ブランチ名はworktree-<value>になります。.gitignoreに.claude/worktrees/を追加しておくと、誤コミットを防げます。

なお、--worktreeを初めて使うディレクトリでは、事前にclaudeを引数なしで起動してワークスペース信頼ダイアログを承諾しておく必要があります。承諾していないと--worktreeはエラーで終了します。

ベースブランチの選択

worktreeは既定でorigin/HEAD（リポジトリのデフォルトブランチ）から分岐します。ローカルのHEADから分岐したい場合はsettings.jsonで切り替えます。

{
  "worktree": {
    "baseRef": "head"
  }
}

PR起点のworktreeも作れます。

これは.claude/worktrees/pr-1234にworktreeを作り、PRのブランチをチェックアウトします。レビュー時にPRを手元で動かしたいときに便利です。

.worktreeincludeで.envなどを持ち込む

worktreeは「フレッシュなチェックアウト」なので、.envのようなgitignore対象ファイルは存在しません。動作確認に必要なファイルを毎回コピーする手間を減らすため、リポジトリルートに.worktreeincludeを置けます。

.env
.env.local
config/secrets.json

ここに書いたパターンにかつ既に.gitignore対象であるファイルだけが自動コピーされます。トラックされているファイルが二重化されることはありません。秘密情報を扱う場合は、「Claude Codeに秘密情報を渡さないための実践ルール」の3層防御を踏まえてコピー範囲を絞ってください。

サブエージェントを別worktreeで動かす

並列サブエージェント運用で最も衝突が起きやすいのは「同じファイルを同時に書き換える」ケースです。これを物理的に防ぐ手段が、サブエージェントを別worktreeで動かす設定です。

会話レベルでは「サブエージェントはworktreeを使って」と指示するだけで効きます。フロントマターで明示するなら次のとおりです。

---
name: parallel-refactor
description: 同時並列でリファクタを進めるサブエージェント
isolation: worktree
---

サブエージェント終了時に変更がなければ、worktreeは自動で削除されます。複数サブエージェントを動かす場合は、それぞれが独立したworktreeで作業するため、ファイルレベルでは衝突しません。サブエージェント全体の仕組みは「Claude Codeのサブエージェントとは？使いどころと注意点」を参照してください。

なお、Desktopアプリは「新しい並列セッション」を作るたびにworktreeを自動で作る挙動です。手動で--worktreeを渡す必要はありません。

ライフサイクルとクリーンアップ

worktreeのライフサイクルは、Claude Codeが自動で管理します。

自動削除されるケース：

• セッション終了時に未コミット変更／untracked files／新規コミットがない
• セッション名付きでない（名前付きセッションはプロンプトする）

プロンプトされるケース：

• 未コミット変更／untracked files／新規コミットがある
• 「保持（ディレクトリとブランチを残す）」または「削除（すべて消す）」を選ぶ

非対話モード（-p）：

• 自動クリーンアップは行われない。git worktree removeで手動削除する

サブエージェントの孤立worktree：

• 起動時に、cleanupPeriodDays設定より古く、かつ未コミット変更／untracked files／unpushed commitsがないworktreeは自動削除される

つまり「クリーンに終わったworktreeは消える、何か残っていれば人間に判断を求める、-pは自動掃除しない」という3点が運用上のポイントです。

手動でのworktree管理

Claude Codeを通さない通常のgit操作でも、worktreeは同じように扱えます。

ディレクトリに移動してClaudeを起動するだけで、そのworktreeで作業できます。

一覧と削除はそれぞれ次のコマンドです。

worktreeを使うべきとき／使うべきでないとき

公式が整理している判断軸を踏まえて、目安を表にします。

並列実行と並列調査の使い分けは「複数のAIエージェントで調査を並列化する実践パターン」、リファクタを複数ファイルで進める手順は「Claude Codeで複数ファイルの変更を安全に進めるコツ」に整理してあります。

Git以外のVCSでの代替

SVNやPerforceなどgit worktreeが使えない環境では、Hooksで隔離ロジックを差し替えられます。WorktreeCreateとWorktreeRemoveフックを実装する形です。

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

カスタムフックを使う場合、.worktreeincludeは処理されない点に注意です。必要なファイルのコピーはフックスクリプト内で行う必要があります。Hooks全般の作法は「Claude CodeのHooksで開発ワークフローを自動化する方法」を参照してください。

PR運用との接続

worktreeはPR分割と相性がよい仕組みです。並列に進めても、最終的に1機能1PRに整理しやすくなります。

• 作業中：機能ごとに別worktree／別ブランチで進める
• コミット：1コミット1意図で、worktree内で小分けにする（「Claude Codeで安全にコミットとPRを作るワークフロー」の方針）
• PR：worktree単位でPRを作成。レビューも独立する
• マージ後：worktreeを削除（自動またはプロンプト）

PR運用の細部は「Claude Codeで安全にコミットとPRを作るワークフロー」、複数ファイル変更時の順序付けは「Claude Codeで複数ファイルの変更を安全に進めるコツ」が参考になります。

やってはいけないこと

worktree運用で事故りやすいパターンを挙げます。

1. .claude/worktrees/を.gitignoreに入れない：意図せずワーキングディレクトリをコミットしてしまう
2. .worktreeincludeに本番秘密を書く：worktreeを使う全員に同じ秘密がコピーされる前提で扱う
3. -p非対話モードで作ったworktreeを残し続ける：自動クリーンアップが効かないので、手動掃除を組み込む
4. 同じファイルを別worktreeで触ったのに最終マージを忘れる：worktree間でファイルが食い違ったままになる
5. 未コミット変更をプロンプト無視で削除する：消したworktreeの変更は戻せない（ローカルブランチへのバックアップなし）

5番目は特に注意で、worktreeの「削除」は中身も消えます。残したい変更があるなら必ず「保持」を選ぶ運用にしてください。

worktree運用チェックリスト

• .gitignoreに.claude/worktrees/を追加した
• 初回利用ディレクトリでワークスペース信頼ダイアログを承諾済み
• worktree.baseRefの既定がorigin/HEADでよいか、headにするかを決めた
• .worktreeincludeは本番秘密を含めず、必要最小限のファイルにとどめた
• サブエージェント並列実行のときはisolation: worktreeまたは会話での明示指示を入れた
• cleanupPeriodDays設定で孤立worktreeの寿命を決めた
• -p非対話モードで作ったworktreeの手動掃除フローを用意した
• PR単位で1 worktree、マージ後は削除という運用ルールを共有した
• Git以外のVCSではWorktreeCreate／WorktreeRemoveフックを実装した

次に読むおすすめ記事：

• 「Claude Codeのサブエージェントとは？使いどころと注意点」：worktreeで隔離するサブエージェントの仕組み
• 「Claude Codeで複数ファイルの変更を安全に進めるコツ」：worktreeを使った並列変更の安全な順序付け
• 「Claude Codeで安全にコミットとPRを作るワークフロー」：worktree単位でPRを切り分けるGit/PR運用