git worktree: AIコーディングエージェント時代に再注目されるGitの隠れた機能 | Namsang LABS

#TL;DR

git worktreeは、ひとつのリポジトリから複数のブランチを別々のディレクトリに同時チェックアウトするGit標準機能である。2015年に導入された古い機能だが、Claude CodeのようなAIコーディングエージェントを並列実行する用途で再注目されている。Claude Codeは--worktreeフラグでネイティブサポートしており、subagentの隔離や/batchスキルもworktreeベースで動作する。

#`git worktree`とは

Gitリポジトリはデフォルトでワーキングディレクトリをひとつしか持たない。ブランチを切り替えるにはgit stash → checkout → 作業 → 再びcheckout → stash popという手順が必要で、ビルドキャッシュや変更中のファイルが多いと切り替え自体が負担になる。

git worktreeは、同じリポジトリの別ブランチを別ディレクトリにチェックアウトする機能だ。各ディレクトリは独立したワーキングツリーを持つが、.gitフォルダ(コミット履歴、ブランチ情報、設定)は共有される。

my-project/               ← メインワークツリー (mainブランチ)
my-project-payments/       ← リンクされたワークツリー (feature/payments)
my-project-refactor/       ← リンクされたワークツリー (feature/refactor)

git cloneと似て見えるが、決定的な違いがある。cloneは履歴全体を複製しディスクを倍使うのに対し、worktreeは.gitデータベースを共有するため追加のディスク使用量が最小限で済む。一方で作ったコミットがもう一方から即座に見える。

#基本コマンド

# 新しいブランチを作りながらワークツリーを作成
git worktree add ../my-project-hotfix -b hotfix/critical main

# 既存ブランチでワークツリーを作成
git worktree add ../my-project-payments feature/payments

# 現在のワークツリー一覧を確認
git worktree list

# ワークツリーを削除
git worktree remove ../my-project-hotfix

# 手動削除されたワークツリーをクリーンアップ
git worktree prune

#知っておくと便利な特性

同じブランチを2つのワークツリーで同時にチェックアウトすることはできない。Gitがこれを強制する。(--forceで回避可能だが推奨しない。)
stashはワークツリー間で共有される。.gitオブジェクトストアに保存されるためだ。
.gitignoreされたファイル(node_modules、.envなど)はワークツリーにコピーされない。新しいワークツリーでは依存関係を再インストールする必要がある。
ワークツリーはオリジナルとリンクしている。別個のcloneではないので、ブランチ作成やコミットは双方から見える。

#AIコーディングエージェント時代になぜ再注目されているのか

git worktreeはGit 2.5(2015年)で導入された。10年間「知ってると便利」程度の位置づけだったが、2025〜2026年にかけてAIコーディングエージェントが積極的に活用し始めたことで状況が変わった。

#核心的な理由: AIエージェントはワーキングディレクトリを占有する

Claude Code、Cursor、CodexのようなAIコーディングエージェントは、ワーキングディレクトリのファイルを直接読み書きする。エージェントがfeature/paymentsを作業している間、ワーキングディレクトリは変更中の状態だ。この状態で別のブランチをチェックアウトしたり、別のエージェントセッションを同じディレクトリで実行するとコンフリクトが発生する。

人間が作業する場合はファイルをひとつずつ編集するのでgit stashで事足りた。しかしAIエージェントは複数ファイルを同時に変更し、作業には数分以上かかる。その間、開発者は待つしかない。

worktreeはこの問題を解決する。エージェントセッションごとに別のワークツリーを割り当てれば、複数のタスクを並行して進められる。あるワークツリーでエージェントが作業している間に、別のワークツリーで完了した結果をレビューする流れが可能になる。

“The real power is that while Claude is working in one worktree, you can be reviewing what finished in another. You’re not waiting — you’re directing.”

Claudeがあるワークツリーで作業している間に、別のワークツリーで完了した結果をレビューできる。待つのではなく、指示を出すのだ。

— Dan Does Code: Parallel Vibe Coding with Git Worktrees

#エージェントエコシステム全体のトレンド

これはClaude Codeだけの話ではない。OpenAIのCodex CLIもバックグラウンドエージェントを独立したサンドボックスで実行するし、parallel-codeのようなオープンソースツールはClaude Code、Codex、Geminiをそれぞれ別のワークツリーで並列実行する。AnthropicのBoris Cherny(Claude Code開発者)は日常的に10〜15のワークツリーを同時に運用していると公言している。

「便利機能」だったgit worktreeが「並列実行インフラ」へと役割を変えたのだ。

#Claude Codeのネイティブworktreeサポート

Claude Code(v2.1.49+)はworktreeをネイティブサポートしている。手動でgit worktree addを実行する必要はなく、--worktree(-w)フラグひとつでワークツリーの作成からセッション開始まで一括で処理される。

#基本的な使い方

# 名前を指定してワークツリー作成 + セッション開始
claude --worktree feature-auth
# .claude/worktrees/feature-auth/ ディレクトリに作成
# worktree-feature-auth ブランチで開始

# 名前の自動生成
claude --worktree
# bright-running-fox のようなランダム名

# 省略形も可能
claude -w bugfix-123

並列作業はターミナルを複数開くだけでいい。

# ターミナル1: feature作業
claude -w feature-auth

# ターミナル2: バグ修正
claude -w bugfix-payment

# ターミナル3: リファクタリング検討
claude -w refactor-db

各セッションは完全に独立している。ファイルの競合もなく、コンテキストの干渉もなく並列実行される。

#ワークツリーのクリーンアップ

セッションを終了するとClaudeがクリーンアップ方法を確認する。

変更なし: ワークツリーとブランチが自動的に削除される。
変更あり: 残すか削除するか選択できる。残せば後から戻ることができ、削除すればコミットされていない変更とブランチがすべて除去される。

異常終了で残ったsubagentのワークツリーは自動的にクリーンアップされる。--worktreeフラグで直接作成したワークツリーは自動クリーンアップの対象外なので、使用後に手動で削除するかセッション終了時のクリーンアップオプションを選択する必要がある。

#`.worktreeinclude`で環境ファイルを自動コピー

新しいワークツリーには.gitignoreされたファイル(.envなど)がコピーされない。プロジェクトルートに.worktreeincludeファイルを作れば、指定したファイルを自動でコピーできる。

# .worktreeinclude (.gitignore 文法を使用)
.env
.env.local
config/master.key

#Subagentと`/batch` — worktreeの拡張

#Subagentのworktree隔離

Claude Codeのsubagent(サブエージェント)もworktreeを使える。セッション中に”use worktrees for your agents”とリクエストするか、カスタムsubagentのfrontmatterにisolation: worktreeを設定すれば、各subagentが独立したワークツリーで実行される。

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Review code changes for quality issues
isolation: worktree
allowed-tools: ['Read', 'Bash']
---
Review the changes in the current branch...

#`/batch`スキル — 大規模な並列変更

/batchスキルはworktreeを大規模に活用する。ひとつの大きなタスクを5〜30の独立単位に分解し、各単位ごとに別のワークツリーでバックグラウンドエージェントを実行する。各エージェントは実装、テスト、PR作成まで独立して遂行する。

# 例: src/ ディレクトリをSolidからReactにマイグレーション
/batch migrate src/ from Solid to React

実行するとオーケストレーターがタスクを分析し、たとえばsrc/components/Button、src/pages/Homeのような単位に分解したうえで、それぞれ別のワークツリーでエージェントを実行する。完了すると各単位ごとにPRが作成され、個別のレビューが可能になる。

incident.ioチームは、Claude Codeのworktree並列実行によりAPIクライアント生成のビルド時間を18%(30秒)短縮した事例を共有している。

#実践ワークフロー

#基本パターン: 並列開発

# 1. feature作業を開始
claude -w feature-auth

# 2. 別のターミナルでバグ修正
claude -w bugfix-payment

# 3. Claudeが作業中に完了済みワークツリーをレビュー
cd .claude/worktrees/feature-auth
git diff main

# 4. PR作成(ワークツリー内から)
git push -u origin feature/auth
gh pr create --title "Add auth module" --base main

# 5. クリーンアップ
git worktree remove .claude/worktrees/feature-auth

#Writer/Reviewerパターン

2つのセッションを役割分担して使うパターンだ。一方のセッションが機能を実装し、もう一方がフレッシュなコンテキストでレビューする。同じエージェントが書いたコードをレビューするよりバイアスが少ない。

# ターミナル1: 実装
claude -w implement-feature

# ターミナル2: レビュー(実装完了後)
claude -w review-feature
# "review the changes in ../implement-feature branch"

#テスト駆動パターン

一方のセッションが先にテストを書き、もう一方がテストをパスするコードを書く。

# ターミナル1: テスト作成
claude -w write-tests

# ターミナル2: 実装
claude -w implement
# "make all tests in the write-tests branch pass"

#注意すべきポイント

#依存関係の再インストールが必要

ワークツリーは.gitignoreされたファイルをコピーしないため、node_modulesや仮想環境などは新たにインストールする必要がある。.worktreeincludeで.envファイルはコピーできるが、大容量の依存関係は手動でインストールしなければならない。

#同じファイルを変更するとマージコンフリクトが発生する

ワークツリー間のファイル隔離は完全だが、最終的にブランチをマージする際に同じファイルを変更していればコンフリクトが起きる。これはworktreeの問題ではなくGit自体の挙動だ。各セッションが変更するファイルの範囲を分離することが重要になる。

#ワークツリー数には実質的な上限がある

Gitはワークツリー数を制限しないが、各ワークツリーでClaude Codeセッションを実行するとCPUとメモリを消費する。実務上は3〜5個が適正ラインで、それ以上はCI/CDやエージェントオーケストレーションに委ねるのが妥当だ。

#通知設定を併用する

ワークツリーを複数走らせると、どのセッションが終了したか追跡しづらくなる。Claude CodeのNotificationフックを設定すれば、セッションの完了や入力待ちのタイミングでアラートを受け取れる。

macOSではCLI通知に広く使われているterminal-notifierをインストールすればいい。

brew install terminal-notifier

.claude/settings.jsonに以下を追加する。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -message '$CLAUDE_NOTIFICATION'"
          }
        ]
      }
    ]
  }
}

#stash vs clone vs worktree

項目	git stash + checkout	git clone	git worktree
ディスク使用量	最小	全体複製	最小(共有)
履歴の共有	同一リポジトリ	別コピー	同一リポジトリ
並列作業	不可	可能	可能
AIエージェント並列実行	不可	可能だが非効率	最適
コミットの即時共有	該当なし	push/pullが必要	即時
Claude Codeネイティブサポート	なし	なし	`--worktree`フラグ

cloneでも並列実行は可能だが、リポジトリを丸ごと複製するためディスクを倍使い、コミット共有にpush/pullが必要になる。worktreeはそのオーバーヘッドなしに同じ結果を得られる。

git worktreeは10年前からある機能だが、AIコーディングエージェントと出会うことで本来の価値を発揮し始めている。claude -w task-nameの一行で並列開発環境が整う。

#参考資料

Claude Code Docs — Common Workflows: Git Worktrees — 公式ドキュメントのworktreeセクション
Botmonster — CLAUDE.md Productivity Stack: Skills, Git Worktrees, and Hooks — worktree + CLAUDE.md + hooks + skills フルスタックガイド
Dan Does Code — Parallel Vibe Coding: Using Git Worktrees with Claude Code — VS Code連携、PRワークフロー、コンフリクト処理の詳細ガイド
incident.io — Shipping Faster with Claude Code and Git Worktrees — APIクライアント生成ビルド時間18%短縮の事例
Threads — Boris Cherny: Introducing built-in git worktree support for Claude Code — Claude Code開発者による公式アナウンス
GitHub — parallel-code: Run Claude Code, Codex, and Gemini side by side — 複数AIエージェントをworktreeごとに並列実行するオープンソースツール
Git公式ドキュメント — git-worktree