Claude Code Worktree完全活用 — エージェント並列開発のための隔離戦略

要点

Claude Codeはgit worktreeを内蔵活用して、1つのリポジトリで複数のブランチを並行作業できます。エージェントを2〜3体並列で走らせるとき、それぞれが同じworking directoryを触ると衝突しますが、Worktreeで物理的にディレクトリを分けることでこの問題を解消できます。

本記事は次の3点を扱います。

1. Worktreeとは何か(git worktreeとの関係 + Claude Code内での扱い)
2. v2.1.133で追加されたbaseRef設定(fresh / head)の使い分け
3. 実運用で効く6パターン(並列実装 / 検証隔離 / 大型リファクタ前のサンドボックス 等)

なお、Subagentsによる並列化の話は別記事サブエージェント完全活用で扱っており、本記事はそれと物理層(ディレクトリ)で並列化する仕組みを補完します。

Worktreeとは何か

git worktree はgitに組み込まれた標準機能で、1つのリポジトリから複数の作業ディレクトリを生やす仕組みです。各worktreeは独立したブランチをチェックアウトでき、.git を共有するため履歴・remote・stashは一元管理されます。

# 通常の clone(1 ディレクトリ = 1 ブランチ)
~/repo
  └── (main がチェックアウトされた状態)
 
# worktree を追加すると...
~/repo
  └── (main)
~/repo-feature-x
  └── (feature/x がチェックアウトされた状態、.git は ~/repo を共有)
~/repo-feature-y
  └── (feature/y がチェックアウトされた状態)

Claude Codeはこの仕組みをエージェントごとの作業隔離に活用します。エージェントAがfeature-xで動き、エージェントBがfeature-yで動くとき、互いのファイル変更が混ざりません。

通常のgit cloneとの違い

worktreeは「複数cloneの利便性」と「単一cloneの軽さ」の両取りです。

Claude Code内での扱い

Claude Codeの worktree 関連設定は settings.json の worktree キー、または対応するCLIフラグで制御できます。基本的な動作:

• エージェントが新しい作業ブランチを切る際にworktreeを物理的に別ディレクトリに作成
• 作業終了後、worktreeを削除してmain側にdiffを戻す(またはPRとして残す)
• 並列エージェントは別々のworktreeで走るため、互いに干渉しない

v2.1.133で追加された baseRef 設定

2026年5月のv2.1.133で、worktreeのベースブランチを設定で指定できるようになりました。

設定例:

{
  "worktree": {
    "baseRef": "fresh"
  }
}

fresh と head の選び方

• 複数人で動くチーム + 並列実装 → fresh 推奨。各エージェント / 各人が常に最新origin/mainから派生するため、merge時の競合が起きにくい
• 個人開発 + 試行錯誤 → head 推奨。今書いているfeatureブランチの上にworktreeを切って、試案を分岐させられる

実運用で効く6パターン

パターン1: 並列実装の物理隔離

3つの独立した実装(API / UI / DBマイグレーション)を3体のエージェントに任せるとき、それぞれを別worktreeに配置するとファイル衝突の心配なく真の並列実行ができます。

# 概念図(Claude Code が内部でこの構造を作る)
~/repo            (main)
~/repo-api        (feature/api → エージェント A 担当)
~/repo-ui         (feature/ui → エージェント B 担当)
~/repo-db         (feature/db → エージェント C 担当)

各エージェントは自分のworktree内だけ書き換える。完了したら別々にPRとして上がる。

パターン2: 大型リファクタ前のサンドボックス

ライブラリ更新や大規模な構造変更を検討するとき、mainを汚さずに「やってみる」用のworktreeを作ります。

# Claude Code に依頼:
# 「このライブラリを v3 に上げて動くか、worktree で試して」
~/repo-lib-v3    (experiment/lib-v3)

結果が良ければPR化、ダメならworktreeごと捨てる。mainの作業は止めなくていいのが要点です。

パターン3: 検証 / 実機テストの隔離

「サンドボックスでこの設定を試したい」「異なる環境変数で動かしたい」といった検証で、設定ファイルを書き換える必要があるとき。worktreeを切ってそこで .env を編集すれば、他のworktreeへの影響なく試せます。

パターン4: レビュー作業の並列化

PRレビュー中に「実際に動かして見たい」と思ったら、そのPRブランチをworktreeでチェックアウトすれば、自分の進行中作業を中断せずに済みます。

# 進行中作業: ~/repo (feature/auth-rewrite)
# レビュー対象: feature/billing-fix を試したい
# → ~/repo-billing-fix で物理隔離して `npm test` 等を実行

パターン5: hotfix対応中の作業継続

本番障害でhotfixを急ぐとき、進行中の長期作業をstashせずに別worktreeでhotfixを切れます。

~/repo            (feature/long-running-rewrite、進行中)
~/repo-hotfix     (hotfix/security-patch、緊急対応)

長期作業のコンテキストを失わず、緊急対応に切り替えられる。

パターン6: Claude Code自体のセッション切り分け

複数のClaude Codeセッションを同時に開いて、別々のworktreeに向ける運用です。1つは長時間調査、もう1つは短時間の修正、と用途別に並走させると効率が上がります。

落とし穴

落とし穴1: ディスク容量

worktreeは .git こそ共有しますが、チェックアウトしたファイル群はそれぞれ実体として存在します。10 GBのmonorepoを5 worktree切ると50 GBです。検証用worktreeは使い終わったら git worktree remove で削除する習慣が必要。

落とし穴2: hooks / lockfileの競合

pre-commit hookがインストールするファイル(.husky/ 等)はworktree間で共有されます。片方で追加したhookが他方のworktreeでも有効になる、といった意図しない伝播が起きうるので、hooks系は共通化か完全分離か方針を最初に決めておきます。

package-lock.json 等のlockfileはworktreeごとに別個に持つことが多く、ブランチ間で依存関係が異なるとき、worktree切替時に npm install が必要になります。

落とし穴3: 削除忘れ

git worktree remove を忘れると、ブランチを git branch -d しようとして「worktreeでチェックアウト中」と怒られます。git worktree list で定期的に棚卸ししましょう。

落とし穴4: シンボリックリンクと相対パス

worktreeのディレクトリ位置が変わるため、絶対パス前提のスクリプトがある場合は壊れる可能性があります。プロジェクト内のスクリプトは git rev-parse --show-toplevel を起点にするなど、worktree-safeに書くと移植性が上がります。

著者の運用方針

実運用で見えた指針:

1. 個人開発なら baseRef: head がデフォルト — 今書いている内容を踏み台にした実験が多いため
2. チーム開発なら baseRef: fresh を強く推奨 — origin/mainからの派生で競合を最小化
3. 使い終わったworktreeは同日中に削除 — 容量と認知負荷の両方の管理コストが下がる
4. worktreeのディレクトリ命名はブランチ名と一致させる — ~/repo-<branch-name> 形式で揃えると、どのworktreeが何か即座に分かる

まとめ

Worktreeは「1リポジトリで複数ブランチを物理的に隔離する」シンプルな仕組みですが、エージェントの並列化・大型リファクタの試行・hotfix対応など、実運用で効く場面は多数あります。v2.1.133で baseRef の選択肢が増えたことで、個人 / チームそれぞれに合った設計ができるようになりました。Claude Code内のエージェント並列化(サブエージェント完全活用)と組み合わせると、論理的隔離(コンテキスト)と物理的隔離(ファイル)の両方が揃い、複数作業の干渉を最小化できます。