この記事は playpark Blog からの転載です。
この記事で分かること
- 並列subagentが同一working directoryでgit操作をすると何が起きるか
- isolationか直列化か、判断基準
-
isolation: 'worktree'の実装例
背景: こういう課題があった
Claude CodeのAgent toolで複数のsubagentを並列起動すると、読み取り専用の調査タスクなら気持ちよく速くなる。ただしファイルを書き換えたりgit操作をしたりする場合は話が別で、同じworking directoryを共有させたまま走らせると、コミットの中身がどれも中途半端に混ざる、という壊れ方をする。
原因はgit操作の競合だ。並列起動したsubagentのうち2つが、isolationを指定せずに同じworking directoryへgit checkout -Bのようなブランチ切り替えやgit commitを投げると、それぞれのgit操作は同じ.gitディレクトリの同じHEADを取り合う。片方が切り替えたブランチのまま、もう片方がステージングしてcommitすると、「自分が書いたはずのないファイル」がコミットに混ざり込む。タイミングによっては再現したりしなかったりするので、原因に気づくまで時間を溶かしやすい。
選択肢の検討
| アプローチ | メリット | デメリット |
|---|---|---|
| そのまま並列実行(isolationなし) | 追加コストゼロ | 書き込み・git操作があると高確率でコミットが壊れる |
isolation: 'worktree' |
subagentごとに独立したHEAD・ステージングエリア、競合しない | worktreeごとに依存関係の再インストールが必要、セットアップ待ちが発生 |
| 直列実行 | セットアップコスト0、競合の心配がそもそもない | 並列化による速度メリットを手放す |
なぜこのアプローチを選んだか
判断基準は「並列で走らせるsubagentが、ファイルを書き換えるか・git操作をする可能性があるか」の1点に絞っている。読み取り専用の調査(コードリーディング、grep、設計把握)ならworking directoryの状態を変更しないので競合しようがなく、isolationは不要。逆にファイルの書き換えやgit操作を伴うなら、isolation: 'worktree'か直列化のどちらかが必須になる。
実装例
Agent({
description: "機能Aを実装",
prompt: "...",
isolation: "worktree"
})
これを並列で呼び出したsubagentそれぞれに指定すれば、各subagentは自分専用のworktreeでcheckout・commitを行い、他のsubagentのHEADと衝突しない。worktreeはgitの標準機能で、ブランチごとに独立した作業ディレクトリを持てるため、subagentごとに別々のHEAD・別々のステージングエリアが用意される。
ただしisolationにもコストがある。worktreeを新規に作ると、そのディレクトリには依存関係のインストール状態が引き継がれない。実際、自分たちのスキル開発チームでも、git worktree add直後のworktreeに依存パッケージが入っておらず、担当のsubagentがその場でインストールコマンドを実行して回避する、という状況が起きていた。だから読み取り専用タスクにまでisolationを付けるのは、得られる安全性に対してセットアップコストが見合わない。
もう一つ、本数が少ない・タスク同士に依存関係がある・同じファイルの近接箇所を触る、といった場面ではisolationより直列実行のほうが安全なことが多い。worktreeを分けて並列にしても、最終的にマージするときに同じ場所でコンフリクトするなら、最初から順番にやったほうが速い。
まとめ: どういう場面で使うべきか
読み取り専用の並列調査にはisolationは不要。ファイルの書き換えやgit操作を伴う並列作業にはisolation: 'worktree'か直列化のどちらかを必ず選ぶ。isolationが守ってくれるのは1つのworktree内の競合までで、複数のworkflow・複数のプロセスが同時にworktreeを作ろうとするタイミングの衝突までは面倒を見てくれないので、並列度そのものを絞る選択肢も合わせて持っておくとよい。
さらに深掘りしたい方へ
この記事では並列subagentのgit操作でisolationが必要な理由と実装を解説しました。
Claude Code の subagent を並列で git 操作させると、コミットが壊れることがある ではさらに：
- HEAD競合が実際に何を壊すかのsequence diagramでの図解
- 手元で再現して確認するための検証コマンド一式
- worktree衝突からの手動リカバリ事例と、isolationだけでは防げないケース
を扱っています。
playpark について
playpark LLC - 業務自動化・AI活用・Web開発
