Claude Code サブエージェント × Worktree Isolation 設計ガイド — 並列実行でコンフリクトを防ぐ実装パターン
Claude Codeのカスタムサブエージェントにisolation: worktreeを設定して並列ファイル編集を安全に実行する方法を解説。フロントマター設計、.worktreeinclude設定、自動クリーンアップの仕組みまで。
エンジニアのゆとです。
Claude Code で複数のサブエージェントを並列実行した時に一番困るのが、ファイルの書き込み競合だ。
2つのサブエージェントが同じファイルを同時に編集しようとすると、どちらかの変更が上書きされる。「3つのサブエージェントで並列処理しよう」と思い立って試してみたら、半分の変更が消えていた——という経験がある人は少なくないと思う。
この問題の解決策が isolation: worktree という設定だ。カスタムサブエージェントのフロントマターに1行書くだけで、そのサブエージェントが起動するたびに独立した git worktree が自動生成される。並列実行してもファイルが衝突しない。
公式ドキュメントと実際の動作から、設計の全体像を整理した。
なぜ並列サブエージェントでコンフリクトが起きるか
1セッション = 1コンテキスト = 1ファイルシステム
通常の Claude Code セッションは1つのファイルシステムの上で動く。複数のサブエージェントを生成しても、全員が同じ作業ディレクトリを見ている。
これは以下のようなシナリオで問題になる。
- サブエージェントA が
src/auth/middleware.tsを編集中 - 同時にサブエージェントB も
src/auth/middleware.tsを参照・編集しようとする - どちらかの書き込みが先に完了して、後からの書き込みが上書きする
単一ファイルへの並列書き込みは、シングルスレッドのプログラミングでスレッドセーフを意識しないのと同じ危険さがある。
git worktree による解決
git worktree は、同一リポジトリから複数の作業ディレクトリを生成する git の仕組みだ。それぞれが独自のブランチとファイルセットを持ち、リポジトリの履歴だけを共有する。
サブエージェントに isolation: worktree を設定すると、起動のたびに .claude/worktrees/<自動生成名>/ 配下に独立した worktree が作られる。各サブエージェントは自分専用のファイルシステムを持って作業するので、コンフリクトが物理的に起きない。
isolation: worktree の設定方法
カスタムサブエージェントのフロントマター
カスタムサブエージェントは .claude/agents/<エージェント名>.md に定義する。ここに isolation: worktree を追加するだけだ。
---
name: code-reviewer
description: コードレビュー専門エージェント。セキュリティ・パフォーマンス・型安全性の3観点からコードを精査して指摘リストを返す。
tools:
- Read
- Grep
- Glob
- Bash
model: claude-sonnet-4-6
isolation: worktree
---
## レビュー指針
以下の3観点でコードを確認する。
...model フィールドでサブエージェントに使うモデルを指定できる。重い処理が不要なレビュータスクなら Haiku にしてコストを抑える、実装系は Sonnet にするといった使い分けができる。
ユーザーレベルとプロジェクトレベルの使い分け
サブエージェント定義の置き場所は2種類ある。
~/.claude/agents/— ユーザーレベル（全プロジェクトで使える）.claude/agents/— プロジェクトレベル（そのリポジトリ専用）
「どのプロジェクトでも使いたいレビュアー」はユーザーレベル、「このプロジェクト固有のドメイン知識を持つエージェント」はプロジェクトレベルに置く。Agent Teams のメンバーとして再利用する時も同じ定義ファイルを参照できる。
.worktreeinclude で環境変数ファイルをコピーする
worktree が持たないもの
git worktree は git で管理されているファイルのみを持つ。.gitignore に書いてある .env や .env.local、config/secrets.json などは自動ではコピーされない。
結果として、環境変数を参照するコードを動かすサブエージェントが「変数が見つからない」エラーを出すことがある。
.worktreeinclude の使い方
プロジェクトルートに .worktreeinclude を置くと、そのファイルに書いたパターンにマッチする gitignore 済みファイルが worktree 作成時に自動コピーされる。構文は .gitignore と同じだ。
# .worktreeinclude
.env
.env.local
config/secrets.jsonこの設定は --worktree フラグ、サブエージェントの worktree、Desktop アプリの並列セッション、いずれの worktree 生成にも適用される。
注意点として、.worktreeinclude は git のカスタムワークツリー作成フック（WorktreeCreate hook）を使っている場合は処理されない。カスタムフック内でファイルのコピーを手動で書く必要がある。
自動クリーンアップの仕組み
サブエージェントが生成した worktree の扱い
サブエージェントが完了した後の worktree の扱いは、変更があるかどうかによって変わる。
変更なし・未追跡ファイルなし・新規コミットなし → worktree とブランチが自動削除される
変更あり・未追跡ファイルあり・新規コミットあり → cleanupPeriodDays 設定を超えた古い worktree が自動クリーンアップ（コミット済みなどの条件で）
手動で削除したい場合は、
git worktree remove .claude/worktrees/<名前>で削除できる。リスト確認は git worktree list で。
cleanupPeriodDays の設定
settings.json で自動クリーンアップの猶予期間を設定できる。
{
"cleanupPeriodDays": 7
}未変更の古い worktree は指定日数後に自動削除される。並列サブエージェントをよく使うプロジェクトでは、.claude/worktrees/ ディレクトリが肥大化しないようにこの設定を入れておくのがいい。
.gitignore に .claude/worktrees/ を追加しておくことも忘れずに。worktree の内容がメインブランチの git status に未追跡ファイルとして表示されるのを防げる。
実践的な設計パターン
パターン1: コードレビューの3観点並列化
一番シンプルな使い方は、同じコードに対して異なる観点のレビューを並列実行することだ。
PRをレビューして。セキュリティ、パフォーマンス、テストカバレッジの3つの観点でそれぞれ独立して評価してほしい。このプロンプトを受け取った Claude は、3つのサブエージェントに分割してレビューを並列実行する。各エージェントが isolation: worktree を持っていれば、同じファイルを並列で読んでもコンフリクトが起きない（読み取りは衝突しないが、書き込みがある場合の保護になる）。
パターン2: 大規模マイグレーションのファイル分割
100ファイルを対象に同一パターンの変更を適用する場合、ファイルを20個ずつに分割して5つのサブエージェントに割り当てる。
重要なのは「各エージェントが担当するファイルを重複なく分割する」こと。isolation: worktree があっても、設計として同じファイルを複数エージェントが担当すると競合が起きる。
---
name: migration-worker
description: ファイルパスのリストを受け取り、各ファイルに対してマイグレーションパターンを適用する。担当ファイルを独立して処理する。
isolation: worktree
---パターン3: Agent Teams のメンバーとして再利用
isolation: worktree を設定したサブエージェント定義は、Agent Teams のメンバー定義にも再利用できる。
code-reviewer サブエージェントを使って、認証モジュールの監査を担当するメンバーを追加して。Agent Teams 自体はメンバーを worktree で分離しないが、こうした形で worktree 分離のカスタムサブエージェントをメンバーとして機能させることができる。
既存の worktree 記事との違い
--worktree フラグを使った手動の並列セッション管理については、別の記事で詳しく書いた。
isolation: worktree はそれとは別のアプローチだ。
claude --worktree feature-a→ ユーザーが手動で並列セッションを立ち上げるisolation: worktreein subagent → Claude が自動でサブエージェント用 worktree を生成・管理する
手動の worktree は「ユーザーが複数の Claude セッションを並列で操作する」用途、サブエージェントの isolation は「Claude が自律的に並列処理を実行する」用途で使い分けるのが自然だ。
FAQ
Q. isolation: worktree と isolation: none の使い分けは？
isolation: none（または isolation 未指定）は worktree を作らずメインの作業ディレクトリで実行する。単一のサブエージェントしか起動しない場合や、並列実行のコストを避けたい場合はこれで十分。複数サブエージェントが同じファイルに書き込む可能性がある場合は isolation: worktree を使う。
Q. /batch コマンドと何が違いますか？
/batch はスキルとして提供されていて、大きな変更を5〜30のworktree分離サブエージェントに分割してPRを作成するもの。isolation: worktree は個々のカスタムサブエージェントに設定するプリミティブな機能。/batch は isolation: worktree を内部で使っているイメージ。
Q. base branch の挙動はどうなりますか？
デフォルトではリモートの origin/HEAD からworktreeが切られる。settings.json で worktree.baseRef: "head" にすると、現在のローカル HEAD（作業ブランチの最新コミット）から切られる。feature ブランチ上で作業中のサブエージェントには "head" 設定が必要。
Q. 生成された worktree のコミットをマージするには？
サブエージェントが worktree 内で作業してコミットした場合、git worktree list でパスを確認して、通常の git merge や git rebase でマージできる。ただしサブエージェントが変更を commit せずに作業した場合、git worktree remove すると変更が失われるので注意。
まとめ
カスタムサブエージェントへの isolation: worktree 追加は、並列実行でのファイル競合を防ぐ最もクリーンな方法だ。
設定は1行で済み、worktree の生成・クリーンアップは自動で管理される。.worktreeinclude で環境変数ファイルをコピーする設定を入れれば、本番に近い環境で並列処理が走る。
「サブエージェントを並列実行してみたら変更が消えた」という経験があるなら、まずここから試してみてほしい。
