Claude Code でカスタムサブエージェントを作る方法

サブエージェントの仕組み

Claude Code のサブエージェントは、メインの会話とは独立したコンテキストウィンドウで動作する AI インスタンスだ。メインエージェントがタスクをサブエージェントに委譲すると、サブエージェントは自身のコンテキストで処理を完結させ、結果だけをメインの会話に返す。これによりメインのコンテキストウィンドウを圧迫せず、並列・大規模タスクの分割処理が可能になる。

サブエージェントには2つの起動パターンがある。

• 独立コンテキスト型: サブエージェントが完全に独立したコンテキストで動作する。メインの会話履歴を引き継がない
• 共有コンテキスト型: メインエージェントの現在のコンテキストを引き継いだ状態で起動する

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

カスタムサブエージェントは、/agents コマンドを使う方法と、Markdown ファイルを手動で作成する方法の2通りがある。

/agents コマンドを使う方法

Claude Code のチャット画面で /agents と入力するとエージェント管理UIが開く。「Create new agent」を選択し、エディタ上でエージェントの設定を記述して保存すると、即座に利用可能になる。

/agents

Markdown ファイルを手動で作成する方法

エージェントの定義は Markdown ファイルとして記述する。配置場所によってスコープが変わる。

ファイルのフォーマットは以下の通り。フロントマターに name・description・model を記述し、本文にエージェントへの指示（システムプロンプト）を書く。

---
name: code-reviewer
description: コードレビューを行うエージェント。PR の差分を受け取り、バグ・パフォーマンス・セキュリティの観点でコメントを返す。
model: claude-haiku-4-5
---

あなたは経験豊富なコードレビュアーです。
与えられたコード差分に対し、以下の観点でレビューコメントを日本語で出力してください。

1. バグ・論理エラー
2. パフォーマンス上の問題
3. セキュリティリスク
4. 可読性・保守性

model には claude-haiku-4-5 のような軽量モデルを指定することで、コストを抑えつつ高速に動作させることができる¹。

組み込みサブエージェントとの使い分け

Claude Code には最初から使える組み込みサブエージェント（claude-code-guide・Explore・general-purpose など）が存在する。これらは汎用目的向けであるため、特定のプロジェクトやワークフローに特化した処理には自作のカスタムサブエージェントを用意する方が効果的だ。

たとえば「調査専用エージェント」「テスト生成エージェント」「ドキュメント整形エージェント」のように、役割を1つに絞った小さなエージェントを複数作り、メインエージェントが必要に応じて委譲するパターンが実用的だ。

つまずきやすい点

エージェントファイルを作成・編集した後は、Claude Code を再起動しないと変更が反映されない。/agents コマンドでも同様のメッセージ（restart to load the latest version）が表示される。

また、description フィールドはメインエージェントがどのサブエージェントを呼び出すかを判断する根拠になる。ここに「どんな状況でこのエージェントを使うか」を具体的に書かないと、意図したタイミングで呼び出されないことがある。