Claude Code Task tool 並列実行とエラーハンドリング実装パターン

この記事の対象者

• Claude Code基本操作を理解している中級開発者
• Task toolを使ったサブエージェント活用を効率化したいチーム

この記事のポイント

1. 4つの最適化レバーを使い分けて Task tool のパフォーマンスを改善
2. 権限制御とHooksによるサブエージェントのガバナンス確立
3. OpenTelemetry ベースの計測で効果を定量的に把握

なぜこの問題が今重要か

Claude Code Task tool を使った自動化では、サブエージェントの使い方次第でパフォーマンスが大きく変わる。しかし「速い・遅い」といった感覚的な判断ではなく、構造的なアプローチで最適化し、計測で効果を検証することが重要である。

本記事では、公式ドキュメントに基づく 4つの最適化レバー を体系的に解説する。

4つの最適化レバー概要

レバー	内容	主な効果
(1) タスク分割と並列化	適切なサブエージェントタイプの選択と並列実行	処理時間の短縮
(2) 権限制御	permissions.deny によるサブエージェント制御	セキュリティ・安定性向上
(3) Hooks によるゲート制御	SubagentStart / SubagentStop イベント活用	可観測性・制御性向上
(4) イベント分析による計測	OpenTelemetry メトリクスの活用	定量的な効果検証

---

レバー1: タスク分割と並列化

サブエージェントタイプの選択

Claude Code は用途別に最適化された4種類のサブエージェントを提供する。タスクに適したタイプを選ぶことが最適化の第一歩となる。

タイプ	モデル	ツールアクセス	用途
Explore	Haiku（高速・軽量）	読み取り専用	ファイル探索・コード検索
Plan	親モデルを継承	読み取り専用	設計・計画策定
general-purpose	親モデルを継承	全ツール利用可能	複雑なタスクの実行
Bash	別コンテキスト	コマンド実行	シェルコマンド実行

Explore を積極的に活用する

Explore は Haiku モデルを使用するため高速かつ低コストで動作する。コードベースの調査やファイル検索は、まず Explore で実行し、その結果を基に general-purpose で処理するパターンが効率的。

自動コンパクション

サブエージェントはコンテキスト容量の約 95% に達すると自動的にコンパクション（要約圧縮）を実行する。この閾値は環境変数で調整できる。

# コンパクション閾値を変更する場合（デフォルト: 95）
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80

アーキテクチャ上の制約

サブエージェントが別のサブエージェントを起動することはできない。これはアーキテクチャ上の制約であり、再帰的なエージェント起動によるリソース消費を防ぐ設計となっている。

CLAUDE.md でのタスク分割指示

Task tool の並列実行は、CLAUDE.md やプロンプトで指示することで実現する。Python の疑似コードではなく、実際の Claude Code の使い方に沿った指示例を示す。

CLAUDE.md に記述する並列実行指示の例:

## Task tool 利用方針

### 並列実行パターン
複数の独立したタスクがある場合、Task tool で並列にサブエージェントを起動すること。

#### コードベース調査の並列化
- Explore サブエージェントを使って、複数ディレクトリを同時に調査する
- 例: フロントエンドとバックエンドの関連コードを同時に探索

#### 調査→計画→実行の段階的パイプライン
1. まず Explore でコードベースを調査
2. 調査結果を基に Plan で実装計画を策定
3. 計画に沿って general-purpose で実装を実行

プロンプトでの並列実行指示例:

以下の3つのタスクを Task tool で並列実行してください：

1. Explore: src/api/ 配下のエンドポイント一覧を収集
2. Explore: tests/ 配下のテストカバレッジ状況を調査
3. Plan: 上記の調査結果を基にリファクタリング計画を策定

1と2は並列実行し、3は1と2の完了後に実行してください。

---

レバー2: 権限制御

サブエージェントの制限

.claude/settings.json の permissions.deny を使って、特定のサブエージェントの使用を制限できる。

特定サブエージェントの無効化:

{
  "permissions": {
    "deny": [
      "Task(general-purpose)"
    ]
  }
}

上記の設定により、general-purpose サブエージェントの起動がブロックされる。Explore や Plan など軽量なサブエージェントのみに制限したい場合に有効。

全サブエージェントの起動を禁止:

CLI オプション --disallowedTools を使用して、Task tool 自体を無効化できる。

claude --disallowedTools Task

バックグラウンドサブエージェントの権限

バックグラウンドで動作するサブエージェントは、事前に承認されていない権限を自動的に拒否する。チーム運用では、明示的に allow リストで許可するツールを指定することが推奨される。

チーム向けの安全なデフォルト設定

チームで Claude Code を運用する場合、以下のような設定をプロジェクトの .claude/settings.json に配置する。

{
  "permissions": {
    "deny": [
      "Task(general-purpose)",
      "Bash(rm *)",
      "Bash(git push --force)"
    ],
    "allow": [
      "Task(Explore)",
      "Task(Plan)",
      "Bash(npm test)",
      "Bash(npm run build)"
    ]
  }
}

この設定のポイント：

• deny: general-purpose サブエージェント（全ツールアクセス可能）と破壊的コマンドをブロック
• allow: 読み取り専用の Explore / Plan と、安全なビルド・テストコマンドを明示的に許可

---

レバー3: Hooks によるゲート制御

SubagentStart / SubagentStop イベント

Claude Code の Hooks 機能を使い、サブエージェントの起動・終了時にカスタムコマンドを実行できる。これにより、サブエージェントの動作をログに記録したり、条件付きでゲート制御を行うことが可能。

.claude/settings.json に以下のように設定する：

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Subagent started at $(date)\" >> /tmp/subagent-log.txt"
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Subagent completed: $(cat /dev/stdin | jq -r '.agent_name')\" >> /tmp/subagent-log.txt"
          }
        ]
      }
    ]
  }
}

活用パターン

パターン	説明
ログ収集	サブエージェントの開始・終了をファイルやログ管理ツールに記録
実行時間計測	SubagentStart と SubagentStop のタイムスタンプ差分で実行時間を算出
通知連携	長時間サブエージェントの完了を Slack 等に通知
条件付きブロック	SubagentStart で特定条件下のサブエージェント起動を阻止

---

レバー4: イベント分析による計測

OpenTelemetry によるメトリクス収集

「速い・遅い」の主観的判断ではなく、テレメトリデータによる定量的な計測を行う。

テレメトリの有効化:

export CLAUDE_CODE_ENABLE_TELEMETRY=1

主要メトリクス

メトリクス名	説明
claude_code.active_time.total	アクティブな処理時間の合計
claude_code.token.usage	トークン使用量
claude_code.tool_result	ツール実行結果（duration_ms 付き）

tool_result イベントには、各ツール呼び出しの成功率と実行時間（duration_ms）が含まれる。これにより、どのサブエージェントタイプがボトルネックになっているかを特定できる。

メトリクスのエクスポート

Prometheus や OTLP コレクターにメトリクスをエクスポートする場合：

# Prometheus 形式でエクスポート
export OTEL_METRICS_EXPORTER=prometheus

# OTLP エンドポイントへエクスポート
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

計測に基づく改善サイクル

1. テレメトリを有効化してベースラインを計測
2. レバー1〜3の最適化を適用
3. 同じメトリクスで改善効果を検証
4. ボトルネックが残る箇所に追加の最適化を適用

---

よくある落とし穴と対処

症状	原因	対処
サブエージェントの応答が遅い	general-purpose を多用している	Explore / Plan で代替可能なタスクを分離
コンテキスト超過エラー	サブエージェントに過大なタスクを渡している	タスクを細分化し、CLAUDE_AUTOCOMPACT_PCT_OVERRIDE を調整
権限エラーで停止	バックグラウンド実行時の自動拒否	permissions.allow で必要なツールを明示的に許可
効果が実感できない	感覚的な評価に依存	OpenTelemetry メトリクスで定量計測

詳細設定（高度な最適化）

## 環境変数リファレンス | 環境変数 | 説明 | デフォルト | |----------|------|-----------| | `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 自動コンパクション閾値（%） | 95 | | `CLAUDE_CODE_ENABLE_TELEMETRY` | テレメトリ有効化 | 0（無効） | | `OTEL_METRICS_EXPORTER` | メトリクスエクスポーター | なし | | `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP エンドポイントURL | なし | ## CLAUDE.md でのタスク分割テンプレート

## タスク実行ルール

### 調査フェーズ
- Explore サブエージェントを使用すること
- 複数ディレクトリの調査は並列で実行すること

### 実装フェーズ
- Plan で実装計画を策定してから general-purpose で実行
- テストは Bash サブエージェントで実行すること

### 禁止事項
- general-purpose でのファイル探索（Explore を使うこと）
- 単一サブエージェントへの過大なタスク投入

次に読む（関連記事）

• Claude Code Subagent完全ガイド
• AI Agent本番環境デプロイメントガイド