git worktree で複数のAIエージェントを衝突させない

複数のAIコーディングエージェントを1つのプロジェクトで走らせたときに最初に起きる問題は、エージェント自体ではありません。全員が同じ部屋に立っていることです。1体がブランチを切り替え、もう1体がファイルを書き、3体目が足元で変わったツリーに対してテストを流します。

git worktree はこれをきちんと解決します。しかも Git 2.5 から入っている標準機能です。

worktree とは何か

worktree は、同じリポジトリにぶら下がる追加の作業ディレクトリです。オブジェクトストアも履歴もリモートも共有したまま、ディレクトリ・チェックアウト中のブランチ・インデックスだけが別になります。

# メインのチェックアウトから
git worktree add ../myapp-auth feature/auth
git worktree add ../myapp-billing feature/billing

これでディスク上に3つのディレクトリができ、それぞれ別のブランチにいて、.git は1つを共有しています。1ディレクトリに1エージェントを割り当ててください。同じファイルにいないので、そもそも衝突できません。

clone を3回するのでは駄目なのか

clone でも動きますが、コストが高く、ずれやすくなります。

• ディスク — clone ごとにオブジェクトストアが丸ごと複製されます。worktree は共有します。
• 取得 — clone が3つなら最新化に git fetch が3回要ります。worktree なら1回 fetch すれば全 worktree が新しいオブジェクトを即座に見ます。
• ブランチの取り違え — clone は2つのディレクトリで同じブランチをチェックアウトして黙って分岐させることを許します。Git は1つのブランチを2つの worktree でチェックアウトすることを拒否します。エージェントが自分でブランチを選ぶ状況では、これがまさに欲しいガードレールです。

最後の点は見た目以上に効きます。「ログインの修正をやって」と言われたエージェントが、別のエージェントが既にいるブランチをチェックアウトすることは普通に起こります。clone だとマージのときに気づきます。worktree だと Git が入口で止めます。

実用的な設定

# 一度だけ: worktree を隣のディレクトリにまとめる
mkdir -p ~/work/myapp-trees
cd ~/work/myapp
git worktree add ~/work/myapp-trees/auth   -b feature/auth
git worktree add ~/work/myapp-trees/billing -b feature/billing

# 一覧と掃除
git worktree list
git worktree remove ~/work/myapp-trees/auth

-b を付けるとブランチの作成とチェックアウトを同時にやります。作業が終わってマージしたら git worktree remove で消してください。放置すると git worktree list が実体のないディレクトリで埋まります（git worktree prune で掃除できます）。

worktree でも解決しないこと

正直に書くと、worktree が解くのはファイルの衝突だけです。残る問題は3つあります。

1. 共有の外部状態 — 同じ開発用データベース、同じポート、同じ node_modules キャッシュを使っていれば、ディレクトリを分けても踏み合います。ポートは worktree ごとに変え、DBはスキーマかコンテナで分けてください。
2. 依存のインストール — worktree は .git は共有しますが node_modules は共有しません。ディレクトリごとにインストールが要ります（pnpm のようなストア共有型を使うと軽くなります）。
3. 人間側の把握 — ディレクトリが5つに増えると、「どのエージェントがどの worktree にいるか」が新しい迷子ポイントになります。

3番目は道具の領分です。私たちは各セッションのタイルに作業ディレクトリを表示して、視線1回で対応が付くようにしています（Agent Tile）。tmux のペイン名に worktree 名を入れても同じ効果が得られます。大事なのは道具ではなく、「ディレクトリとエージェントの対応を、記憶ではなく画面に置く」ことです。

まとめ

1リポジトリに2体以上のエージェントを入れるなら、worktree は実質必須です。設定は2行、覚えるコマンドは add / list / remove の3つで、得られるのは「衝突をマージ時ではなく入口で止める」という性質です。