サブエージェントを作成する
Claude Codeには組み込みのサブエージェントが用意されていますが、独自のサブエージェントを作成することもできます。カスタムサブエージェントは、コードレビュー、テストの作成、ドキュメントの確認など、特定のタスクに特化しています。これらはYAMLフロントマターを持つMarkdownファイルとして定義され、Claudeにいつそのサブエージェントを使用すべきか、そしてそのサブエージェントがどのように振る舞うべきかを伝えます。
サブエージェントを作成する
サブエージェントを作成する最も簡単な方法は、Claudeに書いてもらうよう依頼することです。作成したいサブエージェントとその保存先を説明すれば、Claudeがファイルを作成します。このレッスンの動画と最初の3枚のスクリーンショットでは、Claude Code v2.1.198で削除された/agentsウィザードを示しています。サブエージェントファイルとそのフィールドは変更されていないため、スコープ、ツール、モデル、色を選択することに変わりはありません。リクエストにはこれらの選択内容を含めてください。
まず、サブエージェントのスコープを選択します。.claude/agents/内のファイルはプロジェクトレベルであり、~/.claude/agents/内のファイルはユーザーレベルです。
- プロジェクトレベル -- 現在のプロジェクトでのみ利用可能
- ユーザーレベル -- マシン上のすべてのプロジェクトで共有
次に、作成方法を選択できます。設定を手動で記述することもできますが、推奨される方法はClaudeに生成させることです。サブエージェントに何をさせたいかを説明するだけで、Claudeはあなたの入力に基づいて名前、説明、システムプロンプトを生成します。

ツールをカスタマイズする
作成中に、サブエージェントがアクセスできるツールをカスタマイズする機会があります。ツールのカテゴリには以下が含まれます。
- 読み取り専用ツール
- 編集ツール
- 実行ツール
- MCPツール
- その他のツール

サブエージェントが実際に何を必要としているかを考えてみましょう。コードレビュアーはおそらく編集ツールを必要としません -- コードを読んで分析すべきであり、変更すべきではないからです。ただし、保留中の変更をより簡単に特定できるように、実行ツールを有効にしておきたい場合もあります。
モデルと色を選択する
ツールを設定した後、サブエージェントを動かすClaudeモデルを選択します。選択肢は以下の通りです。
- Haiku -- 高速で軽量なタスクに最適
- Sonnet -- 速度と深さのバランスが取れた選択肢
- Opus -- 複雑な分析に最適
- Inherit -- メインの会話で実行されているモデルをそのまま使用
最後に、色を選びます。これはUIに表示されるため、どのサブエージェントがアクティブかをすぐに確認できます。ちょっとした工夫ですが、複数のサブエージェントを実行している場合に役立ちます。

設定ファイル
作成が完了すると、サブエージェントの設定ファイルは選択したスコープに対応するフォルダに保存されます(プロジェクトレベルのサブエージェントの場合、通常は.claude/agents/your-agent-name.mdです)。典型的なサブエージェント設定は次のようになります。
---
name: code-quality-reviewer
description: Use this agent when you need to review recently written or modified code for quality, security, and best practice compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---
You are an expert code reviewer specializing in quality assurance, security best practices, and
adherence to project standards. Your role is to thoroughly examine recently written or modified code
and identify issues that could impact reliability, security, maintainability, or performance.各フィールドを詳しく見ていきましょう。
name-- サブエージェントの一意の識別子です。これは、Claudeに直接依頼するか、メッセージ内で@agent-code-quality-reviewerと入力することで参照する方法です。description-- Claudeがいつサブエージェントを使用するかを決定する際の制御に使われます。これは1行でなければなりません(改行が必要な場合はエスケープされた改行文字\nを使用してください)。ここに会話例を含めることで、Claudeがいつ委任が適切かを理解する助けになります。tools-- サブエージェントがアクセスできるツールを一覧表示します。Claudeがリクエストに基づいてこれを入力しますが、いつでもここでリストを編集できます。model-- 使用するClaudeモデルを指定します。エイリアス(sonnet、opus、haiku、fable)、claude-sonnet-5のような完全なモデルID、またはinheritのいずれかです。color-- サブエージェントを識別するためのUIの色です。
システムプロンプト
Markdownファイルの本文(YAMLフロントマターより下のすべて)がシステムプロンプトです。ここで、サブエージェントに指示を与えます。何に焦点を当てるべきか、どのように物事を分析すべきか、そしてメインエージェントにどのように結果を報告すべきかです。
よく書かれたシステムプロンプトが、役に立つサブエージェントと要点を外したサブエージェントの違いを生みます。サブエージェントが何を探すべきか、そして出力をどのように構成すべきかについて具体的に記述してください。
Claudeに自動的にサブエージェントを使わせる
明示的に依頼しなくてもClaudeにタスクをサブエージェントへ委任させたい場合は、description フィールドに「proactively」という単語を含めてください。例えば次のようになります。
description: Proactively suggest running this agent after major code changes...また、descriptionに会話例を追加して、サブエージェントを使用すべき具体的なシナリオをClaudeが理解できるようにすることもできます。例が具体的であればあるほど、Claudeはいつ委任すべきかをより正確に把握できるようになります。
サブエージェントをテストする
サブエージェントを作成したら、実際にコードを変更してClaudeにレビューを依頼することでテストしてみましょう。セッション開始時にagentsフォルダが存在しなかった場合は、まずClaude Codeを再起動して新しいサブエージェントを読み込んでください。

期待通りにサブエージェントが使用されない場合は、戻ってdescriptionを確認してください。より具体的な例やトリガーとなるシナリオを追加することで、Claudeがいつサブエージェントに作業を委任すべきかを理解しやすくなります。