10 サブエージェント(Subagents)

更新日: 2026-10-25

特定の種類の作業を担当する専門のAIアシスタント。自分専用のコンテキストウィンドウ・システムプロンプト・使えるツール・権限を持ち、作業後は要約だけをメインの会話に返す。
使いどころ: 脇道の作業(大量の検索結果・ログ・ファイル内容)でメインの会話が埋まりそうな時。

メリット:

コンテキスト節約(調査の中身はメインに入らない)
制約をかけられる(読み取り専用など)
再利用(ユーザーレベルで全プロジェクト共通)
専門化(特化したシステムプロンプト)
コスト削減(Haiku など安いモデルに回せる)
※ サブエージェントのリクエストも同じ利用上限にカウントされる

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

名前	内容
Explore	高速・読み取り専用のコード探索。Claude が quick / medium / very thorough の深さを指定。CLAUDE.md は読まない
Plan	プランモード中の調査用。読み取り専用
general-purpose	調査と変更の両方が必要な複雑な作業。全ツール
claude	汎用のキャッチオール。バックグラウンドセッションの既定
statusline-setup	`/statusline` 設定用
claude-code-guide	Claude Code の使い方の質問に答える

作り方

/agents の作成ウィザードは廃止(v2.1.198〜)。Claude に頼むか、ファイルを直接書く。

~/.claude/agents/ に個人用の code-improver サブエージェントを作って。
可読性・性能・ベストプラクティスの観点でファイルを調べて改善案を出す。
読み取り専用で Sonnet を使うこと。

生成されるファイル ~/.claude/agents/code-improver.md:

---
name: code-improver
description: 可読性・性能・ベストプラクティスの改善を提案する。コードを書いた/変更した後に使う。
tools: Read, Grep, Glob
model: sonnet
---
あなたはコード改善の専門家です。各問題について、問題点・現在のコード・改善版を示してください。

置き場所(優先度順)

場所	範囲
管理設定	組織全体(最優先)
`--agents` CLIフラグ(JSON)	そのセッションだけ
`.claude/agents/`	このプロジェクト(コミットでチーム共有)
`~/.claude/agents/`	自分の全プロジェクト
プラグインの `agents/`	プラグイン有効時

主なフロントマター

項目	意味
`name` / `description`	必須。description で Claude が委任先を判断(「use proactively」と書くと積極的に使われる)
`tools` / `disallowedTools`	使えるツールの許可/除外
`model`	`sonnet` `opus` `haiku` `fable` `inherit` など
`permissionMode`	権限モード
`maxTurns`	最大ターン数
`skills`	起動時に全文を読み込むスキル(最大32個)
`mcpServers`	このサブエージェント専用の MCP
`hooks`	このサブエージェント実行中だけの Hooks
`memory`	永続メモリ(`user` / `project` / `local`)。`.claude/agent-memory/<名前>/` などに学びを蓄積
`isolation: worktree`	一時的な git worktree で隔離して作業
`background: true`	常にバックグラウンド実行
`effort` `color` `omitClaudeMd` `initialPrompt`	思考量、表示色、CLAUDE.md を読まない(管理ポリシーの CLAUDE.md は読む)、初回プロンプト
`autoCompactWindow`	このサブエージェントの自動コンパクションの閾値(v2.1.296〜)

呼び出し方

自然言語: 「test-runner サブエージェントで失敗テストを直して」(Claude が判断)
@メンション: @"code-reviewer (agent)" 認証の変更を見て(確実にそのエージェントを使う)
セッション全体: claude --agent code-reviewer、または設定 "agent": "code-reviewer"(メインのスレッド自体がそのエージェントになる)
自動: Claude が description を見て自分で委任

フォアグラウンド / バックグラウンド

フォアグラウンド: 終わるまでメインが待つ。権限確認はそのまま表示
バックグラウンド: 並行して動く。権限確認はメインに「どのサブエージェントが聞いているか」付きで表示
Ctrl+B で実行中のタスクをバックグラウンドへ、/tasks で一覧
対話セッションでは既定で「フォークモード」ON → サブエージェントはバックグラウンドで動く
v2.1.302 から、フォーク型サブエージェントは claude -p・Agent SDK・デスクトップ・VS Code でも既定で有効(OFF: CLAUDE_CODE_FORK_SUBAGENT=0)。デスクトップと VS Code ではメインのサブエージェントは常にバックグラウンド、-p と SDK では既定でフォアグラウンド

フォーク(会話を引き継ぐサブエージェント)

通常のサブエージェントはまっさらから始まる。フォークは今までの会話を全部引き継ぐ
説明し直さずに脇作業を任せられる。途中のツール呼び出しはメインに入らず、結果だけ戻る
/subtask 今までのパーサー変更の単体テストを下書きして
下のパネルで ↑↓ 選択、Enter で中身を見て追加指示、x で停止

よくある使い方

大量出力の隔離: 「サブエージェントでテストスイートを実行して、失敗したテストとエラーだけ報告して」
並列調査: 「認証・DB・APIモジュールを別々のサブエージェントで並行調査して」
連鎖: 「code-reviewer で性能問題を見つけ、optimizer で直して」
検証: 実装後に別のサブエージェントでレビュー(作った本人に採点させない)
思考量を変える: Claude はサブエージェントを呼ぶ時に effort を指定できる(軽い調査は low、難しい検証は high など)

メインの会話とどちらを使う?

メイン: 何度もやり取りが必要、複数フェーズで文脈を共有、素早い小修正
サブエージェント: 出力が多く中身は不要、ツール制限をかけたい、自己完結して要約を返せる作業
※ サブエージェントはさらにサブエージェントを起動できる(既定でメインから3階層まで。CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で変更)。例: レビュー担当が指摘ごとに検証担当を並列起動