SDKにおけるサブエージェント

Claude Code SDKでサブエージェントを使用する方法

Claude Code SDKにおけるサブエージェントは、メインエージェントによって統制される特殊化されたAIです。 コンテキスト管理と並列化にサブエージェントを使用してください。

このガイドでは、SDKアプリケーションがマークダウンファイルを通じて作成されたサブエージェントとどのように相互作用し、活用するかを説明します。

概要

サブエージェントは、指定されたディレクトリにYAMLフロントマターを含むマークダウンファイルを配置することで、ファイルシステムベースのアプローチを通じてのみ作成されます。SDKは実行中にこれらの事前定義されたサブエージェントを呼び出すことができます。

サブエージェントを使用する利点

コンテキスト管理

サブエージェントはメインエージェントから分離されたコンテキストを維持し、情報過多を防ぎ、相互作用を集中させます。この分離により、特殊化されたタスクが無関係な詳細でメインの会話コンテキストを汚染することがなくなります。

例: research-assistantサブエージェントは、中間検索結果でメインの会話を散らかすことなく、数十のファイルとドキュメントページを探索し、関連する発見のみを返すことができます。

並列化

複数のサブエージェントが同時に実行でき、複雑なワークフローを劇的に高速化します。

例: コードレビュー中に、style-checker、security-scanner、test-coverageサブエージェントを同時に実行し、レビュー時間を数分から数秒に短縮できます。

特殊化された指示と知識

各サブエージェントは、特定の専門知識、ベストプラクティス、制約を持つカスタマイズされたシステムプロンプトを持つことができます。

例: database-migrationサブエージェントは、SQLのベストプラクティス、ロールバック戦略、データ整合性チェックに関する詳細な知識を持つことができ、これらはメインエージェントの指示では不要なノイズとなります。

ツール制限

サブエージェントは特定のツールに制限でき、意図しない行動のリスクを軽減します。

例: doc-reviewerサブエージェントは読み取りとGrepツールのみにアクセスでき、分析はできるが誤ってドキュメントファイルを変更することがないことを保証します。

サブエージェントの作成

サブエージェントは特定のディレクトリにマークダウンファイルとして定義されます：

• プロジェクトレベル: .claude/agents/*.md - 現在のプロジェクトでのみ利用可能
• ユーザーレベル: ~/.claude/agents/*.md - すべてのプロジェクトで利用可能

ファイル形式

各サブエージェントは、YAMLフロントマターを含むマークダウンファイルです：

---
name: code-reviewer
description: Expert code review specialist. Use for quality, security, and maintainability reviews.
tools: Read, Grep, Glob, Bash  # Optional - inherits all tools if omitted
---

Your subagent's system prompt goes here. This defines the subagent's
role, capabilities, and approach to solving problems.

Include specific instructions, best practices, and any constraints
the subagent should follow.

設定フィールド

フィールド	必須	説明
name	はい	小文字とハイフンを使用した一意の識別子
description	はい	このサブエージェントをいつ使用するかの自然言語での説明
tools	いいえ	許可されたツールのカンマ区切りリスト。省略した場合、すべてのツールを継承

SDKがサブエージェントを使用する方法

Claude Code SDKを使用する際、ファイルシステムで定義されたサブエージェントは自動的に利用可能になります。Claude Codeは：

1. サブエージェントを自動検出します .claude/agents/ ディレクトリから
2. タスクマッチングに基づいて自動的に呼び出します
3. 特殊化されたプロンプトとツール制限を使用します
4. 各サブエージェント呼び出しで分離されたコンテキストを維持します

SDKはファイルシステム設定を尊重します - 実行時にプログラム的にサブエージェントを作成する方法はありません。すべてのサブエージェントはSDK実行前にファイルとして定義される必要があります。

サブエージェントの例

コードレビュアー、テストランナー、デバッガー、セキュリティ監査人を含むサブエージェントの包括的な例については、メインサブエージェントガイドを参照してください。このガイドには、効果的なサブエージェントを作成するための詳細な設定とベストプラクティスが含まれています。

SDK統合パターン

自動呼び出し

SDKはタスクコンテキストに基づいて適切なサブエージェントを自動的に呼び出します。サブエージェントのdescriptionフィールドがいつ使用されるべきかを明確に示すようにしてください：

---
name: performance-optimizer
description: Use PROACTIVELY when code changes might impact performance. MUST BE USED for optimization tasks.
tools: Read, Edit, Bash, Grep
---

明示的呼び出し

ユーザーはプロンプトで特定のサブエージェントを要求できます：

// SDKを使用する際、ユーザーは明示的にサブエージェントを要求できます：
const result = await query({
  prompt: "Use the code-reviewer subagent to check the authentication module"
});

ツール制限

サブエージェントはtoolsフィールドを通じてツールアクセスを制限できます：

• フィールドを省略 - サブエージェントは利用可能なすべてのツールを継承（デフォルト）
• ツールを指定 - サブエージェントはリストされたツールのみ使用可能

読み取り専用分析サブエージェントの例：

---
name: code-analyzer
description: Static code analysis and architecture review
tools: Read, Grep, Glob  # No write or execute permissions
---

You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.

関連ドキュメント

• メインサブエージェントガイド - 包括的なサブエージェントドキュメント
• SDK設定ガイド - 設定アプローチの概要
• 設定 - 設定ファイルリファレンス
• スラッシュコマンド - カスタムコマンド作成