⟐ Claude Code/2026-04-02中級

Claude Code worktreeで並列開発を加速する

Claude Code の worktree で複数タスクを安全に並行させるための実装メモ。ブランチを物理的に分離してコンテキストスイッチを軽くする手順を、実際に運用してわかった勘所とともに整理します。

Claude Code²⁰² worktree³ 並列開発² Git⁴ ワークフロー²⁰

✦ プレミアム記事

フィーチャー開発の途中で本番のバグ報告が飛び込んでくる。レビュー待ちのあいだに別の改修へ手を伸ばす。個人開発で複数のアプリを並行して回していると、こうした割り込みが日常的に起こります。ブランチを切り替えるたびにビルドキャッシュが無駄になり、頭の中の文脈もリセットされてしまう。この摩擦を物理的に解消してくれるのが Git worktree と Claude Code の組み合わせでした。ここでは、複数の開発コンテキストを安全に分離したまま並行させる方法を、実装レベルで整理します。

私自身、個人開発で iOS と Android のアプリを同時に抱えているため、worktree を導入する前は「片方を直すともう片方のビルド環境が崩れる」という小さな事故を何度も繰り返していました。作業場所そのものを分けてしまえばこの種の取り違えは起きにくくなる、という発見が、この記事を書く動機になっています。

並列開発が重要な理由

従来のGitワークフロー（main → feature-X → PR → merge）では、1つの作業単位が完了するまで次のタスクに進めません。しかし、実際のプロジェクト管理では以下のようなシナリオが頻繁に起こります：

フィーチャーAを開発中に、本番環境でバグが発見される
PR中のコードレビューを待つ間に、別のフィーチャーに着手したい
複数の開発者が同じリポジトリで異なるブランチを独立して進めたい

従来のアプローチでは、ローカルブランチを切り替えるたびに：

ワーキングディレクトリ全体が再構築される（時間がかかる）
エディタやビルドシステムのキャッシュが無駄になる
前のコンテキストに戻すのが手間

Git worktreeはこれらの問題を根本的に解決します。複数のブランチを 独立したディレクトリツリー として同時に管理できるため、コンテキストスイッチが軽いのです。

Git worktreeの基礎知識

worktreeとは何か

Git worktreeは、1つのリポジトリの複数のブランチを、複数のワーキングディレクトリで同時に管理できるGit機能です。

# 通常のGitワークフロー（切り替えが必要）
git checkout main
git checkout feature-X
git checkout bugfix-Y
 
# worktreeのワークフロー（並列実行可能）
git worktree add ../main-work main
git worktree add ../feature-X-work feature-X
git worktree add ../bugfix-Y-work bugfix-Y
# 3つのディレクトリが同時に独立存在

主な利点

物理的な独立 - 各worktreeは独立したディレクトリツリー。.git/directoryは共有だが、ワーキングツリーは完全に分離
コンテキストスイッチの高速化 - ブランチ切り替えではなくディレクトリ移動なので、エディタやビルドシステムの状態を保持可能
並列実行 - 複数のClaude Codeセッションを同時に起動可能
メモリ効率 - git statusやgit logを個別に実行でき、大規模リポジトリでの待機時間が短い

worktreeとbranchの関係

重要な制約があります：同じブランチを複数のworktreeに割り当てることはできません。これはGitの設計上の制限で、チェックアウト状態の一貫性を保つためです。

# これはNG：同じブランチを2つのworktreeに割り当て
git worktree add ../work1 main
git worktree add ../work2 main  # エラー：ブランチ'main'は既にチェックアウト中
 
# 正しい方法：新しいブランチを作成して割り当て
git worktree add ../work1 main
git worktree add ../work2 -b feature/new-task

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦worktreeを使った並列開発のセットアップ方法と実践的なコマンド集

✦複数のClaude Codeセッションを同時に走らせる具体的な手順

✦ブランチ分離で安全に開発する上級テクニックとトラブルシューティング

Stripe による安全な決済 · いつでもキャンセル可能

✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または

メンバーシップなら全記事が読み放題 →

Claude Codeでのworktree活用

Claude Code worktreeオプション

Claude Codeは --worktree オプションをサポートしています。これにより、特定のworktreeをターゲットにした自動コード変更を実行できます。

# 構文
claude --worktree=<worktree_path> --context=<context_details>
 
# 例：feature-X-workディレクトリをターゲット
claude --worktree=../feature-X-work \
       --context="実装する機能は認証システムの改善"

Isolation機能について

Claude Codeには --isolated フラグもあり、以下の効果があります：

ファイルシステムアクセス制限 - worktree内のファイルのみアクセス可能
Git操作の分離 - 該当worktree内でのみgit add/commit実行
他worktreeへの影響なし - 一方のセッションが他方を破壊しない

# 厳密なisolation
claude --worktree=../feature-X-work \
       --isolated \
       --context="新しいUI コンポーネント実装"

並列開発のセットアップ

ステップ1：既存リポジトリの確認

まず、現在のリポジトリ構成を確認します。

# プロジェクトディレクトリに移動
cd ~/my-project
 
# リポジトリの状態確認
git status
git branch -a
 
# 現在のworktreeを表示
git worktree list

ステップ2：worktreeディレクトリ構造の設計

複数のworktreeを管理する場合、ディレクトリ構造を明確にしておく点が肝心です。推奨構造は以下の通りです：

~/projects/
└── my-project/
    ├── .git/                      ← Git共有ディレクトリ
    ├── main-work/                 ← メインブランチ用worktree
    ├── feature-auth-work/         ← 認証機能開発用
    ├── feature-payment-work/      ← 決済機能開発用
    ├── bugfix-issue-123-work/     ← バグ修正用
    └── release-v2-0-work/         ← リリース準備用

この構造では、メインの.git/ファイルが1つで、複数のworktreeがその下に並列存在します。

ステップ3：worktreeの初期化

各タスク用のworktreeを作成します。

# メインブランチ用（既に存在する可能性もあるので確認）
git worktree add main-work main
 
# フィーチャー開発用（新規ブランチ作成）
git worktree add feature-auth-work -b feature/authentication
 
# バグ修正用（existingブランチから）
git checkout -b bugfix/issue-123
git worktree add bugfix-123-work bugfix/issue-123
 
# 各worktreeの状態確認
git worktree list

出力例：

/home/user/my-project/main-work          main        abcd1234
/home/user/my-project/feature-auth-work  feature/authentication  created new branch
/home/user/my-project/bugfix-123-work    bugfix/issue-123  e5f6789a

ステップ4：Claude Codeセッション管理

各worktreeで独立したClaude Codeセッションを起動します。

# ターミナルを複数開き、各worktreeに移動
 
# ウィンドウ1：主要タスク
cd feature-auth-work
claude --context="認証フロー実装：OAuth 2.0とセッション管理"
 
# ウィンドウ2：バグ修正
cd bugfix-123-work
claude --context="本番エラーの根本原因調査と修正"
 
# ウィンドウ3：ドキュメント整備
cd main-work
claude --context="APIドキュメント更新"

各セッションは独立したコンテキストで動作するため、一方のセッションでの変更が他方に影響しません。

実践ワークフロー：フィーチャー開発

フィーチャー開発の完全なワークフローを、実装レベルで解説します。

初期化フェーズ

# リポジトリのルートで作業開始
cd ~/my-project
 
# 最新のmainを取得
git fetch origin main
git checkout main
git pull origin main
 
# 新規フィーチャーブランチ作成
git checkout -b feature/user-dashboard
 
# worktree作成
git worktree add feature-dashboard-work feature/user-dashboard
cd feature-dashboard-work

開発フェーズ

Claude Codeセッション起動：

claude --worktree=. \
       --context="ユーザーダッシュボードの実装
       - サイドバーに過去7日の活動サマリー表示
       - 実装言語はTypeScript + React
       - スタイルはTailwind CSS
       - 既存の useAuth フックを使用"

Claude Codeが以下を自動実行：

必要なコンポーネントファイル作成（src/components/Dashboard.tsx等）
TypeScript型定義追加
Storybook用のストーリーファイル追加
テストファイル生成
自動コミット（git add src/）

コードレビュー前のチェック

# ローカルテスト実行
npm test
npm run build
 
# 型チェック確認
npx tsc --noEmit
 
# Linter実行
npm run lint
 
# 差分確認
git log --oneline main..feature/user-dashboard
git diff main..feature/user-dashboard -- src/

PR準備

# コミット履歴をきれいにする（必要な場合）
git rebase -i main
 
# 最終確認
git status
 
# pushして準備完了
git push origin feature/user-dashboard

GitHub UIでPRを作成。その間、別のworktreeで別タスク開始可能。

実践ワークフロー：バグ修正と機能開発の並行

私はこの並行パターンを、複数アプリの保守と新機能を同じ週に進めるときに、もっとも恩恵を感じる使い方として頼りにしています。リリース済みアプリのクラッシュ対応を止めずに、次の機能開発を別レーンで進められます。

本番環境でバグが発見された場合、複数のworktreeの力が最大限発揮されます。

シナリオ

進行中: feature/user-dashboard の開発（feature-dashboard-work）
発生: 本番でユーザーログイン時にタイムアウトエラー
対応: 同時並行で原因調査と修正

バグ修正worktree作成

main-workで作業中のセッションは継続したまま、新規ウィンドウを開く：

cd ~/my-project
 
# 本番ブランチ(main)から修正ブランチ作成
git checkout main
git pull origin main
git checkout -b hotfix/login-timeout
 
# worktree作成
git worktree add hotfix-login-work hotfix/login-timeout
cd hotfix-login-work
 
# Claude Code起動
claude --worktree=. \
       --context="本番エラー修正：ユーザーログイン時のタイムアウト
       - エラーメッセージ：'Request timeout after 30s'
       - 再現条件：複数地域からの同時アクセス
       - 想定原因：auth APIのレート制限不足
       - タイムアウト値の増加と接続プール最適化を検討"

並行実行状態

# ターミナル1：feature開発 (既存)
cd feature-dashboard-work
# 継続中...
 
# ターミナル2：バグ修正 (新規)
cd hotfix-login-work
# 修正実施中...
 
# ターミナル3：別タスク管理
cd main-work
git log --oneline -10

各worktreeはGit的には独立しているため、一方のコミットが他方に影響しません。

マージとクリーンアップ

バグ修正が完了したら：

# hotfix ブランチをテスト
cd hotfix-login-work
npm test
npm run build
 
# main へマージ（通常はPR経由）
git push origin hotfix/login-timeout
 
# GitHub で PR review/approve/merge 後...
 
# worktree削除
cd ~/my-project
git worktree remove hotfix-login-work
 
# ローカルブランチも削除
git branch -d hotfix/login-timeout

Claude Code Agentとworktreeの連携

Claude Codeのエージェントモードと worktreeを組み合わせると、さらに強力な自動化が可能です。

エージェントモード有効化

cd feature-auth-work
 
# エージェントモード（完全自動実行）
claude --worktree=. \
       --agent \
       --context="認証機能の完全実装
 
       要件：
       - JWT ベースのトークン管理
       - リフレッシュトークンサポート
       - CSRF 対策
       - 監査ログ記録
 
       実装ステップ：
       1. ユーティリティ関数実装（src/utils/auth.ts）
       2. サーバーエンドポイント作成（src/api/auth/）
       3. クライアントコンポーネント実装（src/components/Auth/）
       4. E2E テスト追加
       5. ドキュメント生成"

エージェントモードでは、Claude Codeが以下を 自動判断・実行 します：

ファイル生成の必要性判定
既存コードとの競合チェック
テスト作成とテスト実行
Git コミットの判断（--agent時は自動commit）

複数エージェントの並列実行

# スクリプトで複数エージェント起動（非同期）
#!/bin/bash
 
# エージェント1：認証機能
(cd feature-auth-work && \
 claude --worktree=. --agent --context="OAuth実装") &
 
# エージェント2：UI コンポーネント
(cd feature-ui-work && \
 claude --worktree=. --agent --context="Form コンポーネント群実装") &
 
# エージェント3：ドキュメント
(cd docs-work && \
 claude --worktree=. --agent --context="API ドキュメント自動生成") &
 
# すべてのバックグラウンドタスク完了を待機
wait
 
echo "すべてのタスク完了"

よくあるエラーと対処法

エラー1：同じブランチを複数のworktreeに割り当て

$ git worktree add work2 main
fatal: 'main' is already checked out at '/path/to/work1'

原因: main ブランチが既に work1 にチェックアウト中

解決策:

# work2用に新規ブランチを作成
git worktree add work2 -b main-secondary main
# または既存の別ブランチを使用
git worktree add work2 develop

エラー2：worktree削除時にエラー

$ git worktree remove feature-work
fatal: '/path/to/feature-work' is not a working tree root

原因: ディレクトリパスが間違っているか、既に削除済み

解決策:

# 登録済みworktreeを確認
git worktree list
 
# 正確なパスで削除
git worktree remove /exact/path/to/feature-work
 
# 強制削除が必要な場合
git worktree remove --force feature-work

エラー3：worktree間でのマージコンフリクト

複数のworktreeで同じファイルを編集した場合：

$ git merge main
CONFLICT (content): Merge conflict in src/utils/api.ts

対処:

# コンフリクト箇所を確認
git diff src/utils/api.ts
 
# エディタで手動修正後
git add src/utils/api.ts
git commit -m "Merge main: resolve conflicts in api.ts"

エラー4：worktreeのディスク容量問題

大規模リポジトリで複数worktreeを作成すると、ディスク使用量が増加。

# worktree ごとのディスク使用量確認
du -sh ~/projects/my-project/*/
 
# 不要なworktreeを削除
git worktree prune  # 削除済みディレクトリの参照をクリア

応用：CI/CDとworktreeの統合

CI/CDパイプラインでworktreeを活用すると、複数のテストスイートを並列実行可能です。

GitHub Actions での例

name: Parallel Testing with Worktrees
 
on: [push, pull_request]
 
jobs:
  test-matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        test-suite: [unit, integration, e2e]
    steps:
      - uses: actions/checkout@v3
 
      - name: Create worktree for ${{ matrix.test-suite }}
        run: |
          git worktree add test-${{ matrix.test-suite }} ${{ github.ref }}
          cd test-${{ matrix.test-suite }}
 
      - name: Install dependencies
        run: |
          cd test-${{ matrix.test-suite }}
          npm install
 
      - name: Run ${{ matrix.test-suite }} tests
        run: |
          cd test-${{ matrix.test-suite }}
          npm run test:${{ matrix.test-suite }}

このワークフローにより、unit・integration・e2e テストが並列実行されます。

ここまでの要点

Git worktreeとClaude Codeの組み合わせは、並列開発の効率を飛躍的に向上させます。複数のタスクを同時進行させながら、コンテキストスイッチのオーバーヘッドを最小化できるのが最大の利点です。

初期設定にやや学習曲線がありますが、一度習得すると、チーム全体の開発速度が大幅に加速することを実感できるでしょう。特に、バグ修正と機能開発の並行実施が必要なプロジェクト、複数の開発者が同じリポジトリで作業するチームでは、worktree導入の投資対効果は高いです。

本記事で紹介したワークフローとコマンド集を参考に、ぜひプロジェクトに適用してみてください。

取り組みの背景：なぜ並列開発か

大規模プロジェクトの開発速度は、エージェントの処理能力ではなく、エージェントの同時実行数で決まります。従来の直列開発では、機能Aの実装が完了してから機能Bに移る一直線のパイプラインです。一方、並列開発はこの直線を複数の並行レーンに分割し、待ち時間を重ね合わせることで全体の所要時間を圧縮します。レーンを増やすほど効果は逓減するため、実際には扱える同時数の上限を見極めながら運用するのが現実的です。

Claude Codeは単なるコーディング支援ツールではなく、複数エージェント間の協調作業システムとして設計されています。ここではこの並列能力を最大限に活用するための完全なマニュアルを提供します。

第1部：ワークツリーの基礎から応用まで

1.1 ワークツリーとは何か

Gitのワークツリー機能は、1つのリポジトリに対して複数の作業ディレクトリを同時に維持できる仕組みです。従来のブランチ切り替え（git checkout）では、同じディレクトリ内でコンテキストが切り替わります。一方、ワークツリーは物理的に異なるディレクトリを作成し、各ディレクトリが独立した作業環境を持ちます。

# 親ワークツリー（メインチェックアウト）
/project/
├── .git/
├── src/
└── ...
 
# 子ワークツリー1
/project/wt-feature-auth/
├── src/
└── ...
 
# 子ワークツリー2
/project/wt-feature-payments/
├── src/
└── ...

各ワークツリーは異なるブランチをチェックアウト可能で、同時に異なるコードを編集できます。これが並列開発の基盤です。

1.2 Claude Codeでのワークツリー操作

Claude Codeで新しいワークツリーを作成するには、--worktree フラグを使用します：

claude-code create --project /path/to/repo --worktree feature/auth

このコマンドは以下の処理を実行します：

/path/to/repo/wt-feature-auth ディレクトリを作成
feature/auth ブランチを新規作成
新しいワークツリーをそのブランチにチェックアウト
.claude-code-context.md を新ワークツリーに生成

重要な設定ポイント：各ワークツリーは独立した CLAUDE.md スコープを持ちます。親ワークツリーで定義された開発指針は、子ワークツリーには適用されません。大規模プロジェクトでは、各ワークツリーのスコープファイルを慎重に管理することが、品質一貫性を保つカギです。

1.3 ワークツリーのライフサイクル管理

ワークツリーは作成から破棄まで、明確なライフサイクルを持ちます：

段階1：初期化（0〜5分）

ワークツリー作成
依存関係のインストール（npm install等）
ローカルテスト環境の構築

段階2：実装（5分〜数時間）

機能コードの記述
ユニットテストの実装
ローカルテストの実行

段階3：統合テスト（実装完了後）

親ブランチとのマージ衝突チェック
エンドツーエンドテスト実行
コード品質スキャン

段階4：クローズ（統合完了後）

プルリクエストのマージ
ワークツリーの削除
リモートブランチの削除

ワークツリーの削除は以下のコマンドで行います：

# ワークツリーの削除
git worktree remove wt-feature-auth
 
# ブランチの削除
git branch -d feature/auth
 
# リモートブランチの削除
git push origin --delete feature/auth

注意：削除時に --force フラグを使うと、保存されていない変更が失われます。必ず git worktree list で状態を確認してから削除してください。

第2部：サブエージェント・アーキテクチャ

2.1 Claude Codeのマルチエージェント設計

Claude Codeは最大7個の並列エージェントをスピンアップ（起動）できます。各エージェントは独立した実行スレッドを持ち、CPU/メモリリソースを共有しながらも、互いに異なるワークツリーで作業できます。

マルチエージェント構成の基本パターン：

親エージェント（調整役）
├─ 子エージェント1 → ワークツリー1 → 機能A（認証）
├─ 子エージェント2 → ワークツリー2 → 機能B（支払い）
├─ 子エージェント3 → ワークツリー3 → 機能C（通知）
├─ 子エージェント4 → ワークツリー4 → テスト・CI
├─ 子エージェント5 → ワークツリー5 → ドキュメント生成
├─ 子エージェント6 → ワークツリー6 → 品質チェック
└─ 子エージェント7 → ワークツリー7 → デプロイメント

2.2 サブエージェントの起動と管理

親エージェントから子エージェントを起動するには、Claude Codeの API を用いて spawn_agent を呼び出します：

// 親エージェント内のコード
const subAgent = await spawnAgent({
  projectPath: "/path/to/repo/wt-feature-auth",
  instructions: "認証モジュールのTypeScript実装を完成させてください...",
  maxIterations: 20,
  timeout: 3600, // 1時間
});
 
// 子エージェントの進捗を監視
const result = await subAgent.waitForCompletion();
if (result.success) {
  console.log("認証機能の実装が完了しました");
} else {
  console.log(`エラー: ${result.error}`);
}

重要な設計原則：

各子エージェントには単一の責務を与える（単一責任原則）
子エージェント間の依存関係は必ず事前に宣言する
タイムアウトはプロジェクトの複雑度に応じて設定する（通常は300〜3600秒）

2.3 エージェント間の通信パターン

複数エージェントが効率よく協調するには、明確な通信インターフェースが必要です。

パターン1：タスク待機モデル（最も一般的） 親エージェントは子エージェントのタスク完了を待ち、その成果を親エージェント内で集約します。依存関係が強い場合に適しています。

const auth = await spawnAgent({ ... }).waitForCompletion();
const payment = await spawnAgent({ ... }).waitForCompletion();
const notification = await spawnAgent({ ... }).waitForCompletion();
// 全て完了後に統合テストを実施

パターン2：ファイアアンドフォーゲット（非ブロッキング） 親エージェントが子エージェントを起動後、その完了を待たずに次の処理を続行します。依存関係が弱い場合に適しています。

const agents = [
  spawnAgent({ ... }), // 非ブロッキング
  spawnAgent({ ... }),
  spawnAgent({ ... }),
];
// 全エージェントの完了を並列待機
await Promise.all(agents.map(a => a.waitForCompletion()));

2.4 リソース制限と負荷分散

7個のエージェントを同時起動すると、システムリソース（CPU/メモリ）に圧力がかかります。Claude Codeは内部的に以下の負荷分散機構を備えています：

CPU スロットリング：各エージェントに最大25% CPUを割り当て
メモリプール：総メモリの75%を複数エージェント間で共有
I/Oスケジューリング：ディスク読み書きをキューで管理

実践的には、システムスペックに応じて実行エージェント数を制限することが推奨されます：

4コアPC：最大3〜4個のエージェント
8コアPC：最大5〜6個のエージェント
16コア以上：最大7個のエージェント

第3部：タスク管理システムの活用

3.1 CLAUDE_CODE_TASK_LIST_ID の仕組み

Claude Codeの全エージェントは、1つの統一されたタスクリストを共有します。このタスクリストのIDが CLAUDE_CODE_TASK_LIST_ID 環境変数で定義されます。

タスクリストの構造：

{
  "id": "task-abc123xyz",
  "project_path": "/path/to/repo",
  "tasks": [
    {
      "id": "t-auth-001",
      "title": "認証モジュールの型定義作成",
      "status": "in_progress",
      "assignee": "agent-1",
      "priority": 1,
      "due_date": "2026-03-30T20:00Z",
      "dependencies": []
    },
    {
      "id": "t-payment-001",
      "title": "決済フローのテスト実装",
      "status": "pending",
      "assignee": null,
      "priority": 2,
      "due_date": "2026-03-30T21:00Z",
      "dependencies": ["t-auth-001"]
    }
  ],
  "last_updated": "2026-03-30T19:45Z"
}

タスクリストは各エージェントによってリアルタイムに更新されます。親エージェントはこのリストを定期的にポーリングして、全体の進捗状況を把握します。

3.2 進捗同期の実装パターン

効率的な並列開発には、進捗状況のリアルタイム同期が不可欠です。以下は実装の標準パターンです：

// 親エージェント内：タスクリスト初期化
const taskList = {
  id: process.env.CLAUDE_CODE_TASK_LIST_ID,
  tasks: [
    { id: "t1", title: "Auth", status: "pending", dependencies: [] },
    { id: "t2", title: "Payment", status: "pending", dependencies: ["t1"] },
    { id: "t3", title: "Notification", status: "pending", dependencies: ["t1", "t2"] },
  ]
};
 
// 子エージェント1：タスク実行
async function executeTask(taskId) {
  await updateTaskStatus(taskId, "in_progress");
  try {
    // 実装処理...
    await updateTaskStatus(taskId, "completed");
  } catch (error) {
    await updateTaskStatus(taskId, "failed", error.message);
    // リトライロジック...
  }
}
 
// 親エージェント：進捗監視
async function monitorProgress() {
  const interval = setInterval(() => {
    const completed = taskList.tasks.filter(t => t.status === "completed").length;
    const total = taskList.tasks.length;
    console.log(`進捗: ${completed}/${total}`);
  }, 5000);
}

3.3 依存関係の制御と順序付け

複数タスクの実行順序は、依存関係グラフによって制御されます。タスクBがタスクAに依存している場合、Bは必ずAの完了後に開始されます。

依存関係グラフの作成例：

認証モジュル (t-auth)
├─ 決済モジュル (t-payment)
│  └─ 通知モジュル (t-notification)
└─ ユーザープロフィール (t-profile)
   └─ 通知モジュル (t-notification)

→ 実行順序: t-auth → [t-payment, t-profile] → t-notification

依存関係を明示的に定義することで、Claude Codeは自動的に最適な実行順序を計算します。これにより、エージェント数が少ないプロジェクトでも、タスクの並列度を最大化できます。

第4部：実装パターンと運用テクニック

4.1 ファンアウト・アグリゲーションパターン

大規模プロジェクトで最も効果的な並列パターンは、ファンアウト・アグリゲーションです。

フロー：

親エージェントが複数の独立したタスクを子エージェントに配分（ファンアウト）
各子エージェントが独立して処理を進行
全子エージェントの結果を親エージェントで収集・統合（アグリゲーション）

// 実装例：複数モジュールの同時開発
async function fanOutAggregation() {
  const features = [
    { name: "auth", branch: "feature/auth" },
    { name: "payment", branch: "feature/payment" },
    { name: "notification", branch: "feature/notification" },
  ];
 
  // ファンアウト：全モジュールを同時起動
  const agents = features.map(f =>
    spawnAgent({
      worktree: f.branch,
      task: `${f.name}モジュールの実装を完成させてください`,
    })
  );
 
  // アグリゲーション：全結果を待機
  const results = await Promise.all(
    agents.map(a => a.waitForCompletion())
  );
 
  // 統合処理
  for (const result of results) {
    if (!result.success) {
      console.error(`${result.feature}が失敗しました`);
      // リカバリーロジック...
    }
  }
 
  return results;
}

4.2 パイプラインパターン

依存関係が強い場合は、パイプラインパターンが効果的です。前のステージの出力が次のステージの入力になります。

ステージ1: コード生成
  ↓
ステージ2: ユニットテスト
  ↓
ステージ3: 統合テスト
  ↓
ステージ4: デプロイメント

各ステージの実装：

async function pipelineExecution() {
  // ステージ1
  const codeGenResult = await spawnAgent({
    task: "APIエンドポイントのスケルトンコード生成"
  }).waitForCompletion();
 
  // ステージ2
  const unitTestResult = await spawnAgent({
    task: "生成されたコードのユニットテスト作成",
    context: codeGenResult,
  }).waitForCompletion();
 
  // ステージ3
  const integrationResult = await spawnAgent({
    task: "既存モジュールとの統合テスト",
    context: unitTestResult,
  }).waitForCompletion();
 
  // ステージ4
  const deployResult = await spawnAgent({
    task: "ステージング環境へのデプロイ",
    context: integrationResult,
  }).waitForCompletion();
 
  return deployResult;
}

4.3 階層的委譲パターン

超大規模プロジェクトでは、親エージェントが直接全タスクを管理するのではなく、階層的に委譲します。

レベル1: プロジェクト親エージェント
├─ レベル2: バックエンド親エージェント
│  ├─ レベル3: 認証チーム子エージェント
│  ├─ レベル3: 決済チーム子エージェント
│  └─ レベル3: 通知チーム子エージェント
└─ レベル2: フロントエンド親エージェント
   ├─ レベル3: UIコンポーネント子エージェント
   └─ レベル3: ページ統合子エージェント

この構造により、各層で適切なスコープと責務を持つエージェントが動作します。

4.4 本番運用ワークフロー：実例

実際のプロジェクト（例：ECサイトのリファクタリング）での並列開発フロー：

Day 1 朝：計画フェーズ

親エージェント：プロジェクト全体の分析と分割
既存コードの複雑度測定、依存関係マッピング
7つのサブタスクに分割

Day 1 午前中：実装フェーズ

子エージェント1 → ワークツリー1 → データベーススキーマ更新
子エージェント2 → ワークツリー2 → APIレイヤーのリファクタリング
子エージェント3 → ワークツリー3 → 認証ロジック最適化
子エージェント4 → ワークツリー4 → ユニットテスト拡充
子エージェント5 → ワークツリー5 → 型定義の厳格化
子エージェント6 → ワークツリー6 → ドキュメント更新
子エージェント7 → ワークツリー7 → CI/CDパイプライン調整

各エージェントは独立して進行。タスク管理システムが依存関係を自動管理。

Day 1 午後：統合テストフェーズ

全サブタスク完了後、親エージェントが統合テストを実行
マージ衝突の自動解決
エンドツーエンドテストの実行

Day 1 夜：QAフェーズ

追加テストが必要な箇所を特定
修正が必要な場合は、該当ワークツリーで追加実装
最終コード品質チェック

Day 2 朝：デプロイ

メインブランチへのマージ
ステージング環境への自動デプロイ
本番環境への昇格（必要に応じて）

第5部：高度なテクニックと最適化

5.1 CLAUDE.md のスコープ管理

大規模な並列開発では、各ワークツリーが異なる開発指針を必要とする場合があります。親ワークツリーの CLAUDE.md は全子ワークツリーに継承されますが、ワークツリー固有のスコープを定義することで、より正確な指示が可能になります。

# ワークツリー固有のCLAUDE.mdの例
/project/wt-feature-auth/CLAUDE.md
 
---
# 認証モジュール開発スコープ
 
## 納期
 
- 2026-03-30 20:00 JST

5.2 Ctrl+T によるリアルタイム監視

Claude Codeは Ctrl+T キーボードショートカットで、全エージェント・全ワークツリーのリアルタイムダッシュボードを表示します。

表示内容：

各ワークツリーのブランチ名
各エージェントの状態（実行中/待機中/完了）
タスク進捗バー（完了タスク数/総タスク数）
エージェントごとのエラーログ
リソース使用率（CPU/メモリ）

このダッシュボードは並列開発の生命線です。問題が発生した場合、即座に対応できます。

5.3 エラーリカバリーと再試行戦略

並列開発では、1つのエージェントの失敗が全体を止めてはいけません。堅牢なリカバリー機構が必要です。

// リトライ付きエージェント実行
async function executeWithRetry(task, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const result = await spawnAgent({
        task: task.description,
        worktree: task.worktree,
      }).waitForCompletion();
 
      if (result.success) {
        return result;
      }
    } catch (error) {
      console.log(`試行 ${attempt}/${maxRetries} 失敗: ${error}`);
 
      if (attempt < maxRetries) {
        // 指数バックオフ
        await sleep(Math.pow(2, attempt) * 1000);
      }
    }
  }
 
  // 全リトライ失敗時の処理
  throw new Error(`タスク失敗: ${task.description}`);
}

5.4 パフォーマンス最適化のチューニング

並列開発の速度を最大化するには、以下のチューニングが効果的です：

チューニング1：ワークツリー数の最適化

少なすぎる：並列度が低く、全体処理時間が長くなる
多すぎる：リソース競合により、各エージェントが遅くなる
最適値：システムコア数の70〜80%

チューニング2：タスク粒度の調整

粒度が大きい：並列度が下がるが、オーバーヘッドが少ない
粒度が小さい：並列度が上がるが、タスク管理のオーバーヘッドが増加
推奨：1タスクあたり 10〜30分の処理時間

チューニング3：依存関係の最小化

依存関係が多いと、待機時間が増加する
可能な限り独立したタスクに分割する

第6部：トラブルシューティング

6.1 よくある問題と対処法

問題1：エージェント間でのマージ衝突

複数エージェントが同じファイルを編集すると、衝突が発生します。対策：

ファイルの所有権を明確に定義（各エージェントが異なるファイルを担当）
衝突が予測される箇所は、親エージェントで事前に整理

問題2：デッドロック（相互依存）

タスクAがタスクBに依存し、同時にタスクBがタスクAに依存する場合、無限待機が発生します。対策：

依存関係グラフを事前に検証
循環依存を検出する自動ツールを導入

問題3：リソース枯渇

7つのエージェントを同時起動すると、メモリが枯渇する場合があります。対策：

同時実行エージェント数を減らす
大規模なワークツリー（容量が大きい）は別時間帯に処理

問題4：ワークツリーのゴースト化

削除に失敗したワークツリーが残存し、ディスク容量を圧迫します。対策：

# 残存ワークツリーの確認
git worktree list
 
# 強制削除
git worktree remove --force wt-orphaned

6.2 ログ分析とデバッグ

各ワークツリーのログは以下の場所に保存されます：

/project/wt-feature-auth/.claude-code-logs/
├── 2026-03-30_19-30.log    # 実行ログ
├── 2026-03-30_19-35.log
└── 2026-03-30_19-40.log

特定のエージェントで問題が発生した場合：

# ログの確認
tail -f /project/wt-feature-auth/.claude-code-logs/*.log
 
# エラーのグレップ
grep -i error /project/wt-feature-auth/.claude-code-logs/*.log

ここまでの要点と運用への落とし込み

ワークツリー、サブエージェント、タスク管理システムの3つの要素を組み合わせることで、Claude Code を使った並行作業はぐっと扱いやすくなります。

重要なポイント：

ワークツリーは物理的な作業スペース。各ワークツリーは独立した環境を保つ
サブエージェントは実行並列性。並行実行で待ち時間を重ね合わせ、体感のスループットを底上げ
タスク管理は進捗の同期。依存関係を自動制御し、デッドロックを回避

これらが噛み合うと、割り込みの多いプロジェクトでも手戻りが目に見えて減ります。まずは worktree をひとつ追加し、普段の改修を別ディレクトリで走らせるところから試してみてください。お読みいただきありがとうございました。

お読みいただきありがとうございます

Claude Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

✦コピー&ペーストで使える実装コード付き
✦毎日新しい上級ガイドを追加
✦¥580/月または ¥1,480 の永久アクセス

メンバーシップを見る →

⟐ Claude Code2026-03-25

Claude Code Worktree — 並列開発で生産性を最大化する

Claude Code の --worktree フラッグを使った並列開発テクニック。複数ブランチを同時に進行させ、開発効率を大幅に向上させる方法。

⟐ Claude Code2026-07-19

コミット済みのシンボリックリンクが worktree の外を指す — AI に並列作業を預ける前のリポジトリ点検

Claude Code 2.1.212 で、コミット済みのシンボリックリンクを worktree 作成時に辿ってリポジトリ外へ書きうる不具合が修正されました。パッチが塞いだのは辿りの側です。危険なリンクがコミットされている側を点検する監査スクリプトと、隔離の手順をまとめました。

⟐ Claude Code2026-06-24

Claude Design と Claude Code を行き来して作る — 発散と収束を分担する開発の流れ

デザインの大枠は Claude Design で、細部の作り込みは Claude Code で。デスクトップアプリへ統合されて往復しやすくなった2つを、発散と収束で役割分担する開発の進め方として整理します。Link Local code と Send to の橋渡しまで。

📚RECOMMENDED BOOKS

LLM開発

Claude CodeによるAI駆動開発入門

平川知秀

AI駆動開発

※ アフィリエイトリンクを含みます