Claude Codeのworktree機能で並列エージェント開発を実現する完全ガイド【2026年2月新機能】
Claude Codeで複数タスクを同時に進めたいのに、ファイル競合で断念した経験はないだろうか。2026年2月、Claude Code v2.1.49で正式導入されたworktree機能がこの問題を根本解決した。claude --worktreeの一発で、各エージェントが独立したコードベースのコピーを持ち、互いに干渉せず並列作業できる。本記事では、CLIフラグの基本からサブエージェントのisolation設定、実際の並列開発ワークフローまで、具体的なコマンドとともに解説する。
なぜworktreeが必要なのか — 従来の並列作業の限界
ファイル競合問題：同一ファイルを複数エージェントが編集するとどうなるか
Claude Codeで複数のサブエージェントに作業を分担させると、同一ファイルへの同時編集が発生する。エージェントAがsrc/api/auth.tsをリファクタリング中に、エージェントBが同じファイルのimport文を変更する——結果は上書きか競合だ。これが従来の並列作業における最大のボトルネックだった。
git worktreeとは何か（30秒で理解する前提知識）
git worktreeは、同一リポジトリの別ブランチを別ディレクトリにチェックアウトするgitの標準機能だ。リポジトリの履歴やリモート接続は共有しつつ、作業ディレクトリとブランチは完全に独立する。つまり、ひとつのリポジトリに対して複数の作業場所を持てる。
Claude Code v2.1.49（2026年2月リリース）で、このgit worktreeのネイティブサポートが追加された。Boris Cherny氏がThreadsで発表し、「各エージェントが独自のworktreeを持ち、互いに干渉せず独立して作業できる」と説明している。
--worktreeフラグの基本操作
名前付きworktreeの作成と自動命名
使い方は至ってシンプルだ。--worktree（短縮形-w）フラグに名前を渡すだけでworktreeセッションが始まる。
# "feature-auth"という名前でworktreeセッションを開始
claude --worktree feature-auth
# 別ターミナルで、別のworktreeセッションを同時に起動
claude --worktree bugfix-123
名前を省略するとランダムな名前（例：bright-running-fox）が自動生成される。
# 名前を省略 → 自動命名
claude -w
ディレクトリ構造とブランチ命名規則
worktreeは以下の場所に作成される。
<リポジトリルート>/
└── .claude/
└── worktrees/
├── feature-auth/ ← 独立した作業ディレクトリ
└── bugfix-123/ ← 別の独立した作業ディレクトリ
ブランチ名はworktree-<name>の命名規則で、デフォルトリモートブランチから分岐する。例えばclaude --worktree feature-authなら、worktree-feature-authブランチが作成される。
.gitignoreに.claude/worktrees/を追加しておくと、worktreeの中身がメインリポジトリの未追跡ファイルとして表示されるのを防げる。
# .gitignore に追加
.claude/worktrees/
サブエージェントのworktree isolation — 並列の本命
CLIフラグでの手動起動も便利だが、並列開発の真価はサブエージェントのisolation設定にある。
カスタムエージェントのYAMLフロントマターでisolation: worktreeを宣言
.claude/agents/にカスタムエージェントを定義し、YAMLフロントマターにisolation: worktreeを追加するだけで、エージェント起動ごとに自動で専用worktreeが作成される。
---
name: refactor-agent
description: 大規模リファクタリングを担当するエージェント
isolation: worktree
tools:
- Read
- Edit
- Write
- Bash
- Glob
- Grep
---
あなたはリファクタリング専門のエージェントです。
指示されたファイル群を対象に、既存の動作を維持しつつモダンなパターンに書き換えてください。
このエージェントが作業を終えると、変更がない場合はworktreeが自動削除される。変更がある場合はworktreeとブランチが保持され、後からレビューやマージが可能だ。
CLIからのアドホック指定
カスタムエージェントを定義せずとも、Task toolのisolationパラメータで都度指定もできる。Claude Codeのプロンプト内で「worktreeを使ってエージェントを実行して」と指示するか、プログラム的にTask toolのisolation: "worktree"を指定すれば、その場でworktree分離が適用される。
実践ワークフロー：3つのユースケース
ユースケース1：大規模リファクタリングのバッチ並列処理
50ファイルのAPI移行を手作業で順次処理していては日が暮れる。worktreeを使えば、複数エージェントに分担させて並列処理できる。
# ターミナル1：認証関連ファイルの移行
claude --worktree migrate-auth -p "src/api/auth/配下の10ファイルをREST→tRPCに移行して"
# ターミナル2：ユーザー関連ファイルの移行
claude --worktree migrate-users -p "src/api/users/配下の10ファイルをREST→tRPCに移行して"
# ターミナル3：商品関連ファイルの移行
claude --worktree migrate-products -p "src/api/products/配下の10ファイルをREST→tRPCに移行して"
各worktreeは独立しているため、同時に実行してもファイル競合は起きない。完了後は各ブランチをレビューしてマージする。
ユースケース2：A/Bアプローチ比較で最適解を選ぶ
設計判断に迷ったら、両方作って比較すればいい。
# JWT方式で認証を実装
claude --worktree auth-jwt -p "JWT方式でユーザー認証を実装して"
# セッション方式で認証を実装
claude --worktree auth-session -p "セッション方式でユーザー認証を実装して"
両方の実装が完了したら、diffで比較して採用を決める。
# 両ブランチの差分を確認
git diff worktree-auth-jwt..worktree-auth-session -- src/
ユースケース3：--tmuxと組み合わせたバックグラウンド並列開発
--tmuxフラグを追加すれば、各セッションがtmuxのバックグラウンドセッションとして起動する。ターミナルを占有しない。
# 3つのタスクをバックグラウンドで同時起動
claude --worktree feature-auth --tmux -p "OAuth2認証を実装して"
claude --worktree feature-search --tmux -p "全文検索機能を追加して"
claude --worktree fix-perf --tmux -p "ダッシュボードのN+1クエリを修正して"
# セッション一覧を確認
tmux list-sessions
クリーンアップとハマりポイント
自動クリーンアップの挙動を正しく理解する
worktreeセッション終了時の挙動は明確にルール化されている。
- 変更なし → worktreeとブランチが自動削除される
- 変更あり → Keep（保持）かRemove（削除）かの確認プロンプトが表示される
手動でクリーンアップする場合は、通常のgitコマンドを使う。
# 現在のworktree一覧を確認
git worktree list
# 特定のworktreeを削除
git worktree remove .claude/worktrees/feature-auth
# 不要なworktree参照を一括整理
git worktree prune
よくあるトラブルと対処法
worktreeごとにnpm installが必要。 worktree間でnode_modulesは共有されない。新しいworktreeを作成したら、そのディレクトリ内でnpm install（またはyarn、pip install等）を実行する必要がある。これはgit worktreeの仕様であり、Claude Code固有の制限ではない。
サブエージェントのネストは不可。 worktree内で動作しているエージェントが、さらにworktreeを使うサブエージェントを起動することはできない。並列化は1階層までと覚えておこう。
WorktreeCreate/WorktreeRemoveフックでgit以外にも対応可能。 SVNやPerforceなどgit以外のVCSを使っている場合、v2.1.50で追加されたフックイベントを設定すれば、--worktreeフラグの挙動をカスタムのワークフロー分離ロジックに置き換えられる。
まとめ
Claude Codeのworktree機能は、AIエージェントによる並列開発のボトルネックだったファイル競合を根本解決する。--worktreeフラグひとつで独立環境を作れるシンプルさと、サブエージェントのisolation: worktree設定による自動化の柔軟さを兼ね備えている。大規模リファクタリングやA/Bアプローチ比較など、従来は順次処理せざるを得なかった作業を並列化できるインパクトは大きい。まずはclaude --worktreeを一度試して、並列開発の生産性を体感してほしい。
Sources: