【Claude Code】カスタムサブエージェントの作成 - タスク特化型AIアシスタントの構築方法

Claude Codeでは、特定のタスクを効率的に処理するためのカスタムサブエージェントを作成できます。サブエージェントは、独自のコンテキストウィンドウ、カスタムシステムプロンプト、ツール制限を持つ特化したAIアシスタントです。

この記事では、サブエージェントの基本概念から、作成方法、設定オプション、実践的な使用パターンまでを詳しく解説します。

サブエージェントとは

サブエージェントは、特定の種類のタスクを処理する特化したAIアシスタントです。各サブエージェントは以下の特徴を持ちます。

• 独自のコンテキストウィンドウで実行
• カスタムシステムプロンプトによる動作の定義
• 特定のツールアクセスの制限
• 独立した権限の設定

Claudeがサブエージェントの説明に一致するタスクに遭遇すると、自動的にそのサブエージェントに委譲され、独立して動作した後、結果を返します。

サブエージェントのメリット

組み込みサブエージェント

Claude Codeには、以下の組み込みサブエージェントが含まれています。

Explore

コードベースの検索と分析に最適化された読み取り専用エージェントです。

Plan

プランモード中にコンテキストを収集するための研究エージェントです。

General-purpose

探索とアクションの両方を必要とする複雑なマルチステップタスク用のエージェントです。

カスタムサブエージェントの作成

/agentsコマンドを使用する方法

最も簡単な方法は、/agentsコマンドを使用することです。

/agents

ファイルをスキャンして、可読性、パフォーマンス、
およびベストプラクティスの改善を提案するコード改善エージェント。

code-improverエージェントを使用して、このプロジェクトの改善を提案してください

サブエージェントファイルを手動で作成

サブエージェントはYAMLフロントマター付きのMarkdownファイルで定義します。

---
name: code-reviewer
description: コード品質とベストプラクティスのレビュー
tools: Read, Glob, Grep
model: sonnet
---

あなたはコードレビュアーです。呼び出されたときは、
コードを分析し、品質、セキュリティ、および
ベストプラクティスに関する具体的で実行可能な
フィードバックを提供してください。

サブエージェントのスコープ

サブエージェントは保存場所によって異なるスコープを持ちます。

claude --agents '{
  "code-reviewer": {
    "description": "エキスパートコードレビュアー",
    "prompt": "あなたはシニアコードレビュアーです。",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

設定オプション

フロントマターフィールド

利用可能なツール

サブエージェントは、Claude Codeの内部ツールを使用できます。デフォルトでは、メイン会話から利用可能なすべてのツール（MCPツール含む）を継承します。

---
name: safe-researcher
description: 制限された機能を持つ研究エージェント
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
---

権限モード

サブエージェントの使用パターン

自動委譲

Claudeは、リクエスト内のタスク説明とサブエージェントのdescriptionフィールドに基づいて、タスクを自動的に委譲します。

フォアグラウンドとバックグラウンド

大量の操作を分離

サブエージェントの効果的な使用法の1つは、大量の出力を生成する操作を分離することです。

サブエージェントを使用してテストスイートを実行し、
失敗したテストとそのエラーメッセージのみを報告してください

並列研究

独立した調査の場合、複数のサブエージェントを生成して同時に作業させます。

認証、データベース、およびAPIモジュールを
並列で調査するために、別々のサブエージェントを使用してください

サブエージェントをチェーン

マルチステップワークフローの場合、Claudeに順序でサブエージェントを使用するよう依頼します。

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

サブエージェントの例

コードレビュアー

コードを変更せずにレビューする読み取り専用サブエージェント。

---
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: db-reader
description: 読み取り専用データベースクエリを実行
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

あなたは読み取り専用アクセス権を持つデータベースアナリストです。
SELECTクエリを実行してデータに関する質問に答えてください。

検証スクリプトの例：

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "ブロック：SELECTクエリのみが許可されています" >&2
  exit 2
fi

exit 0

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

サブエージェントの再開

サブエージェントが完了すると、ClaudeはそのエージェントIDを受け取ります。前の作業を続けるには、Claudeに再開を依頼します。

code-reviewerサブエージェントを使用して認証モジュールをレビューしてください
[エージェントが完了]

そのコードレビューを続けて、今度は認可ロジックを分析してください
[Claudeは前の会話から完全なコンテキストでサブエージェントを再開]

まとめ

サブエージェントを活用することで、Claude Codeでのワークフローを大幅に効率化できます。コードレビュー、デバッグ、データ分析など、繰り返し行うタスクを特化したエージェントに委譲することで、メインの会話コンテキストを保持しながら、効率的に作業を進められます。

参考文献

• Claude Code - カスタムサブエージェントの作成（公式ドキュメント）
• Claude Code - フック
• Claude Code - スキル
• Claude Code - プラグイン