Claude Code 実践マスター — Hooks・Orchestration・並列エージェント運用の極意

Claude Code の上級段階では、ライフサイクルイベント（Hooks）と複数エージェント協調（Orchestration）が中核になります。このレベルに到達すると、プロジェクト全体の自動化と品質管理が飛躍的に向上します。ここでは21種類の Hooks イベント、4種類のハンドラ、そして DevMoses 氏が実証した 198 エージェント並列運用の実践知を体系化します。

Hooks の全体像 — 21 種類のライフサイクルイベント

Hooks は .claude/settings.json で定義する自動ハンドラです。特定のイベント（コマンド実行、ファイル変更、プロンプト受信など）をトリガーに、自動的に処理を実行します。

全 21 イベントの分類

イベント種別	イベント名	説明
コマンド系（4個）	onCommandStart	コマンド実行開始時
	onCommandEnd	コマンド実行終了時
	onCommandError	コマンド実行エラー時
	onCommandResult	コマンド実行結果返却時
ファイル系（6個）	onFileCreate	ファイル作成時
	onFileChange	ファイル変更時
	onFileDelete	ファイル削除時
	onFileRename	ファイル名変更時
	onFileLintError	リント警告・エラー時
	onFileValidationError	バリデーション失敗時
プロンプト系（3個）	onPromptReceived	プロンプト入力受信時
	onPromptProcessed	プロンプト処理完了時
	onPromptError	プロンプト処理エラー時
エージェント系（4個）	onAgentStart	エージェント起動時
	onAgentEnd	エージェント終了時
	onAgentError	エージェント内エラー時
	onAgentStateChange	エージェント状態変更時
その他（4個）	onScheduleExecution	スケジュール実行時
	onWebhookReceived	Webhook 受信時
	onConfigChange	設定変更時
	onHeartbeat	定期ハートビート時

4 種類のハンドラと実装パターン

Hooks の実装は 4 種類のハンドラで構成されます。それぞれの特性を理解することが設計の鍵です。

1. Command ハンドラ — 既存スキル呼び出し

.claude/skills/ に定義されたスキルを直接呼び出します。トークン消費ゼロで軽量です。

{
  "hooks": {
    "onCommandStart": {
      "type": "command",
      "command": "validate-inputs",
      "timeout": 5000
    }
  }
}

用途:

入力形式の事前検証
コマンド実行前のチェック
ファイル整形

2. HTTP ハンドラ — 外部サービス連携

HTTP POST/GET リクエストを送信し、外部サービス（Slack、Discord、HubSpot、Webhook等）と連携します。

{
  "hooks": {
    "onFileChange": {
      "type": "http",
      "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
      "method": "POST",
      "headers": {
        "Content-Type": "application/json"
      },
      "body": {
        "text": "File {{file}} changed in {{project}}"
      }
    }
  }
}

用途:

Slack 通知
GitHub Actions トリガー
外部 API 呼び出し

3. Prompt ハンドラ — 入力前処理

ユーザーが入力したプロンプトを加工・検証します。危険な操作をブロックしたり、テンプレートに拡張したりできます。

{
  "hooks": {
    "onPromptReceived": {
      "type": "prompt",
      "rules": [
        {
          "pattern": "^delete.*database",
          "action": "block",
          "message": "DB削除操作は明示的な承認が必要です"
        },
        {
          "pattern": "^deploy",
          "action": "prepend",
          "text": "本番環境へのデプロイ前に必ず staging で検証してください。"
        }
      ]
    }
  }
}

用途:

危険なコマンドのブロック
プロンプト自動拡張
入力フォーマット統一

4. Agent ハンドラ — マルチエージェント制御

別のエージェント（Subagent）を起動し、複雑なタスクを分散処理します。

{
  "hooks": {
    "onCommandError": {
      "type": "agent",
      "agent": "error-analyzer",
      "context": "{{error}}",
      "timeout": 30000
    }
  }
}

用途:

エラーの自動分析
フォールバック処理
タスク分散

Hooks 設定の完全実例

実際のプロジェクトで使える、段階的な Hooks 設定例を示します。

Level 1: 基本検証と通知

{
  "hooks": {
    "onCommandStart": {
      "type": "command",
      "command": "validate-syntax"
    },
    "onFileChange": {
      "type": "http",
      "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
      "method": "POST",
      "body": {
        "text": "✅ {{file}} updated"
      }
    }
  }
}

Level 2: 危険操作ブロック + 自動リント

{
  "hooks": {
    "onPromptReceived": {
      "type": "prompt",
      "rules": [
        {
          "pattern": "^drop table|^delete from",
          "action": "block",
          "message": "危険：DB削除操作です。ダブルチェックが必要"
        }
      ]
    },
    "onFileChange": {
      "type": "command",
      "command": "run-eslint"
    }
  }
}

Level 3: エラー自動分析 + デプロイ前チェック

{
  "hooks": {
    "onCommandError": {
      "type": "agent",
      "agent": "error-analyzer",
      "timeout": 15000
    },
    "onPromptReceived": {
      "type": "prompt",
      "rules": [
        {
          "pattern": "^deploy.*production",
          "action": "prepend",
          "text": "本番デプロイ前チェックリスト:\n1. staging で検証したか?\n2. マイグレーション計画はあるか?\n3. ロールバック手順は用意したか?"
        }
      ]
    }
  }
}

Orchestration — 複数エージェント協調運用

単一のエージェントに全てを任せるのではなく、複数のエージェントを役割分担させることで、複雑なプロジェクトを高速に処理できます。

Subagents パターン — 役割別分散

Subagents は 3 種類に分類されます。

Explore Agent — 調査・探索役

新しいコードベースに入ったとき、全体構造を把握するのが役割です。

---
name: "Explore"
description: "プロジェクト構造を分析し、ファイルマップを作成"
---
 
タスク:
1. package.json から依存関係を抽出
2. src/ フォルダの構造を可視化
3. README.md から主要な設計方針を抽出
4. 重要ファイル（config, schema, 基盤）の位置を特定

実行タイミング:

新規プロジェクト開始時
月に一度の定期更新
大規模リファクタ前

Plan Agent — 計画・設計役

実装方針を立案し、工程表を作成します。Explore エージェントの調査結果を受け取ります。

---
name: "Plan"
description: "実装計画を策定し、Explore 結果をもとにマイルストーンを作成"
---
 
入力: Explore エージェント の調査結果
 
タスク:
1. 要件を 3 段階のマイルストーンに分割
2. 各段階の依存関係を図示
3. リスク要因を列挙
4. エスティメーション（段階別・人日）を提示

実行タイミング:

新機能開発の着手時
デプロイ計画作成前

General-purpose Agent — 実装役

具体的なコード生成・修正を行います。Explore と Plan の結果をコンテキストとして受け取ります。

$ !orchestrate-general-purpose \
  --explore-result="explore_output.json" \
  --plan-result="plan_output.json" \
  --task="Auth component implementation"

Agent Teams — 独立コンテキストでの協調

複数のエージェントが並列に独立したコンテキストで動作し、最後に結果を統合します。

{
  "teams": {
    "backend_team": {
      "agents": ["api-design", "database-schema", "auth-service"],
      "context": "shared-project-state",
      "sync_interval": "5m"
    },
    "frontend_team": {
      "agents": ["ui-components", "state-management", "styling"],
      "context": "shared-project-state",
      "sync_interval": "5m"
    }
  },
  "integration": {
    "point": "weekly-review",
    "conflicts": "manual-review"
  }
}

特徴:

各チームが独立して進行
共有状態（shared-project-state）で同期
矛盾は週 1 回の統合レビューで解決

/batch スキル — 大規模変更の並列処理

100+ ファイルに及ぶ一括変更（例: API バージョンアップ、モジュール名変更）を並列処理します。

---
name: "Migrate to TypeScript Strict Mode"
description: "プロジェクト全体を strict mode に移行（500ファイル対象）"
---
 
ステップ 1: ファイル一覧の生成
find src/ -name "*.ts" -o -name "*.tsx" | sort > files.txt
 
ステップ 2: ファイルを 50 個単位で分割
split -l 50 files.txt batch_
 
ステップ 3: 各バッチを並列エージェントに割り当て
for batch in batch_*; do
  /batch --files="$(cat $batch)" --task="convert-to-strict-mode" &
done
 
ステップ 4: 統合と検証
npm run type-check
npm run test

実行例:

$ !batch \
  --task="migrate-api-v1-to-v2" \
  --file-pattern="src/api/**/*.ts" \
  --parallelism=10 \
  --rollback-on-error

実践パターン — 本番で使える設定例

パターン A: スタートアップ / 小規模チーム

{
  "hooks": {
    "onPromptReceived": {
      "type": "prompt",
      "rules": [
        {
          "pattern": "^deploy.*production",
          "action": "block",
          "message": "本番デプロイは週 1 回（金曜 16:00）に限定。PM に相談してください"
        }
      ]
    },
    "onFileChange": {
      "type": "command",
      "command": "run-unit-tests"
    }
  }
}

パターン B: 成長段階 / 中規模チーム

{
  "hooks": {
    "onCommandError": {
      "type": "agent",
      "agent": "error-analyzer"
    },
    "onFileChange": {
      "type": "http",
      "url": "https://api.github.com/repos/YOUR/REPO/check-runs",
      "body": {
        "name": "eslint-check",
        "status": "in_progress"
      }
    }
  },
  "orchestration": {
    "default_strategy": "subagents",
    "subagents": ["explore", "plan", "implement"]
  }
}

パターン C: エンタープライズ / 大規模チーム

{
  "hooks": {
    "onPromptReceived": {
      "type": "prompt",
      "rules": [
        {
          "pattern": "^deploy",
          "action": "prepend",
          "text": "デプロイメント前チェック:\n□ JIRA チケット番号を記載\n□ 関連チーム（DevOps, QA, PM）に通知\n□ staging で 24 時間監視"
        }
      ]
    },
    "onCommandError": {
      "type": "agent",
      "agent": "error-analyzer"
    }
  },
  "orchestration": {
    "teams": {
      "backend": ["api", "database", "auth", "payment"],
      "frontend": ["ui", "state", "analytics"],
      "devops": ["ci-cd", "monitoring", "security"]
    },
    "sync_strategy": "real-time"
  }
}

DevMoses の 198 エージェント並列運用に学ぶ

DevMoses は、複雑な機械学習パイプラインを 198 個のエージェントで並列処理し、手作業の 100 倍以上の速度で完了させました。その成功要因は:

明確な役割分担 — 各エージェントが単一責任を担当
非同期進行 — エージェント同士が待機せず、独立して作業
定期同期 — 5 分ごとに進捗状況と矛盾を確認・解決
フェイルセーフ — 1 個のエージェントの失敗が全体に波及しない設計
出力の統合 — 最終段階で全エージェント結果をマージ

この設計原則を小規模プロジェクトに応用すれば、3〜5 個のエージェントで十分に大きな生産性向上が得られます。

全体を振り返って

Hooks と Orchestration は、Claude Code を「自動化された開発チーム」へ進化させます。21 種類のイベント、4 種類のハンドラ、複数エージェント協調を組み合わせることで、プロジェクト全体の品質と生産性が飛躍的に向上します。

小規模から始めて、必要に応じてスケールアップしていく姿勢が大切です。まずは onCommandStart の入力検証から、次に onFileChange での自動テスト実行、最後に Subagents で役割分担—こうして段階的に高度な自動化を実現していきます。

Claude Code 実践マスター — Hooks・Orchestration・並列エージェント運用の極意

Hooks の全体像 — 21 種類のライフサイクルイベント

全 21 イベントの分類

4 種類のハンドラと実装パターン

1. Command ハンドラ — 既存スキル呼び出し

2. HTTP ハンドラ — 外部サービス連携

3. Prompt ハンドラ — 入力前処理

4. Agent ハンドラ — マルチエージェント制御

Hooks 設定の完全実例

Level 1: 基本検証と通知

Level 2: 危険操作ブロック + 自動リント

Level 3: エラー自動分析 + デプロイ前チェック

Orchestration — 複数エージェント協調運用

Subagents パターン — 役割別分散

Explore Agent — 調査・探索役

Plan Agent — 計画・設計役

General-purpose Agent — 実装役

Agent Teams — 独立コンテキストでの協調

/batch スキル — 大規模変更の並列処理

実践パターン — 本番で使える設定例

パターン A: スタートアップ / 小規模チーム

パターン B: 成長段階 / 中規模チーム

パターン C: エンタープライズ / 大規模チーム

DevMoses の 198 エージェント並列運用に学ぶ

全体を振り返って

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

関連記事