オーケストレーション実践

サブエージェントとエージェントチームを組み合わせて、実際のプロジェクト開発で活用する方法 を学びます。

オーケストレーションとは

オーケストレーションとは、複数のエージェントを 適切に組み合わせて協調させる ことです。オーケストラの指揮者のように、各エージェントの役割とタイミングを管理します。

オーケストレーション:
  Phase 1: Plan エージェントが設計（分析フェーズ）
  Phase 2: チームメイトが並列実装（実装フェーズ）
  Phase 3: レビューエージェントが品質確認（検証フェーズ）
  Phase 4: リーダーが統合・最終確認（統合フェーズ）

サブエージェントとチームの組み合わせ

サブエージェント（階層型）とエージェントチーム（協調型）は、状況に応じて使い分けます。オーケストレーションでは、両方を組み合わせて最大の効果を発揮します。

実践例 1: マルチエージェントコードレビュー

複数のエージェントが異なる観点からコードレビューを行い、総合的な品質を確保します。

構成

レビューリーダー（メイン Claude）
  ├── セキュリティレビューエージェント
  ├── パフォーマンスレビューエージェント
  ├── アーキテクチャレビューエージェント
  └── テストカバレッジチェックエージェント

セットアップ

.claude/agents/security-reviewer.md:

---
name: security-reviewer
description: セキュリティ観点のコードレビュー
tools:
  - Read
  - Glob
  - Grep
---

あなたはセキュリティ専門のコードレビュアーです。

## チェック項目
- SQL インジェクション
- XSS（クロスサイトスクリプティング）
- CSRF（クロスサイトリクエストフォージェリ）
- 認証・認可の不備
- 機密情報の露出
- 依存パッケージの脆弱性

## 出力形式
- 重要度: 高/中/低
- ファイル名と行番号
- 問題の説明
- 修正案

.claude/agents/perf-reviewer.md:

---
name: perf-reviewer
description: パフォーマンス観点のコードレビュー
tools:
  - Read
  - Glob
  - Grep
---

あなたはパフォーマンス専門のコードレビュアーです。

## チェック項目
- N+1 問題
- 不要な再レンダリング
- メモリリーク
- 重い計算処理
- キャッシュの未活用

実行方法

> PR #42 を以下の観点から総合レビューしてください:
  - /agents:security-reviewer にセキュリティレビューを依頼
  - /agents:perf-reviewer にパフォーマンスレビューを依頼
  - 結果を統合してレビューレポートを作成してください

レビューの品質向上

複数の専門エージェントを使うことで、1 つの Claude では見落としがちな問題も発見できます。各エージェントが専門領域に集中するため、より深い分析が可能です。

実践例 2: 並列デバッグ

複数のバグを同時に調査・修正する実践例です。

シナリオ

スプリント中に 3 つのバグが報告された場合:

Bug #1: ログイン時に 500 エラーが返される
Bug #2: 検索結果が正しくソートされない
Bug #3: ファイルアップロードが 10MB 以上で失敗する

実行方法

> 以下の 3 つのバグを並列で調査・修正してください:

  Bug #1: ログイン時に 500 エラーが返される
    → 認証関連のコードを調査して修正

  Bug #2: 検索結果が正しくソートされない
    → 検索ロジックを調査して修正

  Bug #3: ファイルアップロードが 10MB 以上で失敗する
    → アップロード処理を調査して修正

  各バグについて:
  1. 原因を特定
  2. 修正を実施
  3. テストを追加
  4. 結果を報告

期待される結果

┌─────────────────────────────────────────┐
│  並列デバッグの結果                         │
│                                          │
│  Bug #1: [修正済み]                        │
│    原因: パスワードハッシュの比較エラー         │
│    修正: bcrypt.compare の引数順を修正       │
│    テスト: auth.test.ts に 3 ケース追加     │
│                                          │
│  Bug #2: [修正済み]                        │
│    原因: sort 関数の比較関数が未定義          │
│    修正: 適切な比較関数を追加                 │
│    テスト: search.test.ts に 5 ケース追加   │
│                                          │
│  Bug #3: [修正済み]                        │
│    原因: multer のデフォルトサイズ制限          │
│    修正: 制限値を 50MB に変更               │
│    テスト: upload.test.ts に 2 ケース追加   │
└─────────────────────────────────────────┘

並列デバッグの注意点

• 同じファイルを複数のエージェントが同時に編集するとコンフリクトが起きる可能性があります
• バグ同士に依存関係がないことを確認してください
• 修正後は統合テストを実行して、相互の影響がないことを確認しましょう

実践例 3: フルプロジェクト開発

新しい機能をゼロから開発する場合のオーケストレーション例です。

フェーズ分割

Phase 1: 設計（Plan エージェント）
  ├── 要件の分析
  ├── アーキテクチャの設計
  └── タスクの分解

Phase 2: 実装（エージェントチーム）
  ├── チームメイト A: フロントエンド
  ├── チームメイト B: バックエンド
  └── チームメイト C: データベース

Phase 3: 品質保証（サブエージェント）
  ├── テスト作成エージェント
  ├── セキュリティレビューエージェント
  └── パフォーマンステストエージェント

Phase 4: 統合（チームリード）
  ├── コードの統合
  ├── 統合テスト
  └── ドキュメント更新

実行方法

# Phase 1: 設計
> ユーザーダッシュボード機能の設計をしてください。
  まず Plan モードで要件を分析し、アーキテクチャを設計して、
  タスクを分解してください。

# Phase 2: 実装
> 先ほどの設計に基づいて、以下の分担で実装してください:
  - フロントエンド: React でダッシュボード画面
  - バックエンド: REST API
  - データベース: マイグレーションとモデル

# Phase 3: 品質保証
> 実装したコードに対して以下を実行してください:
  - ユニットテストと統合テストの作成
  - セキュリティレビュー
  - パフォーマンスの確認

# Phase 4: 統合
> すべての変更を統合して、最終確認を行ってください。
  PR を作成してください。

フルプロジェクト開発のタイムライン

時間 →

Phase 1: [==設計==]
Phase 2:          [====フロント====]
                  [====バック====]
                  [====DB====]
Phase 3:                          [==テスト==]
                                  [==セキュリティ==]
Phase 4:                                     [==統合==]

Phase 2 の実装タスクは並列実行されるため、全体の所要時間が大幅に短縮されます。

オーケストレーションのベストプラクティス

1. フェーズを明確に分ける

# 良い例: フェーズが明確
> まず設計を行い、設計が確定してから実装を開始してください

# 避けるべき例: フェーズが曖昧
> 設計しながら実装してください

2. 成果物の受け渡しを定義する

> Phase 1 の設計フェーズでは以下を成果物としてください:
  - API 仕様書（エンドポイント、リクエスト/レスポンスの形式）
  - データベーススキーマ
  - コンポーネント構成図
  Phase 2 ではこの成果物に基づいて実装してください。

3. チェックポイントを設ける

> 各フェーズの完了時にレポートを作成し、
  次のフェーズに進む前に確認させてください。

段階的に導入する

最初から完全なオーケストレーションを構築する必要はありません。まずは 2 つのサブエージェントの組み合わせから始めて、徐々に複雑な構成に発展させましょう。

レベル 1: サブエージェント 1 つ + メイン Claude
レベル 2: 複数のサブエージェント
レベル 3: エージェントチーム
レベル 4: フルオーケストレーション

トラブルシューティング

問題	対処法
エージェント間でコンフリクト	ファイルの担当を明確に分ける
タスクの重複	タスクリストで担当を明記
品質のバラつき	レビューフェーズを追加
長時間の処理	タスクを小さく分割

まとめ

項目	内容
オーケストレーション	複数エージェントの役割・タイミングを管理
コードレビュー	複数観点の並列レビューで品質向上
並列デバッグ	独立したバグを同時修正
フルプロジェクト	設計→実装→検証→統合のフェーズ管理
ベストプラクティス	フェーズ分割、成果物定義、チェックポイント

これで Claude Code 完全ガイドの全ステップが完了です。Step 1 の環境構築から Step 7 のマルチエージェントまで、段階的に学んできました。ここで学んだ知識を活用して、AI と協力した効率的な開発を実践してください。