Claude Code subagentとは｜仕事を分ける設計と権限・コストの判断軸

Claude Codeを本格的に使い始めると、ひとつの会話に調査ログ、テスト結果、実装の履歴が積み上がっていきます。本題に戻ったときには、最初に立てた方針が会話の奥に埋まっている状態です。

会話を分ければ解決しそうに見えますが、新しい会話には前提が何も残っていません。説明のやり直しが発生し、かえって手間が増えます。subagentが引き受けるのはこの間にある問題で、担当を切り出して別の文脈で走らせ、メインに返すのは要約だけという形をとります。

本記事では、subagentの正体から、どんな分け方が効いてどんな分け方が失敗するのか、定義ファイルの置き場所、権限とツールの絞り込み、コストと実行時間への影響までを、公式ドキュメントで確認できる範囲に限って整理します。

Claude Codeをチームで使い始め、社内の設計や運用ルールを決める立場にある方を想定しています。

記載内容は2026年8月13日時点の公式ドキュメント（code.claude.com/docs）に基づきます。バージョンによって既定値や挙動が変わる項目があるため、実装前に最新版の記述を確認してください。

AI開発環境の設計や社内展開のルールづくりで判断に迷っている場合は、malnaへのご相談も承っています。

Claude Codeのsubagentとは、別のコンテキストで動く担当を切り出す仕組みです

公式ドキュメントはsubagent（サブエージェント）を、特定の種類のタスクを処理する特化したAIアシスタントと説明しています。それぞれが独自のコンテキストウィンドウ、専用のシステムプロンプト、限定されたツールアクセス、独立した権限を持って動きます。メインの会話は依頼を出し、返ってきた結果を受け取るだけの関係になります。

独自のコンテキストで動き、メインには要約だけが返ります

サブエージェントを使う目的として公式が最初に挙げているのは、再度参照しない情報でメインの会話が溢れるのを防ぐことです。検索結果やログ、ファイルの中身といった大量の出力は、判断の材料になったあとに読み返すことがほとんどありません。

フォークを除くサブエージェントは、起動時に真っ白なコンテキストから始まります。公式の記述では、そこに入るのは次のものだけです。

• そのエージェント自身のシステムプロンプトと、Claude Codeが付け足す作業ディレクトリなどの環境情報
• Claudeが仕事を渡すときに書いた依頼文
• CLAUDE.mdの階層（組み込みのExploreとPlanはこれを読み込みません）
• 親セッション開始時点のgitステータスのスナップショット
• フロントマターのskills欄に書かれたスキルの全文

逆に、メインの会話の履歴、出力スタイル、自動メモリは渡りません。コンテキストウィンドウの大きさも親ではなく、そのサブエージェント自身のモデルで決まります。小さい窓のモデルに任せれば、窓もその分小さくなります。

組み込みの担当が最初から用意されています

Claude Codeには、Claudeが状況に応じて自動的に使う組み込みのサブエージェントが含まれています。自分で定義を書く前から分業は始まっているため、まずここを把握しておくと設計の起点になります。

名前	モデル	ツール	役割
Explore	メイン会話から継承（Claude APIではOpusが上限）	読み取り専用。WriteとEditは拒否	ファイル探索、コード検索、コードベースの把握
Plan	メイン会話から継承	読み取り専用。WriteとEditは拒否	プランモードでの調査
general-purpose	メイン会話から継承	サブエージェントが使える全ツール	探索と変更の両方を伴う複雑な作業
claude	メイン会話から継承	サブエージェントが使える全ツール	専門の担当に当てはまらない作業
statusline-setup	Sonnet	ー	/statusline の設定
claude-code-guide	Haiku	ー	Claude Codeの機能に関する質問

ExploreとPlanは、調査を速く安く保つためにCLAUDE.mdと親セッションのgitステータスを読み飛ばします。他の組み込みとカスタム定義はどちらも読み込む仕様です。この差は、社内ルールをCLAUDE.mdに書いている場合に効いてきます。Exploreに守らせたい前提があるなら、委譲時の依頼文に書き直す必要があります。

フォークは、文脈を引き継ぐ例外的な分け方です

フォークは、真っ白から始めるのではなくメインの会話をそのまま引き継いで動くサブエージェントです。同じシステムプロンプト、同じツール、同じモデル、同じ履歴を持つため、状況を説明し直さずに脇の作業を渡せます。

引き換えに、サブエージェント本来の入力の隔離は失われます。それでもフォーク自身のツール呼び出しはメインの会話に流れ込まず、戻るのは最後の結果だけです。名前付きの担当では背景の説明が足りない場合や、同じ出発点から複数の案を並行して試したい場合に向きます。

なお、複数のClaude Codeインスタンスを編成して互いにメッセージを送り合わせるエージェントチームは、subagentとは別の実験的機能として文書化されています。本記事は、ひとつの親から担当を切り出して任せる範囲に絞って扱います。

参考：Orchestrate teams of Claude Code sessions（英語）

仕事を分けると変わるのは、文脈・並行・役割の3点です

サブエージェントに仕事を分ける効果は、コンテキストの分離、依存のない処理の並行実行、役割と道具の固定という3点に集約されます。公式が挙げる利点も、コンテキストの保持、制約の強制、設定の再利用、振る舞いの特化、コストの制御という並びで、この3点と重なります。

探索と実装をメインの会話から外せます

分業の一番わかりやすい見返りは、メインの会話に残るものが減ることです。テストの実行、ドキュメントの取得、ログの処理はいずれも大量の出力を生みますが、必要なのはその結論だけという場合が多くあります。

たとえばテストスイートを走らせる作業を任せ、失敗したテストとエラーメッセージだけを返させれば、数千行の出力はサブエージェント側に残ります。メインには十数行が戻るだけです。判断に使う情報と、判断のために一度だけ見る情報を別の場所に置くという考え方になります。

依存のない調査を同時に走らせられます

独立した調査は、複数のサブエージェントを同時に立てて並べられます。認証、データベース、APIといった別々の領域をそれぞれの担当が調べ、Claudeが戻ってきた結果を突き合わせるという流れです。

ここで条件になるのが依存関係です。公式は、調査の道筋が互いに依存しない場合に最も効くと明記しています。片方の結論を待たないと次に進めない作業を並べても、待ち時間が発生するだけで速くなりません。

役割と使える道具を固定できます

役割を定義ファイルに書いて固定すると、毎回同じ指示を書き直す必要がなくなります。同じ種類の作業を同じ指示で繰り返し立ち上げているなら、そこがカスタム定義の候補です。

道具を絞れる点も、役割の固定と同じ効果を持ちます。レビュー役に書き込み系のツールを渡さなければ、コードを直す判断そのものが選択肢から消えます。指示文で「直さないでください」と伝えるより確実な方法です。

効く分け方は、出力量と依存関係で見分けます

有効な分け方には共通する形があります。出力量が多い作業、他と依存しない作業、立場を分けたい作業の3つです。公式ドキュメントはこれを、大量出力の隔離、並行調査、直列のつなぎというパターンとして整理しています。

出力が大量に出る作業を切り出す

最も効果が大きい使い方として公式が挙げているのは、大量の出力を生む操作の隔離です。テストの実行、外部ドキュメントの取得、ログファイルの処理が代表例になります。

依頼の書き方も結果を左右します。テストを実行してと伝えるだけでは全出力が返りますが、報告する範囲を指定すれば戻る分量も絞られます。分けるだけでなく、返してもらう単位まで決めておくことが設計の一部です。

依存のない調査を並べる

調査対象が複数あって互いに独立しているとき、担当を分けて同時に走らせる形が向きます。モジュールごと、観点ごと、仮説ごとといった切り分け方が考えられます。

一方で、公式は注意も添えています。サブエージェントが終わると結果はメインの会話に返るため、詳細な報告を返す担当を大量に走らせると、それ自体がコンテキストを消費します。並行数を増やせば増やすほど効くという性質のものではありません。

レビュー役を書き込みなしで独立させる

レビューや検査の担当は、ツールを読み取り専用に絞って独立させる形が公式の例に挙がっています。ReadとGrepとGlob、必要ならBashまでを許可し、EditとWriteを外す構成です。

立場を分ける意味は、書いた本人が自分の成果物を検査する構造を避けられることにあります。定義の本文に検査項目を並べ、重要度で分類して返すよう書いておけば、報告の形もそろいます。

工程を直列につないで渡す

複数の工程がある作業は、サブエージェントを順番に使う形に分けられます。各担当が自分の仕事を終えて結果を返し、Claudeが必要な情報を次の担当に渡していく流れです。

公式は、性能の問題を洗い出す担当と、それを直す担当を続けて使う例を示しています。洗い出しの過程で読んだ大量のコードが、修正側のコンテキストに持ち込まれずに済みます。

分けた先でさらに分ける

サブエージェントは、既定で自分のサブエージェントを立てられます。メインの会話から下に3層までという上限が置かれ、上限に達した層からはAgentツールが取り上げられる仕組みです。

入れ子が向くのは、任せた仕事の中がさらに並行の小分けに割れる場合です。指摘ごとに検証担当を立てるレビュー役のような形なら、中間の出力はメインの会話に届きません。戻ってくるのは最上位の担当の要約1本だけになります。上限を変える場合は環境変数 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で層数を指定し、1 にすれば入れ子は無効です。

参考：Manage costs effectively（英語）

うまくいかない分け方には、共通した特徴があります

分けると逆効果になる作業もあります。公式ドキュメントはメインの会話で進めるべき条件を明記しており、頻繁なやり取りが必要な作業、複数の工程が大きな文脈を共有する作業、小さく的を絞った変更、待ち時間が問題になる場面がそこに含まれます。

前提の共有が必要な作業は、説明の手間が増えます

サブエージェントは会話の履歴を引き継ぎません。これまでのやり取りで積み上げた判断や、読み込んだファイルの内容は渡らないため、必要な前提はすべて依頼文に書き直すことになります。

計画、実装、テストのように複数の段階が同じ文脈を共有する作業では、この書き直しのコストが分業の利点を上回ります。文脈を渡したいなら、名前付きの担当ではなくフォークを選ぶ方が筋が通ります。

往復して詰める作業はメインの会話に残します

方針を固めながら進める作業は、分けると扱いにくくなります。サブエージェントは依頼を受けて動き、結果を返して終わる形が基本のため、途中で細かく方向を変える用途には向きません。

なお、終わった担当に追加の指示を送って再開させることはできます。SendMessageで送られた指示は、その担当を立てたエージェントからのものであれば通常の作業指示として扱われ、途中の軌道修正も反映されます。ただし他のエージェントからのメッセージは、権限の承認や設定変更の根拠にはなりません。承認を与えられるのは権限の仕組みと利用者本人だけという線が引かれています。

同じファイルを触る並行作業は隔離が必要です

並行して走る担当が同じファイルを書き換えると、上書きが起きます。作業の切り分けで防ぐのが基本ですが、公式はもうひとつの手段として isolation: worktree を用意しています。

この指定を付けると、そのサブエージェントは一時的なgitワークツリーの中で動きます。渡されるのは、既定では親セッションのHEADではなくデフォルトブランチから枝分かれしたリポジトリの複製です。変更がなければワークツリーは自動で片付けられ、外に出ようとするコマンドは拒否されます。

報告が多すぎると、分けた意味が薄れます

分業の効果は、返ってくる情報量で決まります。担当ごとに詳細な報告を返させると、メインのコンテキストは分ける前と変わらない水準まで膨らみます。

判断の材料として何が必要かを先に決め、それ以外は返させないという設計が要になります。会話の中にすでにある内容についての確認なら、サブエージェントを立てるより /btw が適します。全体の文脈は見えるがツールは持たず、やり取りが履歴に残らない仕組みです。

社内でこうした切り分けの基準づくりから設計への落とし込みまでを進めたい場合は、malnaの支援内容もご確認ください。malnaは戦略立案から実行、内製化までを一貫して支援しており、AI導入・コンサルティングおよびIT・DX分野の導入事例は累計40社以上あります。

担当の定義は、フロントマター付きのMarkdown 1枚で決まります

カスタムのサブエージェントは、YAMLフロントマターとMarkdown本文からなるファイル1枚で定義します。必須の項目は name と description の2つだけで、残りはすべて任意です。作成方法としては、Claudeに書かせる方法と、自分でファイルを置く方法があります。

必須項目は name と description の2つだけです

フロントマターで指定できる項目は多岐にわたりますが、必須は2つに限られます。まずは最小構成で作り、必要になった制御だけを足していく順序が扱いやすくなります。

項目	必須	内容
name	必須	小文字とハイフンで書く識別子。: は使えない。ファイル名と一致させる必要はない
description	必須	どんなときにこの担当へ委譲するか
tools	任意	使えるツール。省略すると継承する
disallowedTools	任意	使わせないツール
model	任意	sonnet opus haiku fable、モデルID、inherit のいずれか。既定は inherit
permissionMode	任意	権限モード
maxTurns	任意	停止までの最大ターン数
skills	任意	起動時に全文を読み込ませるスキル
mcpServers	任意	この担当が使えるMCPサーバー
hooks	任意	この担当が動いている間だけ効くフック
memory	任意	永続メモリの範囲。user project local
background	任意	常に背後で走らせるかどうか
effort	任意	この担当が動くときの思考量。セッションの設定を上書きする
isolation	任意	worktree を指定すると一時的なワークツリーで動く
color	任意	一覧や記録での表示色
initialPrompt	任意	メインのエージェントとして動くときに自動で送られる最初の指示

--agents フラグでJSONを渡す形でも同じ項目が使えます。この場合はファイルに保存されず、そのセッションの間だけ存在するため、試作や自動化スクリプトに向いた形です。システムプロンプトは prompt に書きます。

description は「いつ任せるか」を書く欄です

Claudeが委譲先を判断する材料は description です。依頼の内容、各担当の説明文、そのときの文脈を照らし合わせて、どの担当に渡すかが決まります。

つまりこの欄は、その担当が何をするかだけでなく、どんなときに呼ばれるべきかまで書く場所になります。公式の例では、コード修正の直後に使うという条件や、積極的に使うという方針が説明文の中に書き込まれています。自動で呼ばれない場合に最初に見直すのもこの欄です。

本文がそのままシステムプロンプトになります

フロントマターの下に書いたMarkdownの本文は、その担当のシステムプロンプトになります。Claude Code本体のシステムプロンプト全体は渡らず、この本文と環境情報だけで動きます。

そのため、作業の手順、確認する項目、報告の形式までを本文に書き込むことになります。公式の例では、起動時にすることを番号付きで示し、確認項目を並べ、返す内容を重要度で分類するという構成が使われています。

置き場所が、その担当を誰が使えるかを決めます

定義ファイルをどこに置くかで、その担当を使える範囲が変わります。同じ name の定義が複数ある場合は、優先順位の高い場所のものが使われます。

置き場所	適用範囲	優先順位
管理設定内の .claude/agents/	組織全体	1（最も高い）
--agents CLIフラグ	そのセッションのみ	2
.claude/agents/	そのプロジェクト	3
~/.claude/agents/	自分の全プロジェクト	4
プラグインの agents/	プラグインを有効にした範囲	5（最も低い）

プロジェクトの .claude/agents/ は、作業ディレクトリからリポジトリのルートまで遡って読み込まれます。同じ name が入れ子の複数階層にある場合、有効になるのは作業ディレクトリに近い定義です。バージョン管理に入れておけば、チームで共有しながら改善していけます。

.claude/agents/ と ~/.claude/agents/ はどちらも再帰的に読み込まれるため、agents/review/ のようにサブフォルダで整理できます。ただし識別されるのは name の値だけで、フォルダ構成は識別に影響しません。同じディレクトリ配下で name が重複すると片方しか読み込まれず、この重複は /doctor が報告します。

なお、プラグイン由来のサブエージェントでは hooks、mcpServers、permissionMode が無視されます。これらを使うには、定義ファイルを .claude/agents/ か ~/.claude/agents/ に置き直します。

知見をためたい担当にはメモリを持たせます

memory を指定すると、その担当は会話をまたいで残るディレクトリを持ちます。コードベースの癖、調査でわかった構造、設計上の判断といった知見を書きためていける仕組みです。

範囲	保存先	使う場面
user	~/.claude/agent-memory/<エージェント名>/	全プロジェクトで覚えておきたい
project	.claude/agent-memory/<エージェント名>/	プロジェクト固有で、バージョン管理で共有したい
local	.claude/agent-memory-local/<エージェント名>/	プロジェクト固有だが、バージョン管理に入れたくない

公式は既定として project を推奨しています。バージョン管理を通じて共有できるためです。メモリを有効にすると、システムプロンプトに読み書きの指示と MEMORY.md の冒頭が差し込まれ、Read、Write、Editが自動で使えます。自動メモリを切っている環境では効きません。

参考：Create custom subagents（英語）

使える道具と権限の絞り込みが、任せられる範囲を決めます

サブエージェントに任せられる範囲は、渡すツールと権限の設定で決まります。指示文で禁じるより、道具を渡さない方が確実です。公式も、必要な権限だけを与えることを設計の原則として挙げています。

tools と disallowedTools で道具を絞ります

ツールの制御には2つの欄があります。tools は許可リスト、disallowedTools は拒否リストとして働きます。どちらも省略した場合は、サブエージェントが使えるツールをすべて継承します。

両方を書いた場合は disallowedTools が先に適用され、残った範囲に対して tools が解決されます。両方に書かれたツールは取り除かれます。どちらの欄も、mcp__ にサーバー名を続ける形でMCPサーバー単位の指定が可能で、disallowedTools ではワイルドカード指定によって全サーバーのツールを除外できます。

tools に書いた項目がどのツールにも解決されない場合は、起動そのものが失敗し、解決できなかった項目名を挙げたエラーが返ります。綴り間違いに気づける設計になっているため、黙って無力な担当が動く事態は避けられます。

そもそもサブエージェントに渡らない道具があります

tools に書いても渡らないツールが存在します。この絞り込みは2段階で、1段目はすべてのサブエージェントに適用され、2段目は背後で走る担当に適用されます。

1段目で外れるのは、AskUserQuestion、EndConversation、EnterPlanMode、ExitPlanMode（permissionMode が plan の場合を除く）、ScheduleWakeup、TaskOutput、WaitForMcpServers、Workflow です。Agent も、入れ子の上限に達した層では取り上げられます。

2段目は背後で走る担当に効きます。既定では背後で走るため、この絞り込みが標準の状態です。MCPのツールはすべて残りますが、組み込みのツールは限られた一覧だけが残り、それ以外は継承していても tools に書いていても外されます。同じ定義でも前面と背後で使えるツールが変わるため、動作しない原因がここにある場合があります。

権限モードは、締める方向にしか働きません

permissionMode は権限確認の扱い方を決める欄です。指定できるのは default、acceptEdits、auto、dontAsk、bypassPermissions、plan で、manual は default の別名として使えます。

見落としやすいのは、親の設定を緩められないという点です。親が bypassPermissions か acceptEdits で動いている場合、その設定が優先され、フロントマターの指定では上書きできません。親が自動モードなら自動モードが継承され、フロントマターの指定は無視されます。管理設定で bypassPermissions を無効にしている環境では、フロントマターに書いても親の設定で動きます。組織として権限を締めた状態は、定義ファイル側からは崩せない構造です。

フックで、道具の中の操作を条件付きに縛ります

ツール単位の許可では粗すぎる場合、フロントマターの hooks で PreToolUse を定義し、実行前に検査する方法があります。同じツールの中で許す操作と止める操作を分けたいときの手段です。

公式が示しているのは、Bashを許可したうえで読み取り専用のSQLだけを通す例です。標準入力で渡されるJSONからコマンドを取り出し、書き込み系のSQLを検出したら終了コード2で止めるという流れになります。フロントマターに書いたフックはその担当が動いている間だけ効き、終了時に片付けられます。ただしプロジェクト配下の定義については、そのフォルダの信頼を承認していないとフックが読み飛ばされます。

特定の担当を使わせたくない場合は、設定の permissions.deny に Agent(担当名) の形で書きます。組み込みにもカスタムにも使える方法です。委譲そのものを止めたいなら、Agent ツール自体を拒否する手もあります。

返ってきた報告は、検証済みの情報ではありません

サブエージェントの最終報告は、Claudeが読む前に走査されます。読んだファイルやWebページ、コマンド出力の中に、メインの会話に向けた指示が混ざっている可能性があるためです。

走査は内容を削ったり書き換えたりはしません。Claude Code自身の出力を模した記述にバックスラッシュを挿入するか、権限設定に言及している場合に印の行を先頭に足すという2種類の変化が入るだけです。悪意の有無を判定する仕組みではなく、報告に含まれた指示に従ってClaudeがツールを呼んだ場合も、権限確認とサンドボックスは通常どおり働きます。この走査は、任せる範囲を絞る作業の代わりにはなりません。

分業の設計を社内に広げるときは、コストと決めごとを先に置きます

サブエージェントを使うと、費用と時間には減る要素と増える要素の両方が出ます。メインの会話が短く保たれる分の節約と、担当ごとにコンテキストを組み直す分の増加が同時に発生するため、どちらが大きいかは分け方で変わります。

メインの文脈が短く保たれる分、読み直しの費用が減ります

Claude Codeは毎回のリクエストで会話の全体を送り直します。会話が長くなるほど、1回の質問でも過去のやり取り全体に対して費用が発生する構造です。

だからこそ、返ってくる情報を要約に絞る効果が積み上がります。公式もコスト削減の手段として、大量出力を伴う操作の委譲を挙げています。逆に、詳細な報告を返す担当を多数走らせれば、この効果は打ち消されます。減るか増えるかは、切り分けと報告の粒度で決まります。

サブエージェントは自前のキャッシュを持ち、5分で切れます

プロンプトキャッシュの扱いも、分けると変わります。サブエージェントは自分のシステムプロンプトとツール構成で会話を始めるため、親とは別のキャッシュを作ります。最初の呼び出しではキャッシュに当たらず、自分のターンを重ねながら温まっていく形です。

保持時間にも差があります。定額プランではメインの会話に1時間の保持が自動で要求されますが、サブエージェントは定額プランでも5分の保持です。親のキャッシュは影響を受けず、呼び出しと結果が会話の末尾に追加されるだけで済みます。フォークは例外で、親のシステムプロンプトとツールと履歴を引き継ぐため、最初のリクエストで親のキャッシュを読みます。同じ文脈で作業を渡す場合にフォークの方が安く済む理由がここにあります。

モデルと effort を作業に合わせて下げられます

model を指定すれば、担当ごとにモデルを変えられます。公式はコスト削減の項目で、単純な作業の担当には model: haiku を指定するよう案内しています。

モデルの決まり方には順序があります。環境変数 CLAUDE_CODE_SUBAGENT_MODEL、呼び出しごとに渡される model、定義ファイルの model、メイン会話のモデルという順です。組織で availableModels による制限をかけている場合、許可されない値は別のモデルに置き換えられ、対話セッションでは警告が出ます。思考量は effort で、low から max までの範囲でセッションの設定を上書きできます。

起動のたびに文脈を集め直すので、待ち時間は増えます

公式は、待ち時間が問題になる場面ではメインの会話を使うよう案内しています。サブエージェントは真っ白から始まるため、必要な情報を自分で集め直す時間がかかります。

小さく的を絞った変更なら、分けずに直接進めた方が速く終わります。分業が効くのは、集め直すコストを払っても釣り合うだけの分量がある場合に限られます。

名前の重複と同時実行の上限を、先に決めておきます

社内で定義ファイルを増やしていくと、運用上の決めごとが必要になります。まず name の重複です。同じディレクトリ配下で重複すると片方しか読み込まれず、どちらが有効かは読み込み順に依存します。命名の規則と持ち主を先に決めておくと、後から追いやすくなります。

同時実行にも上限があります。既定では1つのセッションで20の担当が動いている状態からさらに立てようとすると失敗し、Claudeには再試行しないよう伝えられます。走っている数が上限を下回れば、また立てられるようになります。上限を変える場合は CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS に正の整数を指定します。なお、セッション全体で立てられる総数には制限がありません。

組織として配るなら管理設定に置きます

組織全体に同じ担当を配る手段として、管理設定の中の .claude/agents/ に定義ファイルを置く方法があります。フロントマターの書式はプロジェクトやユーザーの定義と同じで、同名の定義があれば管理設定側が優先されます。

組み込みの担当を制限する手段も用意されています。特定の種類を止めるなら permissions.deny に追加し、委譲そのものを止めるなら Agent ツールを拒否します。ExploreとPlanだけを外すなら CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 を設定し、この場合Claudeは委譲せずに自分でファイルを読んで探索する動きに変わります。締める順序としては、まず現場で使われている定義を把握してから制限に進む形が安全と考えられます。

参考：カスタムサブエージェントの作成

参考：How Claude Code uses prompt caching（英語）

よくある質問

サブエージェントの導入検討でよく挙がる疑問を整理しました。

Claude Codeのsubagentとは何ですか

特定の種類のタスクを処理する特化したAIアシスタントです。独自のコンテキストウィンドウ、専用のシステムプロンプト、限定されたツールアクセス、独立した権限を持って動き、作業を終えると結果をメインの会話に返します。1つのセッションの中で動く仕組みです。

サブエージェントの定義ファイルはどこに置きますか

プロジェクト単位なら .claude/agents/、自分の全プロジェクトで使うなら ~/.claude/agents/ に置きます。組織全体に配る場合は管理設定の中の .claude/agents/ が置き場所です。同じ名前の定義がある場合は、管理設定、CLIフラグ、プロジェクト、ユーザー、プラグインの順に優先されます。

サブエージェントを使うとトークン消費は増えますか

減る側と増える側の両方があります。大量の出力がメインの会話に入らず要約だけが返る分は減りますが、サブエージェントは親とは別のキャッシュを持ち、起動ごとに文脈を組み直します。詳細な報告を返す担当を多数走らせると、節約の効果は失われます。

サブエージェントとエージェントチームはどう違いますか

サブエージェントは1つのセッションの中で動き、結果をメインのエージェントにのみ返します。エージェントチームは複数のClaude Codeインスタンスを編成する実験的機能で、担当同士が直接メッセージを送り合い、共有のタスクリストで自己調整します。既定では無効で、環境変数で有効化します。

サブエージェントが自動で呼ばれないときは何を見ますか

まず description を見直します。Claudeは依頼の内容と各担当の説明文、そのときの文脈から委譲先を判断するため、どんなときに使うかが説明文に書かれていないと選ばれません。特定の担当を確実に使いたい場合は、@メンションで指定する方法があります。

まとめ

Claude Codeのsubagentは、別のコンテキストで動く担当を切り出して任せる仕組みです。効果は、コンテキストの分離、依存のない処理の並行実行、役割と道具の固定という3点に集約されます。

分け方には向き不向きがあります。大量の出力を生む作業、互いに依存しない調査、立場を分けたいレビューは分業が効きます。逆に、前提の共有が必要な作業や往復して詰める作業は、分けない方が速く進みます。定義ファイルは name と description だけで書き始められ、共有範囲を決めるのは置き場所です。任せる範囲は指示ではなくツールと権限で絞るのが確実です。

最初の一歩としては、いま繰り返している作業の中から、出力が大量に出て結論だけが必要なものを1つ選び、読み取り専用の担当として定義してみてください。分けた結果として何がメインに返ってくるかを見れば、次にどこを分けるべきかが見えてきます。

分業の設計や社内展開のルールづくりを具体的に進めたい場合は、malnaにご相談ください。

関連記事：Claude CodeでSEO分析基盤をゼロから構築する全手順【実務者向け】

関連記事：Claude Codeで広告分析と施策提案を自動化する方法【実務者向け】

AIを使える人材が社内にいない場合

分け方の考え方はわかった。でも、社内の作業を切り分けて担当を組む人がいない。

役割の粒度を決め、渡す権限を絞り、動かしてから直していく工程は、業務と環境の両方を見られる人が手を動かさなければ形にならないのではないでしょうか。malnaでは、AI活用の実務経験を持つ人材をご紹介するAIタレント名鑑を運営しています。採用ではなく業務委託として、週1日から相談いただけます。

無料相談はこちら 記事一覧はこちら