agent-patterns

エージェントのパターン

Claude Code と AI 支援開発におけるマルチエージェントの設計、委任、オーケストレーションです。大規模なソフトウェア開発では、役割を入れ替え可能なエージェントを標準とし、専門エージェントはピアレビューや議論ベースのワークフローに限って使用します。

Claude Code のサブエージェントは、カスタムシステムプロンプト、特定のツールアクセス、独立した権限を備え、隔離されたコンテキストウィンドウで動作する専門の AI アシスタントです。探索、テスト実行、冗長な操作をメインスレッドの外に置くことで、メインの会話コンテキストを維持します。

主な制約：サブエージェントは、ほかのサブエージェントを起動できません。複数ステップのオーケストレーションでは、メインの会話からサブエージェントを連鎖的に実行する必要があります。

クイックリファレンス

パターン	説明	使用する場面
同質なスウォーム	同一のエージェントが共有ボードからタスクを選択します	大規模なソフトウェア開発、回復力の高いシステム
順次パイプライン	各エージェントが前の出力を基に作業します	依存関係が明確な複数ステップのワークフロー
階層型	マネージャーが作業を分解し、ワーカーが並行して実行します	独立したサブタスクを含む複雑なタスク
ピアコラボレーション	エージェントが合意に至るまで反復します	コードレビュー、品質が重視される出力
オーケストレーターによる委任	メインの会話がサブエージェントを連鎖的に呼び出します	複数フェーズのワークフロー、専門家による並行作業
2段階レビュー	仕様への準拠を確認してから、コード品質を確認します	重大な影響を伴うコード、複雑な要件
質問優先の委任	エージェントが作業を進める前に確認質問をします	曖昧なタスク、やり直しのコストが高い作業
レビューループの適用	修正とレビューを繰り返し、最大反復回数に達するとエスカレーションします	収束が必要なあらゆるレビューワークフロー

組み込みサブエージェント	モデル	ツール	目的
Explore	Haiku	読み取り専用	ファイルの検出、コード検索、コードベースの調査
Plan	継承	読み取り専用	plan モード中のコードベース調査
General-purpose	継承	すべてのツール	複雑な調査、複数ステップの操作
Bash	継承	ターミナル	別のコンテキストでのターミナルコマンドの実行
Claude Code Guide	Haiku	読み取り専用	Claude Code の機能に関する質問への回答

設定	値
カスタムエージェントの配置場所	.claude/agents/*.md（プロジェクト）、~/.claude/agents/*.md（ユーザー）
CLI エージェント	--agents '{...}'（セッションのみ、JSON 形式）
プラグインエージェント	プラグインの agents/ ディレクトリ（優先度が最も低い）
必須フィールド	name、description
任意フィールド	tools、disallowedTools、model、permissionMode、skills、hooks、color
モデルの値	sonnet、opus、haiku、inherit（デフォルト）
権限モード	default、acceptEdits、dontAsk、bypassPermissions、plan
ネストの上限	サブエージェントは別のサブエージェントを起動できません（1階層のみ）
フォアグラウンドとバックグラウンド	フォアグラウンドではメインの会話がブロックされ、バックグラウンドでは並行して実行されます
バッチサイズ	エージェントあたり5～8項目（標準的なタスク）
並列エージェント	同時に2～4個

サブエージェントとメインの会話の使い分け

サブエージェントを使う場合	メインの会話を使う場合
タスクの出力が長大になる場合（テストスイート、ログ、API レスポンス）	頻繁なやり取りや反復的な調整が必要な場合
特定のツール制限や権限を適用する場合	複数のフェーズで重要なコンテキストを共有する場合
作業が自己完結しており、要約を返せる場合	すばやく対象を絞った変更を行う場合
独立した調査を並行して進める場合	レイテンシが重要な場合（サブエージェントは新たに開始してコンテキストを収集するため）

ツールアクセスのパターン

エージェントの役割	推奨ツール	理由
読み取り専用のレビュー担当	Read, Grep, Glob	コードを変更できないため、監査に安全
ファイル作成担当	Read, Write, Edit, Glob, Grep	Bash は使用不可。ヒアドキュメント利用時の承認要求の連発を回避
スクリプト実行担当	Read, Write, Edit, Glob, Grep, Bash	ビルド／デプロイタスクに必要なすべてのアクセス権
調査エージェント	Read, Grep, Glob, WebFetch, WebSearch	ドキュメント検索のための外部データアクセス

サブエージェントは、デフォルトですべてのツール（MCP ツールを含む）を継承します。アクセスを制限するには、tools を許可リストとして、または disallowedTools を拒否リストとして使用してください。MCP ツールはバックグラウンドのサブエージェントでは利用できません。

よくある間違い

間違い	正しいパターン
サブエージェントがさらにサブエージェントを起動できると期待する	サブエージェントは入れ子にできません。代わりに、メインの会話からサブエージェントを連鎖させます
ファイル作成だけを行うエージェントに Bash ツールを与える	Write と Edit ツールだけを使用します。Bash はヒアドキュメントの使用による承認要求を連発させます
機密性の高い操作で disallowedTools を指定し忘れる	ツールを継承する場合でも、危険なツールを明示的に拒否するには disallowedTools を使用します
小さなタスクにエージェントを起動しすぎる（5 体以上）	まず 2～3 体から始めます。それ以上では調整のオーバーヘッドがメリットを上回ります
エージェントのプロンプトの 300 行目より後に重要な指示を埋もれさせる	重要なルールはフロントマターの直後に置きます。モデルは後半の指示を優先度の低いものとして扱います
大規模なソフトウェア開発に特化型エージェントを使う	共有タスクボードを使う、役割を柔軟に割り当てられるエージェントを使います。特化型エージェントは単一障害点を生みます
委任プロンプトに「見つかった問題を修正する」を含めない	明示的な実行指示がないと、エージェントは問題を報告するだけで変更を加えません
コンテンツ生成にモデルとして Haiku を設定する	デフォルトでは Sonnet を使います。Haiku はスクリプト実行、高速な検索、合否チェックに限って使用します
カスタムエージェントの説明を明確に記述しない	Claude は description フィールドを使って自動委任するタイミングを判断します。説明が曖昧だと委任されません
バックグラウンドのサブエージェントで MCP ツールを使う	MCP ツールはバックグラウンドのサブエージェントでは利用できません。代わりにフォアグラウンドで実行します
サブエージェントにスキルを事前ロードしない	サブエージェントは親からスキルを継承しません。skills フィールドに明示的に記載してください

委任

• エージェントのプロンプトを設計する前にコードベースを調査する：Claude は、ファイルの検索とコード検索のために、組み込みの Explore サブエージェント（Haiku、読み取り専用）へ自動的に委任します。簡易、中程度、非常に詳細なモードに対応しています
• 複雑なプロジェクトではマルチエージェントのアーキテクチャを計画する：プランモードを使用します。Claude は計画を提示する前に、調査を Plan サブエージェントに委任します
• 多数のファイルに対する一括操作を実行する：メインの会話から、同一のプロンプトと重複しない項目リストを指定して、汎用サブエージェントを連鎖的に呼び出します
• 大量の出力を伴う操作を分離する：テストの実行、ログの処理、ドキュメントの取得をサブエージェントに委任し、冗長な出力がメインコンテキストに入らないようにします
• 調査を並行して実行する：互いに独立した調査のために複数のサブエージェントを同時に起動します。すべての調査が完了すると、Claude が結果を統合します
• 中断された作業を再開する：Claude に以前のサブエージェントの作業を続けるよう依頼します。再開されたエージェントは、ツールの呼び出しや推論を含む会話履歴全体を保持しています

プロジェクトレベルのワークフローの順序付け、フェーズゲート検証、目標の分解、能力のスコアリングには、orchestration スキルを使用します。

参考資料

• エージェントの種類と設計パターン
• 委任パターンと一括ワークフロー
• サブエージェントの設定とプロンプトエンジニアリング
• コミュニケーションとオーケストレーションのパターン
• トラブルシューティングとアンチパターン