【Claude Code中級編 #12】Sub agentとWorktreeの組み合わせ——並列開発の設計

第5回のAgent toolで「同じファイルを複数エージェントが編集するとコンフリクトする」という制約に触れた。この記事ではその解決策——git worktreeとSub agentを組み合わせた並列開発の設計を扱う。

この記事でわかること：

git worktreeの仕組みとClaude Codeでの使い方
isolation: "worktree" オプションでエージェントごとに独立ブランチを作る方法
並列作業後のマージ戦略と設計上の注意点

Agent toolだけでは解決できない問題

第5回で「向いていない場面」として挙げた例：

❌ 複数のエージェントが同じファイルを編集するとコンフリクトが発生する

たとえば「フロントエンドとバックエンドを並列実装して」と指示したとき、両方が src/types.ts（共通型定義）を編集しようとすると壊れる。

エージェントA（フロント実装）: src/types.ts を編集 → 書き込み成功
エージェントB（バックエンド実装）: src/types.ts を編集 → Aの変更を上書き or 競合

同一ワーキングディレクトリ上で動いている限り、並列エージェントの書き込みは必ずこの問題にぶつかる。

git worktreeとは

git worktree はGitの標準機能で、1つのリポジトリから複数のワーキングディレクトリを作れる仕組み。

通常のgit構成:
  repo/
    ├── .git/
    ├── src/
    └── ...

git worktreeを追加した構成:
  repo/          ← mainブランチで作業中
    ├── .git/
    ├── src/
    └── ...
  repo-frontend/ ← feature/frontendブランチで独立して作業
    ├── src/     （同じ.gitを共有）
    └── ...
  repo-backend/  ← feature/backendブランチで独立して作業
    ├── src/
    └── ...

.git ディレクトリは1つだけ共有しながら、ワーキングディレクトリだけを複数持てる。各ワーキングディレクトリは別ブランチをチェックアウトした状態で独立して動く。

Claude CodeのWorktreeサポート

Claude Codeにはworktreeと統合する仕組みが2つある。

① isolation: "worktree" オプション（推奨）

Agent toolに isolation: "worktree" を指定すると、Claude Codeが自動でworktreeを作成してサブエージェントをその中で動かす。

isolation: "worktree" の挙動:
  → Agentが自動でgit worktreeを作成
  → サブエージェントはそのworktree内（独立ブランチ）で動く
  → 変更なしで終了した場合: worktreeは自動削除
  → 変更があった場合: worktreeのパスとブランチ名が返ってくる

オーケストレーター側にworktreeを作るコマンドを書く必要がない。

② git worktreeを手動で使う

worktreeの管理を細かくコントロールしたいときは、gitコマンドで手動作成する。

# worktreeを追加（ブランチも同時に作成）
git worktree add ../repo-frontend feature/frontend
git worktree add ../repo-backend feature/backend

# 確認
git worktree list

基本ワークフロー

isolation: "worktree" を使った並列開発の流れ。

① オーケストレーター（メインセッション）がタスクを分割
        ↓
② サブエージェントAを isolation: "worktree" で起動
   サブエージェントBを isolation: "worktree" で起動  ← 同時
        ↓
③ A: 自動生成されたブランチで作業
   B: 自動生成されたブランチで作業  ← 互いに独立
        ↓
④ 各エージェントから「自動生成されたブランチ名・パス」が返ってくる
        ↓
⑤ オーケストレーターがマージを判断・実行

isolation: "worktree" ではブランチ名を指定できない。Claude Codeが自動でブランチを作成し、作業完了時にブランチ名とパスを返す仕組みになっている。

各エージェントが別ブランチで動くため、同じファイルを編集してもコンフリクトしない。コンフリクトは「マージ時」に一度だけ発生し、人間が確認して解決できる。

実用例：フロント・バックエンドを並列実装

ユーザー管理機能を例に、並列実装の指示を設計する。

タスク分割の設計

タスク全体: ユーザー管理機能の実装
  ├── タスクA（フロント）: src/app/users/ の画面・コンポーネント
  ├── タスクB（バックエンド）: src/api/users/ のエンドポイント
  └── 共通: src/types/user.ts（先に確定させる）

重要: 共通ファイル（型定義など）は並列作業を始める前に確定させる。並列作業の対象から除外することでコンフリクトを設計段階で回避できる。

オーケストレーターへの指示例

以下のタスクをworktreeで隔離して並列実装してください。

【事前確認】
- src/types/user.ts はすでに User 型が定義済み（変更不要）

【タスクA: フロントエンド】
worktreeで隔離して実行
src/app/users/ に以下を実装:
- ユーザー一覧ページ (page.tsx)
- ユーザーカード コンポーネント (UserCard.tsx)
src/types/user.ts は読み取りのみ（編集しない）

【タスクB: バックエンド】
worktreeで隔離して実行
src/api/users/ に以下を実装:
- GET /api/users エンドポイント
- POST /api/users エンドポイント
src/types/user.ts は読み取りのみ（編集しない）

各エージェントは完了したらブランチ名を報告してください。

「worktreeで隔離して」と自然言語で指示すると、Claude Codeが内部的にAgent toolの isolation: "worktree" パラメータを使ってサブエージェントを起動する。確実にworktree隔離を使わせたい場合は、CLAUDE.mdに「並列実装時はworktree isolationを使うこと」と書いておくのが効果的。

「編集しない」と明示することで、共通ファイルへの意図しない変更を防げる。

マージ戦略

並列作業が完了したら、各ブランチをmainにマージする。

パターン①：シンプルなマージ（依存なし）

2つのブランチが完全に独立している（編集ファイルの重複がない）場合は順番にマージするだけ。

git checkout main
git merge feature/frontend   # コンフリクトなし
git merge feature/backend    # コンフリクトなし

パターン②：コンフリクトが予想される場合

共通ファイルを両方が変更している場合は、一方をベースに手動でマージする。

# まずAをマージ
git checkout main
git merge feature/frontend

# Bをマージ（コンフリクトが出る可能性あり）
git merge feature/backend
# → コンフリクト発生

# コンフリクト確認
git status
# → 手動で解決してコミット
git add src/types/user.ts   # 解決したファイルだけをステージング
git commit -m "merge: resolve conflict between frontend and backend"

パターン③：PR経由（チーム開発）

個人開発でも、大きな並列実装ではPR経由のマージが安全。

# 各ブランチをpush
git push origin feature/frontend
git push origin feature/backend

# PRを作成 → レビュー → マージ
gh pr create --base main --head feature/frontend --title "feat: ユーザー一覧UI"
gh pr create --base main --head feature/backend  --title "feat: ユーザー管理API"

Claude Codeに「PRを作成してレビューをリクエストして」と指示することで、マージ前の確認フローを組み込める。

worktreeを手動で作る場合のワークフロー

isolation: "worktree" を使わず、worktreeを自分で管理する場合。

# 並列作業用にworktreeを2つ作成
git worktree add /tmp/work-frontend feature/frontend
git worktree add /tmp/work-backend  feature/backend

# Claude Codeに指示するとき
「/tmp/work-frontend ディレクトリでフロントの実装をして」
「/tmp/work-backend  ディレクトリでバックエンドの実装をして」

# 作業完了後にworktreeを削除
git worktree remove /tmp/work-frontend
git worktree remove /tmp/work-backend

使い終わったworktreeは git worktree remove で削除する。isolation: "worktree" の自動クリーンアップと違い、手動管理では削除し忘れが起きやすい。

向いている場面・向いていない場面

向いている

編集対象ファイルがほとんど重ならない並列実装 — フロント・バックエンドの分離など
大規模リファクタの複数モジュール同時対応 — モジュールごとに独立したブランチで安全に進められる
実験的な変更を本線に影響させたくない場合 — worktreeがブランチを隔離するため、mainへの影響ゼロ

向いていない

共通ファイルへの変更が多い場合 — worktreeで隔離しても、マージ時にコンフリクトが集中する
タスク間に強い依存がある場合 — AがBの結果を待たないと進めない設計は、並列化よりパイプライン型が向く
小規模な単一タスク — worktree作成・削除のオーバーヘッドが効果を上回る

まとめ

課題	解決策
複数エージェントが同じファイルを編集するとコンフリクト	`isolation: "worktree"` で各エージェントを別ブランチに隔離
worktreeの手動管理が面倒	`isolation: "worktree"` で自動作成・自動クリーンアップ
並列作業後のマージが複雑	共通ファイルを事前確定 + PR経由でレビューを挟む
本線(main)への影響が怖い	worktreeはブランチを切るため、mainを汚染しない

Sub agentとWorktreeの組み合わせの核心は「コンフリクトをマージ時の1回に集約する」設計にある。並列作業中はお互いを干渉させず、確認が必要なタイミングだけ人間が判断する——この流れを設計できると、Claude Codeによる並列開発が一段と安定する。

← 第11回：コンテキスト管理の技術——トークンを無駄にしない｜第13回：Channelsで通知を飛ばす——Webhook・Discord連携の実装 →