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で死んだものを削除できる。

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

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

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

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

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

まとめ

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

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