はじめに

AI エージェントにタスクを任せようとしたのに、ロード中のスピナーに邪魔されたことはありませんか？

AI エージェントが長時間かかるタスクを処理している間、コンテキストを頻繁に切り替えずに他の機能開発を続けるのは難しくなります。

git worktree を使うと、複数のブランチを同時に別々のディレクトリへチェックアウトできます。これにより、前のタスクの完了を待つことなく、複数の AI エージェントを並列で実行できるようになります。

このドキュメントでは、Git worktree の仕組み、worktree を前提としたプロジェクト構成、そして複数の worktree 上で AI エージェントを効率的に活用する方法について説明します。

git-worktree とは？

通常、Git では 1 つのリポジトリディレクトリにつき、チェックアウトできるブランチは 1 つだけです。

これまでは、複数のブランチを同時に扱うために、リポジトリを複数回 clone する方法が一般的でした。しかし、この方法にはいくつか欠点があります。

• clone ごとに独自の .git データベースを持つため、ローカルブランチ、stash、参照情報などが共有されない。
• clone のたびにリポジトリ履歴全体の fetch や展開が必要になる場合があり、セットアップに時間がかかる。
• 複数の clone で同じブランチを誤って操作し、変更を上書きしたり競合する rebase を行ってしまう可能性がある。
• 各 clone を個別に fetch・更新する必要がある。

git worktree を使うと、同じ Git リポジトリに紐づいた追加の作業ディレクトリを作成できます。

各 worktree は独自のチェックアウトブランチとファイルシステム状態を持ちながら、Git オブジェクトデータベースを共有します。独立した clone のように扱えますが、clone したときのような欠点を回避できます。

基本的な Git Worktree コマンド

新しい Worktree を作成する

git worktree add ../project__feature-abc

このコマンドは以下を実行します。

• project__feature-abc という兄弟ディレクトリを作成する。
• 新しいディレクトリで project__feature-abc ブランチをチェックアウトする。
• 新しいディレクトリを現在のリポジトリへリンクする。

/projects
├── project
└── project__feature-abc (✨ 新しいディレクトリ)

2 番目の引数を使うことで、新しいディレクトリでチェックアウトするブランチ名を指定できます。

git worktree add ../project__feature-abc feat/abc

ブランチがまだ存在しない場合は以下のようにします。

git worktree add ../project__feature-abc -b feat/abc

既存の Worktree を一覧表示する

git worktree list

出力例:

/path/project                  a1b2c3d [main]
/path/project__feature-abc     d4e5f6g [feat/abc]
/path/project__refactor-api    h7i8j9k [refactor/api]

Worktree を削除する

git worktree remove ../feature-auth

worktree と関連ディレクトリの両方を削除します。

古い Worktree 情報を整理する

git worktree prune

手動で worktree ディレクトリを削除した場合に便利です。

ワークフロー例

各 worktree は独立したディレクトリとして存在するため、それぞれを IDE、ターミナル、または AI 支援開発ツールで個別に開き、異なるタスクを各 AI エージェントへ割り当てることができます。

Worktree を作成する

メインリポジトリから、いくつかの worktree を作成します。

git worktree add ../project__auth -b feat/auth
git worktree add ../project__dashboard -b feat/dashboard
git worktree add ../project__update-user -b feat/update-user

これにより、対応する作業ディレクトリが作成されます。

/projects
├── project
├── project__auth ✨
├── project__dashboard ✨
└── project__update-user ✨

各 Worktree の AI エージェントへタスクを割り当てる

それぞれの worktree を別々のウィンドウやワークスペースで開き、専用の AI エージェントを割り当てることができます。

たとえば、私は 2 つの VSCode ウィンドウを開きます。片方ではダッシュボードの構築を AI エージェントへ依頼し、もう片方ではユーザー情報を更新する API の実装を依頼します。

各エージェントは独立したディレクトリ上で動作するため、ファイルシステム上の変更は分離されたまま保たれ、無関係な作業に影響されることなく、タスクごとのコンテキストを維持できます。これにより、長時間実行される AI エージェントのタスクが、他の開発作業を妨げることを防げます。

1 つのタスクが終わるのを待つ代わりに、ウィンドウを切り替えながら、複数の worktree 上で並列に開発を進めることができます。

変更を commit・push する

タスクが完了したら、通常どおり対応するブランチへ commit と push を行います。違うのは、頻繁に stash やブランチ切り替えを行う必要がないことです。各 git worktree は同じ Git リポジトリデータベースを共有しながら、それぞれ独立した作業状態を維持します。

推奨ディレクトリ構成

各 worktree は独立したディレクトリとして存在するため、メインリポジトリの内側ではなく、同じ階層に配置することを推奨します。これにより、意図しないファイル追跡を防ぎ、リポジトリ構造を整理しやすくなります。

例:

✅ 推奨
projects/
├── project
├── project__auth
├── project__dashboard
├── project__error-code
├── project__hotfix
└── project__refactor-composable

❌ 非推奨
projects/
└── project
    ├── auth
    ├── dashboard
    ├── error-code
    ├── hotfix
    └── refactor-composable

Worktree 間で依存関係を管理する

worktree を作成しても、ignore されたファイルは自動的にはコピーされません。そのため、各 worktree は独自の node_modules/ ディレクトリを持つことになります。

作成した worktree 内で、依存関係をインストールする必要があります。

npm install

また、メインリポジトリから環境変数ファイル（.env、.furo-env など）を各 worktree へコピーする必要がある場合もあります。