複数エージェントを同じリポジトリで並走させると壊れる — worktree で作業領域を分離する設計

Antigravity 2.0 の projects に worktree を載せる

Antigravity 2.0 は projects と worktree のサポートが入り、サイドバーで作業単位を切り替えられるようになりました。エージェント管制塔として複数エージェントを監督する設計では、この projects を「worktree 1つ = project 1つ = エージェント1本」という対応で割り当てると、画面上でも作業の独立性が見えるようになります。

私は次のレイアウトに落ち着いています。

~/repos/antigravitylab.net        ← 統合・push を行う「親」クローン（人間が触る）
~/repos/wt-agent-articles         ← project: 記事エージェント
~/repos/wt-agent-deps             ← project: 依存更新エージェント
~/repos/wt-agent-i18n             ← project: 翻訳整合エージェント

親クローンでは作業させず、各 worktree でエージェントが作った feature ブランチを、人間（または統合役のエージェント1本）が順番に main へ取り込みます。push の窓口を1か所に絞ることで、複数エージェントが同時に origin/main を奪い合う non-fast-forward の押し合いも避けられます。

後始末まで含めてライフサイクルを管理する

worktree は作るのは簡単ですが、消し忘れると git worktree list が散らかり、ディスクも食います。エージェントの仕事が終わったら、ブランチを取り込んでから worktree を畳む、という後始末をスクリプト化しておきます。

#!/usr/bin/env bash
# finish_worktree.sh <worktree-path> <branch>
# 取り込み済みの worktree を安全に畳む
set -euo pipefail
WT="$1"; BR="$2"
REPO="$HOME/repos/antigravitylab.net"
 
cd "$REPO"
 
# 1) 作業ツリーに未コミットの変更が残っていないか確認（残っていれば中断）
if [ -n "$(git -C "$WT" status --porcelain)" ]; then
  echo "⚠️ $WT に未コミットの変更があります。畳むのを中止します。"
  exit 1
fi
 
# 2) ブランチが main に取り込み済みか確認（未取り込みなら中断）
if ! git merge-base --is-ancestor "$BR" origin/main; then
  echo "⚠️ $BR はまだ origin/main に取り込まれていません。中止します。"
  exit 1
fi
 
# 3) worktree を削除し、用済みブランチも消す
git worktree remove "$WT"
git branch -d "$BR"
git worktree prune
echo "✅ $WT を畳みました（$BR 削除済み）"

ポイントは、未コミットの変更が残っていないことと、ブランチが main の祖先になっている（取り込み済みである）ことを、削除前に必ず検査することです。git merge-base --is-ancestor は、取り込み済みなら終了コード0、未取り込みなら1を返します。これを通過しない worktree は畳まない、という規律を機械で守らせます。

どこまで並列にしてよいか

分離できたからといって無限に並列化してよいわけではありません。実運用で回している体感では、4 並列を超えたあたりから、push の取り込み待ち行列とレビューの目が追いつかなくなります。

並列数の上限は、エージェントの本数ではなく「人間（または統合役）が一定時間内に main へ安全に取り込める本数」で決めるのが現実的です。私は記事・依存・翻訳整合の3本＋統合役1本の構成を基本線にしています。これ以上増やしたくなったら、並列を増やすより、各エージェントの担当範囲を太くするほうが破綻しにくいと感じています。

本番運用での落とし穴として、私自身が踏んだ注意点を3つ挙げておきます。

1. 親クローンでうっかり作業してしまう取り違えです。エージェントには worktree のパスを絶対パスで渡し、親クローンでは git config --local receive.denyCurrentBranch refuse のような防御も併用すると、誤操作を早めに弾けます。
2. worktree の消し忘れです。畳み忘れた作業ツリーが20個ほど溜まると、git worktree list の確認に毎回数秒の無駄が乗り、ディスクも数百 MB 単位で食います。1日の終わりに後始末スクリプトをまとめて回す運用をお勧めします。
3. 同名ブランチの再利用です。前回の agent/articles が残ったまま次回も同名で作ろうとすると失敗します。worktree 名・ブランチ名には日付や実行 ID を含め、衝突を避けるのが安全です。

アプリ開発で AdMob のレポート集計や App Store 向けの素材生成をエージェントに任せている私の体感では、並列を3〜4本に抑えて担当範囲を太くしたほうが、5本以上に薄く割るより全体の所要時間がむしろ約20%短くなりました。取り込み待ちの行列が短くなるためだと考えています。

並列エージェントの設計は、速さよりも「壊れないこと」を先に固めるほど、結果的に手戻りが減って速くなります。次に複数エージェントを走らせるときは、まず worktree でそれぞれの作業領域を分けるところから始めてみてください。