Claude Codeのカスタムサブエージェントは、特定のタイプのタスクを処理するために呼び出すことができる専門的なAIアシスタントです。これらは、カスタマイズされたシステムプロンプト、ツール、および独立したコンテキストウィンドウを持つタスク固有の設定を提供することで、より効率的な問題解決を可能にします。

サブエージェントとは?

サブエージェントは、Claude Codeがタスクを委任できる事前設定されたAIパーソナリティです。各サブエージェントは:
  • 特定の目的と専門分野を持つ
  • メインの会話とは独立した独自のコンテキストウィンドウを使用する
  • 使用を許可された特定のツールで設定できる
  • その動作を導くカスタムシステムプロンプトを含む
Claude Codeがサブエージェントの専門分野に一致するタスクに遭遇すると、そのタスクを専門のサブエージェントに委任でき、サブエージェントは独立して作業し結果を返します。

主な利点

コンテキストの保持

各サブエージェントは独自のコンテキストで動作し、メインの会話の汚染を防ぎ、高レベルの目標に集中し続けます。

専門的な専門知識

サブエージェントは特定のドメインに対する詳細な指示で微調整でき、指定されたタスクでより高い成功率をもたらします。

再利用性

一度作成されたサブエージェントは、異なるプロジェクト間で使用でき、一貫したワークフローのためにチームと共有できます。

柔軟な権限

各サブエージェントは異なるツールアクセスレベルを持つことができ、強力なツールを特定のサブエージェントタイプに制限できます。

クイックスタート

最初のサブエージェントを作成するには:
1

サブエージェントインターフェースを開く

以下のコマンドを実行します:
/agents
2

'Create New Agent'を選択

プロジェクトレベルまたはユーザーレベルのサブエージェントを作成するかを選択します
3

サブエージェントを定義

  • 推奨:まずClaudeで生成し、その後カスタマイズして自分のものにする
  • サブエージェントを詳細に説明し、いつ使用すべきかを記述する
  • アクセスを許可したいツールを選択する(または空白のままにしてすべてのツールを継承)
  • インターフェースはすべての利用可能なツールを表示し、選択を簡単にします
  • Claudeで生成している場合、eを押して独自のエディターでシステムプロンプトを編集することもできます
4

保存して使用

サブエージェントが利用可能になりました!Claudeは適切な場合に自動的に使用するか、明示的に呼び出すことができます:
> code-reviewerサブエージェントを使用して最近の変更をチェックしてください

サブエージェントの設定

ファイルの場所

サブエージェントは、YAMLフロントマターを持つMarkdownファイルとして2つの可能な場所に保存されます:
タイプ場所スコープ優先度
プロジェクトサブエージェント.claude/agents/現在のプロジェクトで利用可能最高
ユーザーサブエージェント~/.claude/agents/すべてのプロジェクトで利用可能低い
サブエージェント名が競合する場合、プロジェクトレベルのサブエージェントがユーザーレベルのサブエージェントより優先されます。

プラグインエージェント

プラグインは、Claude Codeとシームレスに統合するカスタムサブエージェントを提供できます。プラグインエージェントはユーザー定義エージェントと同様に動作し、/agentsインターフェースに表示されます。 プラグインエージェントの場所:プラグインはagents/ディレクトリ(またはプラグインマニフェストで指定されたカスタムパス)にエージェントを含みます。 プラグインエージェントの使用
  • プラグインエージェントはカスタムエージェントと一緒に/agentsに表示されます
  • 明示的に呼び出すことができます:「security-pluginのcode-reviewerエージェントを使用してください」
  • 適切な場合にClaudeによって自動的に呼び出すことができます
  • /agentsインターフェースを通じて管理(表示、検査)できます
プラグインエージェントの作成の詳細については、プラグインコンポーネントリファレンスを参照してください。

CLIベースの設定

JSONオブジェクトを受け入れる--agents CLIフラグを使用して、サブエージェントを動的に定義することもできます:
claude --agents '{
  "code-reviewer": {
    "description": "エキスパートコードレビュアー。コード変更後に積極的に使用。",
    "prompt": "あなたはシニアコードレビュアーです。コード品質、セキュリティ、ベストプラクティスに焦点を当ててください。",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
優先度:CLI定義のサブエージェントは、プロジェクトレベルのサブエージェントより低い優先度を持ちますが、ユーザーレベルのサブエージェントより高い優先度を持ちます。 使用例:このアプローチは以下に有用です:
  • サブエージェント設定の迅速なテスト
  • 保存する必要のないセッション固有のサブエージェント
  • カスタムサブエージェントが必要な自動化スクリプト
  • ドキュメントやスクリプトでのサブエージェント定義の共有
JSON形式とすべての利用可能なオプションの詳細については、CLIリファレンスドキュメントを参照してください。

ファイル形式

各サブエージェントは、この構造を持つMarkdownファイルで定義されます:
---
name: your-sub-agent-name
description: このサブエージェントがいつ呼び出されるべきかの説明
tools: tool1, tool2, tool3  # オプション - 省略した場合はすべてのツールを継承
model: sonnet  # オプション - モデルエイリアスまたは'inherit'を指定
---

サブエージェントのシステムプロンプトをここに記述します。これは複数の段落にすることができ、
サブエージェントの役割、能力、問題解決へのアプローチを明確に定義する必要があります。

サブエージェントが従うべき具体的な指示、ベストプラクティス、制約を含めてください。

設定フィールド

フィールド必須説明
nameはい小文字とハイフンを使用した一意の識別子
descriptionはいサブエージェントの目的の自然言語による説明
toolsいいえ特定のツールのカンマ区切りリスト。省略した場合、メインスレッドからすべてのツールを継承
modelいいえこのサブエージェントに使用するモデル。モデルエイリアス(sonnetopushaiku)または'inherit'でメインの会話のモデルを使用。省略した場合、設定されたサブエージェントモデルがデフォルト

モデル選択

modelフィールドにより、サブエージェントが使用するAIモデルを制御できます:
  • モデルエイリアス:利用可能なエイリアスの1つを使用:sonnetopus、またはhaiku
  • 'inherit':メインの会話と同じモデルを使用(一貫性に有用)
  • 省略:指定されていない場合、サブエージェント用に設定されたデフォルトモデル(sonnet)を使用
'inherit'の使用は、サブエージェントをメインの会話のモデル選択に適応させたい場合に特に有用で、セッション全体で一貫した能力と応答スタイルを確保します。

利用可能なツール

サブエージェントは、Claude Codeの内部ツールのいずれかへのアクセスを許可できます。利用可能なツールの完全なリストについては、ツールドキュメントを参照してください。
推奨: ツールアクセスを変更するには/agentsコマンドを使用してください - 接続されたMCPサーバーツールを含むすべての利用可能なツールをリストするインタラクティブなインターフェースを提供し、必要なものを選択しやすくします。
ツールの設定には2つのオプションがあります:
  • toolsフィールドを省略してメインスレッドからすべてのツール(デフォルト)を継承、MCPツールを含む
  • 個別のツールを指定してより細かい制御のためのカンマ区切りリスト(手動または/agents経由で編集可能)
MCPツール:サブエージェントは設定されたMCPサーバーからMCPツールにアクセスできます。toolsフィールドが省略された場合、サブエージェントはメインスレッドで利用可能なすべてのMCPツールを継承します。

サブエージェントの管理

/agentsコマンドの使用(推奨)

/agentsコマンドは、サブエージェント管理のための包括的なインターフェースを提供します:
/agents
これにより、以下が可能なインタラクティブメニューが開きます:
  • すべての利用可能なサブエージェント(組み込み、ユーザー、プロジェクト)を表示
  • ガイド付きセットアップで新しいサブエージェントを作成
  • ツールアクセスを含む既存のカスタムサブエージェントを編集
  • カスタムサブエージェントを削除
  • 重複がある場合にどのサブエージェントがアクティブかを確認
  • 利用可能なツールの完全なリストでツール権限を簡単に管理

直接ファイル管理

ファイルを直接操作してサブエージェントを管理することもできます:
# プロジェクトサブエージェントを作成
mkdir -p .claude/agents
echo '---
name: test-runner
description: テストを実行し失敗を修正するために積極的に使用
---

あなたはテスト自動化の専門家です。コード変更を見たら、適切なテストを積極的に実行してください。テストが失敗した場合、失敗を分析し、元のテストの意図を保持しながら修正してください。' > .claude/agents/test-runner.md

# ユーザーサブエージェントを作成
mkdir -p ~/.claude/agents
# ... サブエージェントファイルを作成

サブエージェントの効果的な使用

自動委任

Claude Codeは以下に基づいてタスクを積極的に委任します:
  • リクエスト内のタスク説明
  • サブエージェント設定のdescriptionフィールド
  • 現在のコンテキストと利用可能なツール
より積極的なサブエージェント使用を促すには、descriptionフィールドに「積極的に使用」や「必ず使用」などのフレーズを含めてください。

明示的な呼び出し

コマンドで言及することで特定のサブエージェントをリクエストします:
> test-runnerサブエージェントを使用して失敗したテストを修正してください
> code-reviewerサブエージェントに最近の変更を確認してもらってください
> debuggerサブエージェントにこのエラーを調査してもらってください

サブエージェントの例

コードレビュアー

---
name: code-reviewer
description: エキスパートコードレビュー専門家。品質、セキュリティ、保守性のためにコードを積極的にレビューします。コードの記述または変更後すぐに使用してください。
tools: Read, Grep, Glob, Bash
model: inherit
---

あなたは高いコード品質とセキュリティ基準を確保するシニアコードレビュアーです。

呼び出された時:
1. git diffを実行して最近の変更を確認
2. 変更されたファイルに焦点を当てる
3. すぐにレビューを開始

レビューチェックリスト:
- コードがシンプルで読みやすい
- 関数と変数が適切に命名されている
- 重複したコードがない
- 適切なエラーハンドリング
- 秘密情報やAPIキーが露出していない
- 入力検証が実装されている
- 良いテストカバレッジ
- パフォーマンスの考慮事項が対処されている

優先度別にフィードバックを提供:
- 重要な問題(必ず修正)
- 警告(修正すべき)
- 提案(改善を検討)

問題の修正方法の具体例を含めてください。

デバッガー

---
name: debugger
description: エラー、テスト失敗、予期しない動作のデバッグ専門家。問題に遭遇した際に積極的に使用してください。
tools: Read, Edit, Bash, Grep, Glob
---

あなたは根本原因分析を専門とするエキスパートデバッガーです。

呼び出された時:
1. エラーメッセージとスタックトレースを取得
2. 再現手順を特定
3. 失敗箇所を分離
4. 最小限の修正を実装
5. 解決策が機能することを確認

デバッグプロセス:
- エラーメッセージとログを分析
- 最近のコード変更を確認
- 仮説を形成してテスト
- 戦略的なデバッグログを追加
- 変数の状態を検査

各問題について以下を提供:
- 根本原因の説明
- 診断を支持する証拠
- 具体的なコード修正
- テストアプローチ
- 予防の推奨事項

症状だけでなく、根本的な問題の修正に焦点を当ててください。

データサイエンティスト

---
name: data-scientist
description: SQLクエリ、BigQuery操作、データインサイトのデータ分析専門家。データ分析タスクとクエリに積極的に使用してください。
tools: Bash, Read, Write
model: sonnet
---

あなたはSQLとBigQuery分析を専門とするデータサイエンティストです。

呼び出された時:
1. データ分析要件を理解
2. 効率的なSQLクエリを記述
3. 適切な場合にBigQueryコマンドラインツール(bq)を使用
4. 結果を分析して要約
5. 発見を明確に提示

主要な実践:
- 適切なフィルターを持つ最適化されたSQLクエリを記述
- 適切な集計と結合を使用
- 複雑なロジックを説明するコメントを含める
- 読みやすさのために結果をフォーマット
- データ駆動型の推奨事項を提供

各分析について:
- クエリアプローチを説明
- 仮定を文書化
- 主要な発見をハイライト
- データに基づく次のステップを提案

クエリが効率的でコスト効果的であることを常に確保してください。

ベストプラクティス

  • Claude生成エージェントから始める:初期サブエージェントをClaudeで生成し、その後それを反復して個人的なものにすることを強く推奨します。このアプローチにより最良の結果が得られます - 特定のニーズにカスタマイズできる堅実な基盤です。
  • 焦点を絞ったサブエージェントを設計:1つのサブエージェントにすべてを行わせようとするのではなく、単一の明確な責任を持つサブエージェントを作成してください。これによりパフォーマンスが向上し、サブエージェントがより予測可能になります。
  • 詳細なプロンプトを記述:システムプロンプトに具体的な指示、例、制約を含めてください。より多くのガイダンスを提供するほど、サブエージェントのパフォーマンスが向上します。
  • ツールアクセスを制限:サブエージェントの目的に必要なツールのみを許可してください。これによりセキュリティが向上し、サブエージェントが関連するアクションに集中できます。
  • バージョン管理:プロジェクトサブエージェントをバージョン管理にチェックインして、チームが恩恵を受け、協力的に改善できるようにしてください。

高度な使用法

サブエージェントのチェーン化

複雑なワークフローでは、複数のサブエージェントをチェーン化できます:
> まずcode-analyzerサブエージェントを使用してパフォーマンス問題を見つけ、次にoptimizerサブエージェントを使用してそれらを修正してください

動的サブエージェント選択

Claude Codeはコンテキストに基づいてサブエージェントを知的に選択します。最良の結果を得るために、descriptionフィールドを具体的でアクション指向にしてください。

パフォーマンスの考慮事項

  • コンテキスト効率:エージェントはメインコンテキストの保持を助け、より長い全体的なセッションを可能にします
  • レイテンシ:サブエージェントは呼び出されるたびにクリーンスレートから始まり、効果的に仕事を行うために必要なコンテキストを収集する際にレイテンシを追加する可能性があります。

関連ドキュメント

  • プラグイン - プラグインを通じてカスタムエージェントでClaude Codeを拡張
  • スラッシュコマンド - その他の組み込みコマンドについて学ぶ
  • 設定 - Claude Codeの動作を設定
  • フック - イベントハンドラーでワークフローを自動化