Claude Code 使い方ガイド：サブエージェントの仕組みと使いどころ

サブエージェントとは、Claudeに委任する関数のようなものです。Claudeが仕事を渡すと、ユーザーには見えない別のウィンドウで処理し、整理された答えを1つだけ返します。適切に使えば、数時間に及ぶセッションでもClaude Codeの一貫性を守る強力な手段になります。使い方を誤れば、得るものがないままトークンと待ち時間だけが増えます。本稿では、その正確な仕組み、定義ファイル、そしてサブエージェントを使う価値が本当にある場面を率直に解説します。

Claude Code 使い方の要点：20秒でわかるサブエージェント

サブエージェントは、独立したコンテキストで完結した補助タスクを実行し、短い要約をメインの会話へ返します。要点はこれだけです。エージェントを使う長いセッションでは、grepの結果、ビルドログ、一度読んだきりのファイルなどのノイズがたまり、モデルは作業そのものより情報整理に多くの注意を割くようになります。サブエージェントは、この問題を解決するためにあります。

ノイズの多い処理をサブエージェントへ移せば、その途中経過は隔離されたままです。メインスレッドに届くのは結論だけです。したがって、「AIエンジニアのチームが共同作業する仕組み」と考えるのは適切ではありません。正しくは、戻り値を伴うコンテキスト整理です。この捉え方を押さえれば、サブエージェントに関するほかの判断も迷いにくくなります。

サブエージェントの実体

サブエージェントは、専用のシステムプロンプト、指定されたツール、独立した権限を持ち、固有のコンテキストウィンドウで動きます。Claudeがサブエージェントの役割に合うタスクを見つけると処理を委任し、サブエージェントは単独で作業して結果を返します。これが公式の定義であり、重要なのは固有のコンテキストウィンドウと結果を返すという2点です。

多くの解説が取り違えているポイントがあります。サブエージェントは何もない状態から始まります。会話履歴も、Claudeがすでに読んだファイルも、呼び出し済みのスキルも見えません。Claudeはタスクを要約した短い委任メッセージを作り、サブエージェントは自身のシステムプロンプトと、作業ディレクトリなどの基本的な環境情報だけを頼りに進めます。完全なClaude Codeのシステムプロンプトは渡されません。完了時に戻るのも要約だけです。

この分離には、利点と代償の両方があります。

• 利点： 読み込んだ12個のファイル、失敗したgrep、調査したログといった冗長な途中経過が、メインのコンテキストに一切入りません。ノイズなしで答えだけを受け取れます。
• 代償： メイン側ではすでに把握している情報も、サブエージェントは自力で集め直す必要があります。会話履歴がなければ理解できないタスクを渡すと、うまく進められません。

Claude Code サブエージェントの定義ファイル

カスタムサブエージェントは、YAMLフロントマター付きのMarkdownファイルで定義します。フロントマターが設定、その後のMarkdown本文がサブエージェントのシステムプロンプトになります。必須フィールドはnameとdescriptionの2つだけです。

---
name: code-reviewer
description: Reviews code for quality and best practices. Use immediately after writing or modifying code.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. When invoked, run git diff to see recent
changes, focus on modified files, and review for clarity, naming, error
handling, exposed secrets, input validation, and test coverage. Group your
feedback by priority: critical issues, warnings, then suggestions.

これだけで、実際に動くサブエージェントが完成します。descriptionは単なる説明文ではありません。Claudeはこれを読んで、いつ委任するかを判断します。「コードをレビューする。コードの作成または変更後、すぐに使う」と明記すれば適切なタイミングで呼び出されますが、「コード支援」のように曖昧だと出番がないままです。専門職の求人票を書くつもりで、役割を具体化してください。

ファイルを手作業で書く必要はありません。Claude Codeでは、/agentsコマンドを実行するとサブエージェント管理用のタブ画面が開きます。稼働中および最近完了したサブエージェントを一覧表示し、開いたり停止したりできるRunningタブと、作成・編集・整理を行うLibraryタブがあります。注意したいのは、サブエージェントがセッション開始時に読み込まれる点です。ディスク上のファイルを直接編集した場合、変更を反映するにはセッションを再起動する必要があります。一方、/agents画面で作成または編集した内容は、すぐに有効になります。

サブエージェントの保存場所と優先順位

同じサブエージェントファイルでも、置く場所によって利用できる範囲が変わります。同名の定義が競合したとき、どれが優先されるかも配置場所で決まります。

同名のサブエージェントがある場合は、優先度の高い場所の定義が使われます。管理対象、プロジェクト、ユーザーの順です。プロジェクトのサブエージェントは作業ディレクトリから上位へたどって検出され、v2.1.178以降は同名なら作業ディレクトリに最も近い定義が優先されます。セッション限定の方法もあります。Claude Codeの起動時に--agentsフラグでサブエージェントをJSONとして渡せば、ディスクへ保存せず、そのセッションだけで利用できます。自動化スクリプトや簡単なテストに便利です。

実務上の判断はシンプルです。このコードベース固有のレビュー方法やテスト手順を持つサブエージェントは.claude/agents/に置き、バージョン管理へ含めてチーム全員で共有します。自分個人の作業スタイルを反映するものは~/.claude/agents/に置けば、どのプロジェクトでも使えます。

モデルとツール：効果を左右する2つの設定

実際の効果を大きく左右するフロントマターのフィールドは2つです。ここを適切に設定すると、サブエージェントは「面白い機能」から、費用対効果の高い実用機能へ変わります。

モデル。 modelフィールドには、エイリアス（sonnet、opus、haiku、fable）、claude-opus-4-8のような完全なモデルID、またはinheritを指定できます。省略時はinheritとなり、メインの会話と同じモデルが使われます。これは見落とされがちなコスト調整機能です。「コードベースをgrepして結果を要約する」だけのサブエージェントに、最上位モデルは必要ありません。model: haikuにすれば、反復的な作業は安価で高速なモデルに任せ、メインセッションでは判断が必要な処理にOpusを使い続けられます。

ツール。 デフォルトでは、サブエージェントはメインの会話で利用できるすべての内部ツールとMCPツールを引き継ぎます。権限を絞る方法は2つあります。toolsは許可リストで、指定したツールだけを使えるようにします。disallowedToolsは拒否リストで、指定したもの以外を許可します。ファイルを変更させたくない調査用サブエージェントなら、tools: Read, Grep, Glob, Bashを設定すれば物理的に編集できません。これは単なる整理ではなく、実効性のある安全境界です。読み取り専用のレビュアーが、レビュー対象を誤って書き換えることはありません。

もう1つ覚えておきたい設定が、isolation: worktreeです。サブエージェントを一時的なgit worktree、つまりリポジトリの隔離コピーで実行します。変更がなければ、そのコピーは自動的に片付けられます。作業ツリーに影響を与えず、リスクのある処理を試させたいときに適しています。

サブエージェントを使うべき場面、使わない場面

GitHubに並ぶ設定例では省かれがちですが、実際に時間と費用を節約するうえで最も重要な判断です。サブエージェントの実行にもコストがかかるため、「使えるか」ではなく「分離する価値がコストを上回るか」を考える必要があります。

反対に、仕組み上サブエージェントが向かないケースもあります。

• 何度もやり取りしながら進める作業。 頻繁な修正とユーザーの判断が必要なら、メインの会話で続けるべきです。委任すると、その対話のループが途切れます。
• コンテキストを共有する工程。 計画、実装、テストの各段階が前の内容を引き継ぐなら、1つのスレッドで進めるのが適切です。それぞれ白紙から始まる3つのサブエージェントへ分けるべきではありません。
• 小さく明確な変更。 誤字を1つ直すためにサブエージェントを起動すると、修正そのものよりコストがかかります。
• 待ち時間を最小限にしたい作業。 サブエージェントは白紙から情報を集めるため、開始にも時間がかかります。答えが今すぐ必要なら、メインで直接処理する方が速くなります。

サブエージェント、スキル、フォーク、エージェントチームの違い

Claude Codeには現在、作業を構成する方法が4つあり、混同しやすくなっています。違いを決めるのは、コンテキストの扱いです。

特に迷いやすいのがスキルとサブエージェントです。どちらも「保存した専門知識」のように見えるからです。スキルは、再利用可能な指示をメインの会話コンテキスト内で実行するため、進行中の内容をすべて把握しています。サブエージェントは正反対で、分離されること自体が目的です。渡したタスク以外は何も見えません。作業を続けながらClaudeにチーム独自のスタイルを適用させるならスキルです。大量の調査を見えない場所で進め、結果だけを受け取りたいならサブエージェントです。

フォークは、その中間にある便利な選択肢です。それまでの会話全体、つまり同じシステムプロンプト、ツール、モデル、メッセージ履歴を継承するため、説明をやり直す必要がありません。一方、フォーク先のツール呼び出しはメインのコンテキストに入らず、最終結果だけが戻ります。固有名を持つサブエージェントへ渡すには背景情報が多すぎる場合に、フォークを使います。（フォークモードはCLAUDE_CODE_FORK_SUBAGENT環境変数で有効になります。）

高度な機能と、知っておくべき限界

比較的新しい2つの機能により、サブエージェントはさらに強力になりました。ただし、どちらにも無視できない制約があります。

ネスト。 Claude Code v2.1.172以降、サブエージェントは自分のサブエージェントを起動できます。レビュアー役のサブエージェントが、指摘ごとに検証役を割り当てても、途中経過はすべて内側に隔離されます。メインへ届くのは、最上位サブエージェントの要約だけです。深さには固定の上限があり、5階層までです。変更はできず、深さ5のサブエージェントにはAgentツールが渡されないため、それ以上は起動できません。この上限には理由があります。深い階層から処理が扇状に広がると、意図せず大量のエージェントを動かし、トークン消費が急増します。深さは目標値ではなく、予算として扱ってください。

メモリ。 memory: project（またはuser、local）を追加すると、サブエージェントはセッションをまたいで読み書きできる永続メモリディレクトリを持ちます。projectメモリを持つコードレビュアーなら、コードベースの慣例や繰り返し起きる問題を蓄積し、使うほど精度を高められます。バージョン管理で共有できるため、推奨されるデフォルトはprojectです。メモリを有効にすると、Claude Codeは起動時にサブエージェントのシステムプロンプトへMEMORY.mdの先頭200行（または25KB）を挿入します。このファイルは内容を選別し、簡潔に保ってください。

最初の一歩としては、目的を1つに絞ったサブエージェントを作るのが効果的です。定番は、読み取り専用のcode-reviewerです。.claude/agents/に置いてバージョン管理へ含め、変更のたびに実行します。価値を確認できたら、次に安価なモデルを使う調査用サブエージェントを追加します。成果を出しているチームは、30個のエージェントを動かしているのではありません。それぞれ1つの役割を確実にこなす3個を使っています。まずコーディングツール自体を選んでいる段階なら、別の判断が必要です。Codex、Claude Code、Cursorの比較と、より広く比較したおすすめのAIコーディングエージェントを参照してください。

Claude Codeを実際の開発・リリース工程へ組み込む方法は、私が普段から主に扱っているテーマです。公開直後の話題ではなく、現場で機能する運用方法を知りたい方は、ニュースレターに登録してください。