Claude Code サブエージェントの使い方｜作成・設定・活用パターンまとめ

Claude Code で作業していると、こんな場面に出くわしませんか？

• テストを全部回したいけど、出力が大量すぎてコンテキストが埋まる
• コードレビューは毎回同じ観点でチェックしたい
• データベースを触るときは SELECT だけに制限したい

こういった「決まったパターンの作業」を毎回メインの会話で処理していると、コンテキストウィンドウがすぐに圧迫されてしまいます。

そこで活躍するのがサブエージェントです。

サブエージェントは、メインの会話から独立したコンテキストウィンドウで動く「専門家」のようなものです。独自のシステムプロンプト、使えるツールの制限、権限設定を持ち、タスクが終わったら結果だけをメインの会話に返してくれます。

つまり、「テスト担当」「レビュー担当」「DB 調査担当」といった専門チームを Claude Code の中に作れるというわけです。

スキルとの違い： スキルはメインの会話コンテキスト内で動くプロンプトの拡張です。一方サブエージェントは、独立したコンテキストで動くため、大量の出力を隔離したり、ツールを制限したりできます。用途が違うので、使い分けが大切です。

Claude Code に最初から入っているサブエージェント

カスタムサブエージェントを作る前に、まず組み込みのものを把握しておきましょう。Claude は状況に応じてこれらを自動的に使い分けています。

Explore（探索エージェント）

コードベースの検索・分析に特化した、読み取り専用の高速エージェントです。

• モデル: Haiku（高速・低コスト）
• 使えるツール: 読み取り系のみ（Write / Edit は使えない）
• 用途: ファイル検索、コード理解、依存関係の調査

Claude が「コードを読んで理解するだけでいい」と判断したとき、自動的に Explore に委譲します。探索結果はサブエージェント側のコンテキストに留まるため、メインの会話が汚れません。

Plan（計画エージェント）

プランモード（/plan）中に、実装計画を立てるための下調べをするエージェントです。

• モデル: メイン会話と同じ
• 使えるツール: 読み取り系のみ
• 用途: 計画策定のためのコードベースリサーチ

General-purpose（汎用エージェント）

探索と実行の両方が必要な、複雑なマルチステップタスク向けです。

• モデル: メイン会話と同じ
• 使えるツール: すべて
• 用途: 複数ステップにまたがる調査・修正作業

たとえば「バグの原因を特定して修正して」のように、調べることと直すことの両方が必要な場面で使われます。

Tip: これらの組み込みエージェント以外にも、Bash、statusline-setup、Claude Code Guide といったヘルパーエージェントがあります。これらは特定の操作時に自動で呼ばれるため、普段意識する必要はありません。

カスタムサブエージェントを作ってみよう

ここからが本題です。自分だけの専門エージェントを作る方法を、ステップバイステップで紹介します。

方法 1：/agents コマンドで対話的に作る（おすすめ）

一番簡単な方法です。Claude Code で /agents と入力するだけで、対話的なセットアップが始まります。

手順：

1. /agents を実行
2. Create new agent を選択
3. スコープを選ぶ（User-level か Project-level）
4. Generate with Claude を選んで、やりたいことを説明する
5. ツール・モデル・背景色を設定して保存

たとえば、こんなふうに説明します：

TypeScriptプロジェクトのコードを分析して、型の使い方や
パフォーマンスの改善点を指摘するエージェントを作って。
改善案にはbefore/afterのコード例を含めてほしい。

Claude がシステムプロンプトと設定を自動生成してくれます。保存した瞬間から使えるようになるので、再起動は不要です。

方法 2：マークダウンファイルを手書きする

サブエージェントの実体は、YAML フロントマター付きのマークダウンファイルです。中身を完全にコントロールしたい場合はこちら。

---
name: ts-improver
description: TypeScriptコードを分析し、型安全性とパフォーマンスの改善を提案する
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたは TypeScript の専門家です。コードを分析して、以下の観点で改善点を報告してください。

## チェック観点
1. **型の安全性** — any の使用、型アサーションの乱用、union 型の網羅チェック漏れ
2. **パフォーマンス** — 不要な再レンダリング、メモ化の欠如、N+1 クエリ
3. **可読性** — 長すぎる関数、ネストが深い条件分岐、命名の曖昧さ

## 出力フォーマット
各指摘について以下を含めてください：
- 問題の説明（なぜ良くないか）
- 該当コード（before）
- 改善案（after）
- 優先度（高・中・低）

ファイルの保存先でスコープが決まります：

注意： ファイルを手動で追加した場合、セッションを再起動するか /agents を実行して読み込む必要があります。

方法 3：CLI フラグでその場限りのエージェントを作る

自動化スクリプトや CI/CD で一時的に使いたい場合は、--agents フラグで JSON を渡せます。

claude --agents '{
  "lint-checker": {
    "description": "リンターを実行して結果を報告する",
    "prompt": "プロジェクトのリンターを実行し、エラーと警告を重要度順にまとめてください。",
    "tools": ["Bash", "Read"],
    "model": "haiku"
  }
}'

このエージェントはそのセッション中だけ存在し、ディスクには保存されません。