AIエージェント用Git worktreeとWorktrunkを調べる
AIエージェントを複数の課題へ同時に割り当てるなら、ブランチ名だけでなく作業ディレクトリも分ける必要があります。
1つのディレクトリを共有すると、未コミット変更、生成物、依存関係、開発サーバーが混ざります。
この問題を調べるため、Git標準のworktreeとWorktrunkを「並行作業の境界」と「ライフサイクル管理」に分けて考えます。
branchだけでは作業を隔離できない
同じディレクトリでブランチだけを切り替える運用では、次の状態が共有されます。
- 前の課題の未コミット変更
- エージェントが編集中のファイル
node_modulesやビルドキャッシュ.envと接続先- 開発サーバーのポート
- 実行中のプロセス
人間が常に端末を見ていても、混ざった状態を見落とします。
AIエージェントは、端末を見ていない間にもファイルとコマンドを扱います。
そのため、「人間がブランチ状態を把握している」という前提を安全境界にしない方がよいです。
Git worktreeが提供する境界
Gitの公式ドキュメントでは、1つのリポジトリへ複数の作業ツリーを関連付けられます。
それぞれが作業ツリー、HEAD、indexを持つため、別ブランチを同時にチェックアウトできます。
作成の最小例は次です。
git worktree add -b feature-auth ../repo.feature-auth main
git worktree list作業を終えてレビューと統合が済んだら、対象worktreeと不要なブランチを確認してから整理します。
git worktree remove ../repo.feature-auth
git branch -d feature-authworktreeはリポジトリの完全なコピーではありません。
Gitオブジェクトを共有しながら、作業ツリーやindexを分けるため、同じブランチを複数のworktreeでチェックアウトする制約があります。
ディレクトリをファイルシステムから直接削除した場合は、git worktree listで残った管理情報を確認し、必要ならgit worktree pruneを使います。
常時マウントされない場所へ置く場合は、git worktree lockも確認します。
Worktrunkはライフサイクルを短くする
Git標準のworktreeは、パス、ブランチ、統合、削除を個別に操作します。
Worktrunkはそのライフサイクルをブランチ名中心のCLIへまとめます。
公式ドキュメントで最初に確認する入口は次です。
wt switch --create feature-auth
wt list
wt merge mainwt mergeは導入したバージョンや設定によって、コミット、squash、rebase、worktree削除まで扱うことがあります。
実行前に、差分、未コミット変更、コマンドのヘルプを確認します。
作成フック、削除フック、ポート割り当て、AIコマンド起動も設定できるが、最初から有効にする必要はありません。
まず作成、一覧、明示的な統合だけを使い、困りごとが出た機能を追加します。
エージェントを起動する単位を決める
エージェントへは、1つの作業ディレクトリと1つの作業指示を割り当てます。
公式例に近い起動形は次です。
wt switch --create --execute codex feature-a -- '認証処理のテストを追加する'--executeの引数やエージェントCLIは環境ごとに異なります。
重要なのは、1つのworktreeへ複数の書き込み主体を置かないことです。
ファイルを分けても、同じAPI契約や設定ファイルを変更すれば、統合時の競合は起こります。
並行化する前に、共有インターフェースと統合順序を決めます。
mainを基準状態として保護する
mainは、統合済みの基準状態を確認し、worktreeを作る起点として使います。
エージェントの作業をmainで直接始めません。
小さな変更でも、コミット対象ならタスク用worktreeを作ります。
プロジェクトルールには、少なくとも次を明記します。
- mainを直接編集しない
- 並行作業では1タスク1worktreeにする
- 他のworktreeのファイルを変更しない
git reset --hardや広い範囲を削除しない- 統合前に差分と検証結果を確認する
.envや秘密情報を無条件にコピーしない
このルールはエージェントだけでなく人間にも適用します。
worktreeの外側にある状態を管理する
worktreeはファイルを分けるが、開発環境のすべてを自動的に分離しません。
依存関係
Node.jsのnode_modulesやRustのtargetをworktreeごとに作ると、初回セットアップが重くなります。
共有キャッシュは高速化に役立つが、ブランチ間で生成物を混ぜる可能性もあります。
最初はworktreeごとにセットアップし、速度が問題になってから共有方法を検証します。
.env
Git管理外の.envにも、データベース接続先やAPIキーが入ります。
コピーする場合は、低権限の開発用credentialだけを使います。
本番資格情報を複数のworktreeへ配るより、worktreeごとに安全なテスト環境を用意します。
ポート
複数の開発サーバーが同じ3000番ポートを使うと衝突します。
ブランチ名からポートを決めるか、Worktrunkのポート割り当てを使います。
エージェントにサーバーを起動させない運用も選択肢です。
統合と後片付けをレビューの一部にする
エージェントの出力を、そのままmainへ取り込みません。
最低限、次の順番で確認します。
- worktreeの差分を見る
- コミット済み変更と未コミット変更を分ける
- lint、テスト、buildをworktreeで実行する
- 変更範囲と生成物を確認する
- Pull Requestまたはローカルマージで統合する
- 不要なworktreeとブランチを削除する
wt listとgit worktree listを定期的に確認します。
古いworktree、起動中のプロセス、不要なブランチを放置すると、並行作業の境界が分かりにくくなります。
まとめ
Git worktreeの価値は、複数ブランチを開くことだけではありません。
作業の責任範囲をディレクトリ単位で分け、レビュー可能な変更へ変える境界になります。
Worktrunkは作成、一覧、統合、削除の手順を短くします。
ただし、.env、ポート、依存関係、認証情報は別途設計する必要があります。
AIエージェントの並行作業でmainを保護する目的なら、Git標準のworktreeだけでも基礎は成立します。