背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

1. これは一言でいうと何か

サブエージェントは、特定種類のタスクを専門に処理するAIアシスタントです。使いどころは明快で、サイドタスクが検索結果・ログ・二度と参照しないファイル内容でメイン会話を溢れさせるときに使います。サブエージェントはそのタスクを独自のコンテキストウィンドウで実行し、メイン会話には概要だけを返します。同じ種類のワーカーを同じ指示で繰り返し生成するなら、カスタムサブエージェントとして定義します。

役立つのは主に5点です。探索と実装を分けてコンテキストを保持する、使えるツールを制限して制約を強制する、設定を再利用する、焦点を絞ったシステムプロンプトで挙動を特化する、Haiku のような速く安いモデルへタスクを回してコストを抑える、です。

2. どういう場面で役立つか

Claude Code には組み込みのサブエージェントがあり、適切なときに自動的に使われます。まずこれを知っておくと選び分けが楽になります。

• コードベースの調査：Explore は読み取り専用の高速エージェントで、Write / Edit は拒否されます。CLAUDE.md と git ステータスを読み込まないため軽量です。変更せずにコードを検索・理解したいときに委譲されます。
• Plan Mode 中の情報収集：Plan が読み取り専用で探索し、探索結果を別ウィンドウに留めます。
• 探索と変更の両方が要る複雑なタスク：general-purpose が全ツールを持って対応します。

カスタムで作る典型シーンは次のとおりです。

• 大量出力を分離する：テスト実行やログ処理は大量にコンテキストを食います。サブエージェントに委譲すれば、詳細はサブエージェント側に残り、失敗したテストと理由だけが返ります。
• 読み取り専用に固定したいレビュー役：ツールを Read / Grep / Glob に絞ったコードレビュアーを定義できます。
• 並行調査：認証・DB・API を別々のサブエージェントで同時に調べさせ、結果を統合します。

向かないケース・不要なケース。

1. 頻繁なやり取りや反復改善が要るタスク、複数フェーズが重要なコンテキストを共有する場合、素早い小変更、レイテンシが重要な場合はメイン会話が向きます（サブエージェントは新規に開始しコンテキスト収集に時間がかかります）。
2. メイン会話で実行される再利用ワークフローが欲しいだけなら、分離コンテキストのサブエージェントではなくスキルを検討します。
3. 会話に既にある内容への簡単な質問は、サブエージェントではなく /btw が適します(ツールなしで答え、履歴に残しません)。

3. コード・コマンドの実例と解説

前提条件

• サブエージェントは YAML フロントマター＋Markdown 本体のファイルで、本体がそのままシステムプロンプトになります。必須フィールドは name と description の2つだけです。
• 置き場所でスコープが決まります。優先度は 管理設定 > --agents(セッション限定) > .claude/agents/(プロジェクト) > ~/.claude/agents/(全プロジェクト) > プラグイン、の順です。
• description が委譲の判断材料です。Claude はこの説明を見て委譲するか決めるので、いつ使うかを明確に書きます。積極的に使わせたいなら「use proactively」のような句を入れます。
• ファイルの追加・編集は数秒で反映され再起動は不要です（ただしセッション開始時に存在しなかった agents ディレクトリを新設した初回だけ再起動が必要）。

最小のサブエージェントを書く

---
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.

これを .claude/agents/（プロジェクト用）か ~/.claude/agents/（全プロジェクト用）に置きます。tools を挙げると使えるツールをその集合に絞れます（省略時は全ツールを継承）。model は sonnet / opus / haiku / fable / 完全なモデルID / inherit を取り、デフォルトは inherit（メイン会話と同じ）です。本体はエージェント自身のシステムプロンプトで、Claude Code の完全なシステムプロンプトは渡りません。

ツールを絞る（許可リストと拒否リスト）

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

tools は許可リストです。上の例は Read / Grep / Glob / Bash だけを許し、ファイル編集も書き込みも MCP も使えません。逆に「Write と Edit だけ外して他は全部継承」したいなら disallowedTools: Write, Edit を使います。両方を指定した場合は disallowedTools が先に効き、残りに対して tools が解決されます。mcp__<server> のようなサーバー単位のパターンも受け付けます。

権限モードを与える

---
name: db-reader
description: Execute read-only database queries
tools: Bash
permissionMode: default
---

permissionMode は default / acceptEdits / auto / dontAsk / bypassPermissions / plan を取ります。ただし非対称な継承ルールに注意してください。親が bypassPermissions や acceptEdits を使っている場合は親が優先され、サブエージェント側で上書きできません。親が自動モードなら、サブエージェントも自動モードを継承し、フロントマターの permissionMode は無視されます。bypassPermissions はすべての権限チェックを飛ばすため慎重に扱ってください。

動的なガードレールはフックで

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

tools の粒度では足りない「一部の操作だけ許す」制御は、PreToolUse フックで実現します。前回（第7回）どおり、スクリプトが stdin の JSON からコマンドを取り出し、書き込み系 SQL を見つけたら exit 2 でブロック（stderr が Claude へのフィードバック）します。フックはそのサブエージェントがアクティブな間だけ実行され、終了時にクリーンアップされます。

明示的に呼び出す

# セッション全体をそのサブエージェントとして実行する
claude --agent code-reviewer

自動委譲が不十分なときは、3段階でエスカレートできます。プロンプトで名前を出す（Claude が委譲を判断）、@"code-reviewer (agent)" の @メンション（そのサブエージェントの実行を保証）、そして上の --agent（セッション全体がそのシステムプロンプト・ツール制限・モデルを採用）です。プロジェクト既定にするなら .claude/settings.json に "agent": "code-reviewer" を置きます。

その他（全フロントマターフィールド一覧、skills のプリロード、memory による永続メモリ、isolation: worktree、--agents の JSON 定義、SubagentStart/SubagentStop フック、ネストされたサブエージェント、/fork、再開・自動圧縮、Agent(agent_type) による生成制限、permissions.deny での無効化、コードレビュアー・デバッガー・データサイエンティストなどの完成例）は公式ドキュメントを参照してください。

4. まとめと次回予告

• サブエージェントは「独自コンテキストで動き、概要だけ返す」ワーカー。大量出力の分離と、ツール制限の強制に効きます。
• 組み込みの Explore / Plan（読み取り専用・CLAUDE.md と git を読まない）/ general-purpose を先に把握すると選び分けが早いです。
• 必須は name と description のみ。description が委譲の判断材料になります。

押さえておくべき挙動を2点。 まずスタートアップで何が読み込まれるかです。非フォークのサブエージェントは新しい分離コンテキストで始まり、会話履歴も既読ファイルも見えません。Claude が作る委譲メッセージから動きます。CLAUDE.md とメモリ階層は読み込まれますが、Explore と Plan だけはこれと git ステータスをスキップします。だから「vendor/ は無視」のような必須ルールは、委譲時のプロンプトで改めて伝えるのが安全です。

もう1点、権限の継承は緩められない方向にだけ働きます。親の bypassPermissions / acceptEdits / 自動モードはサブエージェント側で上書きできません。制限を厳しくはできても、親が許す範囲を超えて緩めることはできない、という設計です。

次回予告：ここまでの拡張機能をまとめて配布する「プラグイン」を取り上げます。

関連ページ（本記事で触れた概念の詳細）：コンテキスト節約の可視化と圧縮 →「コンテキストウィンドウ」、PreToolUse と終了コード →「Hooks」、skills プリロードと context: fork の対比 →「Skills」、permissionMode の各モード →「権限モード」、isolation: worktree →「worktree」、並行・通信するエージェント →「バックグラウンドエージェント」「エージェントチーム」、配布 →「プラグイン」。

---

本記事は執筆時点の公式ドキュメント（カスタムサブエージェントの作成）に基づきます。最新は公式ドキュメントをご確認ください。