git worktree: 複数のAIエージェントを衝突なしで動かすための土台

同じリポジトリで2つのエージェントを起動する。片方がpackage.jsonを編集し、もう片方も同じファイルを編集する。30秒後には、誰にもマージできない状態にコードが陥っている。

これはエージェントのバグではない。全員が同じフォルダで作業しているせいだ。

解決策は、Gitが何年も前から備えているのにほとんど誰も使っていないツール、git worktreeだ。

問題: 3つのエージェント、1つのリポジトリ、マージ不能

通常のGitリポジトリは、1つのフォルダで一度に1つのブランチをチェックアウトする。mainで作業し、ブランチを切り替えれば、フォルダ全体が丸ごと切り替わる。

そこに自律エージェントを3つ放り込んでみよう。3つは同時に書き込む。エージェントAがファイルを作成し、エージェントBがクリーンな状態から始めようとgit checkoutを実行して、Aの作業中の変更を消し飛ばす。結果として残るのは、書きかけのファイル、壊れたインデックス、そして自分でコードを書いていたほうが早かったと思えるほど解きほぐすのに時間がかかるコンフリクトだ。

並列化が時間を節約してくれるのは、エージェント同士が干渉しないときだけだ。

git worktreeとは何か

worktreeとは、同じリポジトリにひもづいた2つ目の作業フォルダのことだ。

履歴もリモートも共通だが、worktreeはそれぞれ独自のブランチをチェックアウトし、ディスク上に独自のファイルを持つ。5つを横並びにして、それぞれ別のブランチに置いても、互いの邪魔にならない。

1つの.gitに、複数のワークスペース。それだけだ。

実践：エージェント1つにつきworktree1つ

セットアップはこうだ。自分のリポジトリから:

git worktree add ../project-auth -b feature/auth
git worktree add ../project-billing -b feature/billing
git worktree add ../project-export -b feature/export

これで、それぞれが独自のブランチに置かれた3つのフォルダができた。各フォルダでエージェントを起動する:

cd ../project-auth && claude
cd ../project-billing && codex

エージェントごとに、自分のフォルダ、自分のブランチ、自分のファイルがある。authのエージェントが、billingのエージェントの作業を目にすることは決してない。衝突は起こりようがない。

機能が仕上がったら、そのブランチをレビューしてマージする。そのあと後片付けをする:

git worktree remove ../project-auth

フォルダは消えるが、ブランチは履歴に残る。すっきりだ。

知っておくべき3つの落とし穴

1つ目の落とし穴は、共有された中心的なファイルだ。2つの機能がどちらも同じroutes.tsや同じデータベーススキーマに手を入れなければならない場合、worktreeは助けにならない。マージのときにコンフリクトが出る。全員が共有するファイルに触れるのは1つのエージェントだけにして、ほかは待つか、迂回するしかない。

2つ目は、ブランチが乖離していくことだ。エージェントが作業している間にも、mainは進んでいく。3日後には、自分のブランチは遅れていて、マージが苦行になる。早めにこまめにリベースするか、セッションを短く保とう。

3つ目は、後片付けの忘れだ。worktreeはどれもディスク上の実在するフォルダだ。1日に10個作って片付けないでいると、親フォルダは手がつけられなくなる。git worktree listで何が残っているかが分かり、git worktree pruneで死んだものを削除できる。

4つ目の落とし穴: worktreeは空っぽで始まる

worktreeに入っているのは、Gitが追跡しているファイルだけだ。git worktree addで手に入るのはソースコードであって、node_modulesも、.venvも、ローカルのシークレットを入れた.envも、ビルドキャッシュも含まれない。新しいworktreeで起動したエージェントはテストを実行できず、開発サーバーも起動できず、しかもその理由を言わないことが多い。npm testはモジュールが見つからずに失敗し、アプリは環境変数がなくて落ち、エージェントは最初の10分をチケットではなく配管作業に費やす。

これには私たちもやられた。あるユーザーが指摘してくれたのは、AgentsRoomのworktreeオプションがエージェントフォームの詳細オプションの中に隠れていたこと、そしてworktreeで起動したエージェントには依存関係がひとつもなく、テストを1つも実行できなかったことだ。どちらも事実だった。分離の仕組みは存在していたが、誰も覚えていない手作業の手順を挟まなければ使いものにならなかった。

バージョン1.194.0から、このオプションはエージェントフォームの「分離」ブロックにあり、何も展開しなくても見える。そして新しいworktreeで最初に起動したエージェントは、準備済みのworktreeで作業を始められる。AgentsRoomは、パターンに一致する無視対象のファイルをメインのチェックアウトからコピーし（デフォルトではすべての.env*。上書きは決してせず、node_modulesや.gitの中にも決してコピーしない）、続いてロックファイルから検出したインストールコマンド（bun、pnpm、yarn、npm、uv、poetry、pipenv、bundle、composer）か、プロジェクト設定で指定したコマンドを実行する。コマンドはエージェント自身のターミナルで動くので目で確認でき、インストールが失敗してもエージェントの起動は止まらない。これはworktreeごとに1回だけ行われる。worktreeの非公開のgitフォルダに置かれたマーカーによって、次の起動ではこの手順が飛ばされる。

手作業でやる場合も手順は同じで、スクリプト1本に収まる。.env*をコピーし、インストールを実行し、それからエージェントを起動する。git worktree addをそのスクリプトで包んでおこう。そうしないと、3つ目のエージェントで忘れる。

本当の問題: 5つのフォルダを誰が見張るのか

worktreeはファイルの衝突を解決する。だが、頭の中の負荷は解決してくれない。

5つのフォルダ、5つのエージェント、5つのターミナルがある。どれが自分のレビュー待ちなのか。よそ見をしている間に10分前に終わったのはどれか。クラッシュしたのはどれか。

ここが、ターミナルにとどまる限り、エージェント1つにつきworktree1つという方式の限界だ。技術的な衝突は解決したものの、見張るべきウィンドウを増やしてしまったのだ。

AgentsRoomは、どのworktreeで動いていようと、各エージェントをタイルに、ステータスと色つきで並べる。待機中のエージェントは赤くなって通知してくれる。worktreeの上に積み重ねる完全な方法は、3〜8個のエージェントを見失わずに並列で動かす方法を読んでほしい。

まとめ

エージェント1つ、worktree1つ、ブランチ1つ。これが本格的なマルチエージェント作業の基本ルールだ。

コマンドは3行に収まり、効果はすぐに現れる。エージェントが互いを上書きしなくなる。そこに、どのエージェントが自分を必要としているかを教えてくれるビューを足せば、頭がパンクすることなく、5つの仕事を本当に並列で回せるようになる。