Claude Code のサブエージェント入門：専用の担当を作って、会話を散らかさない

サブエージェントとは

サブエージェントは、特定の種類の作業を担当する専用のアシスタントです。それぞれが次のものを独立して持ちます。

• 自分だけの文脈（コンテキストウィンドウ）
• 自分用のシステムプロンプト
• 使えるツールの範囲
• 独立した権限

作業の途中で大量の検索結果やログ、ファイルの中身が出て、あとで参照しないなら、サブエージェントに任せて要約だけを受け取ると、主会話が圧迫されません。なお、サブエージェントの利用も、主会話と同じ利用上限に数えられます。

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

名前	役割
Explore	読み取り専用。ファイルの探索、コード検索、コードベースの調査。調べる深さを quick / medium / very thorough から選べる
Plan	プランモード中の調査用。読み取り専用
general-purpose	探索と変更の両方が必要な、複雑で多段階の作業。全ツールが使える
statusline-setup	/statusline を設定するとき
claude-code-guide	Claude Code の機能について質問したとき

Explore と Plan は、CLAUDE.md と git status を読み込みません。また、ひと呼吸で終わる作りなので、あとから続きを頼むことはできません。続けたいときは、general-purpose かカスタムのサブエージェントを使います。

定義ファイルを書く

サブエージェントは、YAML の frontmatter と Markdown の本文でできたファイルで定義します。本文がそのままシステムプロンプトになります。

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

必須の項目は name と description だけです。description は、Claude が「いつ、この担当に任せるか」を判断する材料になります。自動で任せてほしいときは、description に「use proactively」のような言い回しを入れるよう案内されています。

主な frontmatter の項目

項目	内容
tools	使えるツール。省略すると、使えるツールをすべて引き継ぐ
disallowedTools	使わせないツール
model	sonnet、opus、haiku、fable、モデルID、inherit のいずれか
permissionMode	default、acceptEdits、auto、dontAsk、bypassPermissions、plan など
maxTurns	動かせる最大のターン数
skills	起動時に全文を渡すスキル
mcpServers	このサブエージェント専用の MCP サーバー
hooks	このサブエージェントの実行中だけ動くフック
memory	永続メモリの範囲（user、project、local）
isolation	worktree にすると、一時的な git worktree で動く

項目名は camelCase で完全に一致させる必要があり、知らない項目は警告なしに無視されます。

置き場所と優先順位

同じ名前のものがあるときは、上にあるほうが優先されます。

順位	場所	範囲
1	管理者が配る設定	組織全体
2	--agents フラグ	起動したセッションだけ
3	.claude/agents/	そのプロジェクト
4	~/.claude/agents/	すべてのプロジェクト
5	プラグインの agents/	プラグインが有効な間

プロジェクトの .claude/agents/ をリポジトリに入れれば、チームで同じ担当を共有できます。作業中に追加・編集したファイルは数秒で検出されますが、セッションの開始時に存在しなかった agents フォルダを新しく作ったときは、再起動が必要です。

作り方

公式ドキュメントが勧めるのは、Claude に頼む方法です。作りたい内容と保存先を、文章で伝えます。

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

できたら、ファイルを開いて frontmatter が依頼どおりか確かめます。手で .md ファイルを書いてもかまいません。

呼び出し方

• 自動で任せる：依頼の内容と各サブエージェントの description から、Claude が選びます。
• 名前を挙げる：「test-runner サブエージェントで失敗しているテストを直して」のように頼みます。ただし、任せるかどうかは Claude が判断します。
• @ で確実に呼ぶ：@"code-reviewer (agent)" 認証まわりの変更を見て のように書くと、そのサブエージェントが確実に使われます。
• セッション全体を担当にする：claude --agent code-reviewer で起動するか、settings.json に "agent": "code-reviewer" と書きます。

並列で使う

独立した調査は、並列に走らせられます。

認証、データベース、API の各モジュールを、別々のサブエージェントで並列に調べて

順番につなぐ使い方もできます。「code-reviewer で性能の問題を見つけて、そのあと optimizer で直して」といった頼み方です。

気をつける点

• 文脈は引き継がれない：サブエージェントは、会話の履歴や、すでに読んだファイルを知りません。「vendor/ は無視する」のような決まりは、頼むときの文章に書き直します。
• 結果が主会話に戻る：詳しい結果を返すサブエージェントを大量に走らせると、主会話の文脈を大きく使います。
• 同時実行は既定で20まで：超えると失敗します。環境変数 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で変えられます。
• 入れ子は既定で3層まで。
• プラグイン由来の制限：プラグインのサブエージェントでは、hooks、mcpServers、permissionMode は安全のため無視されます。必要なら .claude/agents/ にコピーします。
• 読み込まれないファイル：name や description がない、frontmatter の書き出しが先頭行にない、YAML として読めない、のいずれかだとスキップされます。

どこから始めるか

最初は、読み取り専用のレビュー担当（tools: Read, Glob, Grep）を1つ作ると、効果が見えやすいでしょう。慣れたら、テスト実行やログ調査など、「出力が多いけれど、結果は要約で十分」な作業を切り出していくのが向いています。