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

​
サブエージェントとは？

サブエージェントは、Claude Codeがタスクを委任できる事前設定されたAIパーソナリティです。各サブエージェントは：

  • 特定の目的と専門分野を持つ
  • メインの会話とは独立した独自のコンテキストウィンドウを使用する
  • 使用を許可された特定のツールで設定できる
  • その動作を導くカスタムシステムプロンプトを含む

Claude Codeがサブエージェントの専門分野に一致するタスクに遭遇すると、そのタスクを専門化されたサブエージェントに委任でき、サブエージェントは独立して作業し結果を返します。

​
主な利点

コンテキストの保持

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

専門的な専門知識

サブエージェントは特定のドメインの詳細な指示で微調整でき、指定されたタスクでの成功率向上につながります。

再利用性

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

柔軟な権限

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

​
クイックスタート

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

1

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

次のコマンドを実行します：

/agents
2

「新しいエージェントを作成」を選択

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

3

サブエージェントを定義

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

保存して使用

サブエージェントが利用可能になりました！Claudeは適切な場合に自動的に使用するか、明示的に呼び出すことができます：

> code-reviewerサブエージェントを使用して最近の変更をチェックしてください

​
サブエージェントの設定

​
ファイルの場所

サブエージェントは、YAMLフロントマターを持つMarkdownファイルとして2つの可能な場所に保存されます：

タイプ場所スコープ優先度
プロジェクトサブエージェント.claude/agents/現在のプロジェクトで利用可能最高
ユーザーサブエージェント~/.claude/agents/すべてのプロジェクトで利用可能低い

サブエージェント名が競合する場合、プロジェクトレベルのサブエージェントがユーザーレベルのサブエージェントより優先されます。

​
ファイル形式

各サブエージェントは、この構造を持つMarkdownファイルで定義されます：

---
name: your-sub-agent-name
description: このサブエージェントがいつ呼び出されるべきかの説明
tools: tool1, tool2, tool3  # オプション - 省略された場合はすべてのツールを継承
---

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

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

​
設定フィールド

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

​
利用可能なツール

サブエージェントは、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
---

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

呼び出された時：
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
---

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

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

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

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

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

​
ベストプラクティス

  • Claudeで生成されたエージェントから始める：初期サブエージェントをClaudeで生成し、その後それを反復して個人的なものにすることを強く推奨します。このアプローチにより最良の結果が得られます - 特定のニーズにカスタマイズできる堅実な基盤です。

  • 焦点を絞ったサブエージェントを設計：1つのサブエージェントにすべてをやらせようとするのではなく、単一で明確な責任を持つサブエージェントを作成してください。これによりパフォーマンスが向上し、サブエージェントがより予測可能になります。

  • 詳細なプロンプトを書く：システムプロンプトに具体的な指示、例、制約を含めてください。より多くのガイダンスを提供するほど、サブエージェントのパフォーマンスが向上します。

  • ツールアクセスを制限：サブエージェントの目的に必要なツールのみを許可してください。これによりセキュリティが向上し、サブエージェントが関連するアクションに集中できます。

  • バージョン管理：プロジェクトサブエージェントをバージョン管理にチェックインして、チームが恩恵を受け、協力して改善できるようにしてください。

​
高度な使用法

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

複雑なワークフローでは、複数のサブエージェントをチェーン化できます：

> まずcode-analyzerサブエージェントを使用してパフォーマンスの問題を見つけ、次にoptimizerサブエージェントを使用してそれらを修正してください

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

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

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

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

​
関連ドキュメント

  • スラッシュコマンド - その他の組み込みコマンドについて学ぶ
  • 設定 - Claude Codeの動作を設定する
  • フック - イベントハンドラーでワークフローを自動化する