カスタムサブエージェントとは — 別コンテキストで特化タスクを任せる専用AI
カスタムサブエージェントは、特定のタスクだけを独立したコンテキストウィンドウ（会話履歴を持つ作業領域）で処理させる専用AIです。Markdownファイル1枚で定義でき、Claudeが説明文に合うタスクを見つけると自動で委譲し、結果の概要だけをメイン会話へ返します。
に検索ログや大量出力でメイン会話を汚さずに済む仕組み
テスト実行やログ解析は大量の出力を生み、メイン会話のコンテキストを一気に食い潰します。これをサブエージェントに任せれば、詳細な出力はサブエージェント側に留まり、メインには「失敗したテストとエラーだけ」といった要約が返る。ツールを読み取り専用に絞ればファイルを壊す心配もなく、探索と実装をきれいに分離できます。
Explore・Plan・general-purposeなど組み込みサブエージェントとの違い
ExploreとPlanは読み取り専用で、CLAUDE.mdとgitステータスを読み飛ばして高速・低コストに調査します。general-purposeは全ツールを持ち、探索と変更の両方を要する複雑な作業向けです。これらと違い、カスタムサブエージェントは独自のシステムプロンプトとツール制限を自分で決められる点が本質です。
Markdownファイルとフロントマターでカスタムサブエージェントを定義する
定義はYAMLフロントマター（先頭の設定ブロック）と本文のシステムプロンプトという単純な構成です。
---
name: code-reviewer
description: コード変更後のレビュー専門。変更直後に使用。
tools: Read, Grep, Glob, Bash
model: sonnet
---
あなたはコードレビューの専門家です。品質と
セキュリティの観点で具体的な指摘を返します。EC-CUBEやLaravelの開発では、テスト失敗の原因調査をサブエージェントに任せると効果的です。詳細なスタックトレースやログをサブエージェント側に閉じ込め、メイン会話には原因と修正方針だけを返させます。軽い作業なのでhaikuへ回してコストを抑えるのも有効です。
---
name: test-debugger
description: テスト失敗やエラーの原因調査専門。テストがコケたら使用。
tools: Read, Grep, Glob, Bash
model: haiku
---
あなたはデバッグの専門家です。エラーを分析し、
根本原因を特定して修正案を返します。WordPressプラグインやテーマのように読み解くファイルが多いコードベースでは、既存実装の調査をサブエージェントへ切り出すと、探索で膨らむ出力をメイン会話から追い出せます。変更させたくないのでtoolsを読み取り専用に絞るのがポイントです。
---
name: codebase-explorer
description: 既存実装の調査と該当箇所の特定専門。変更前の調査で使用。
tools: Read, Grep, Glob
model: sonnet
---
あなたはコードベース調査の専門家です。関連ファイルを探し、
実装の要点だけを要約して返します。必須のname・descriptionと、tools・modelで権限を絞る書き方
まず用意するのはname（サブエージェントを識別する名前。:を含む名前は使えません）とdescriptionです。toolsを明示しなければ権限を絞れないので、レビュー用途ならRead系だけに絞り、WriteやEditを外しておきます。modelを明示すれば使うモデルを固定でき、軽い作業をhaikuへ回せばコストを抑えられます。
保存場所（プロジェクト／ユーザー）で変わる適用範囲と優先順位
.claude/agents/に置けばそのプロジェクト限定、~/.claude/agents/なら全プロジェクトで使えます。同名が衝突した場合はプロジェクト側が優先されます。チームで共有しながら改善していくなら、プロジェクト側に置いてバージョン管理へコミットするのが実務では扱いやすい選択です。
作成したサブエージェントを実際に委譲・呼び出しする手順
呼び出し方は3通りあり、確実性の低い順に使い分けます。
- 自然言語で名前を挙げる（例「code-reviewerで最近の変更を見て」）。委譲するかはClaudeが判断します
@メンションで名前を指定して呼び出せます。@メンションの入力補完には、登録済みのサブエージェントが状態とともに表示されますclaudeの起動オプションでサブエージェントを指定し、セッション全体をそのエージェントとして動かす方法もあります
自動委譲・@メンション・–agentの3パターンの使い分け
普段は自然言語で任せ、確実に特定のエージェントへ通したいときだけ@メンションへ上げる、という段階運用が現実的です。レビュー専用のセッションを丸ごと立てたい場合に限り--agentを使います。
意図したサブエージェントが呼ばれないときに疑うべきdescriptionの書き方
委譲の判断材料はdescriptionです。曖昧だと呼ばれないので、いつ使うかを具体的に書き、積極的に委譲させたいなら「変更直後に使用」「use proactively」といった発火条件を明記します。作ったのに見つからない場合、まず疑うべきは配置のタイミングです。セッション開始後に新しくagentsディレクトリを作るとファイル監視が追いつかず認識されないため、Claude Codeを再起動すれば読み込まれます。
EC-CUBE公式パートナー 