Claude Code│サブエージェントの設定方法｜.claude/agentsの書き方と呼び出し方

2026年9月29日2026年10月27日

サブエージェントは、Claude Code の中で、役割を決めて別に動かす小さな担当者です。

調べ物やレビューの詳細を別のコンテキストで処理し、メインへ結果を返せます。サブエージェント自身のリクエストも同じ利用枠を消費するため、分担すれば消費量が減るとは限りません。

置き場所：.claude/agents/名前.md（プロジェクト）、~/.claude/agents/名前.md（自分用）
必須は name と description。本文がそのサブエージェントへの指示になる
model で使うモデルを決められる（haiku にすると軽い作業を安く回せる）
組み込みの Explore・Plan・general-purpose もある

2026年10月23日に公式Subagents資料を再照合しました。以下の実行例は9月29日の記録で、今回の実機再検証結果ではありません。

手元の確認は、2026年9月29日に Windows 11 の Claude Code 2.1.284 で、練習用のフォルダー（C:\demo\cc-b）を使って行いました。

自作のサブエージェントを動かした

委任とモデル選択を試すため、Haikuで文字数を答える練習用エージェントを作りました。LLMの回答は正確な文字数を保証しないため、実務の計数には文字の数え方を決めたプログラムを使ってください。

試す場合は、対象プロジェクトの.claude/agents/に次の内容をword-counter.mdとして保存し、先頭行を---にします。

既存セッションの開始後に初めてagentsフォルダーを作った場合は、Claude Codeを再起動してから呼び出してください。

起動時から存在するプロジェクト用・自分用フォルダー内の変更は通常数秒で検出されますが、追加ディレクトリー内の定義や監視を無効にした起動では再起動が必要です。

.claude/agents/word-counter.md

---
name: word-counter
description: 渡された文の文字数を数える練習用のサブエージェント。文字数を数えるときに使う。
tools: Read
model: haiku
---

渡された文の文字数（空白を含む）を数え、「文字数: N」の1行だけを返す。

claude -p "word-counter サブエージェントを使って「こんにちは世界」の文字数を数え、サブエージェントの返事をそのまま返して" --output-format stream-json --verbose

出力の記録を調べると、Claude が Agent ツールで word-counter を呼び、使われたモデルにはメインの claude-opus-5 と、サブエージェントの claude-haiku-4-5 の2つが記録されていました。

以下は当時の結果であり、現在の実行ではAgent呼び出しにword-counterが指定されたことと、実際のモデルを確認してください。

対話モードのv2.1.242以降では、/tasksのサブエージェント行でもモデルを確認できます。

TOOL Agent {"description": "Count characters", "prompt": "「こんにちは世界」の文字数を数えてください。", "subagent_type": "word-counter"}
RESULT word-counter サブエージェントの返事：

文字数: 7

置き場所と優先順位

順位	場所
1	組織の管理設定
2	起動時の `--agents` フラグ
3	.claude/agents/（プロジェクト）
4	~/.claude/agents/（自分用）
5	プラグインの agents/

Claude Code 公式ドキュメント「Subagents」をもとに作成

プロジェクト用・自分用のagents配下は再帰的に読まれ、nameで識別します。同じagentsツリー内でnameを重複させないでください。入れ子のプロジェクト定義では作業場所に近いものが優先され、プラグインは階層を含むスコープ付き識別名になります。

主な設定

項目	働き
name（必須）	識別名。256文字以内で、: を含めず – で始めない
description（必須）	いつ使うか。Claude はこれを見て任せるかを決める
tools	使えるツール。省略時はサブエージェントに提供可能なツールを継承（権限・実行形態による制限あり）
model	sonnet・opus・haiku・fable・完全なモデル ID・inherit（メインと同じ）
disallowedTools・permissionMode・maxTurns・skills・mcpServers・effort など	細かい制御

description に「use proactively」と書くと、積極的に任されやすくなると書かれています。

modelの指定は呼び出し時の指定や組織の利用可能モデル制限などで変わり得るため、haikuを書くだけで常にそのモデルになるとは限りません。

名前を文章で挙げる方法はClaudeの委任判断に委ねられるため、対話モードで特定の担当を指定したい場合は、@の候補一覧からエージェントを選びます。

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

名前	役割
Explore	読み取り専用でファイルを探す（quick・medium・very thorough の3段階）
Plan	プランモード中の調べ物（読み取り専用）
general-purpose	調べて変更もする、複数手順の作業

Exploreは原則メインのモデルを使いますが、メインがFableの場合は接続先によりOpusになる例外があります。同名の独自Exploreや環境変数によるモデル上書きもあるため、実際のモデルを確認してください。

呼び出し方

名前を挙げて頼む（上の例）
@"code-reviewer (agent)" のように @ で指定する
claude --agent 名前で、セッション全体をそのエージェントとして動かす
--agents にJSONを渡して、そのセッションだけのサブエージェントを作る

v2.1.198以降の/agentsは作成画面ではなく編集方法を案内します。--agentsへのJSONファイルパスはv2.1.281以降の非対話モード（-p）だけで、対話モードでは使えません。

気をつけること

自作のサブエージェントの説明の合計が15,000トークンを超えると、起動時に警告が出る
サブエージェントはメインから3階層下まで子を作れる（CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で変更）
特定のサブエージェントを止めるなら --disallowedTools "Agent(Explore)" など

手順を再利用したいだけなら、Skillsのほうが手軽です。

まとめ

.claude/agents/名前.md に name・description・本文を書く
model: haiku で軽い作業を安いモデルに任せられる（実際に Haiku で動いた）
名前を挙げて頼むか、@ で指定して呼ぶ
/agents は 2.1.198 から作成画面を開かない

参考：Claude Code「Subagents」（2026年10月23日照合）と、2026年9月29日のCLI 2.1.284実行記録。

よくある質問：Claude Codeのサブエージェント

サブエージェントとは、何ですか？

Claude Code の中で、役割を決めて別に動かす小さな担当者です。

調査の詳細を別のコンテキストで扱い、結果をメインへ返します。利用枠はメインと共通で、追加のリクエストも消費に含まれます。

自作のサブエージェントは、どこに置きますか？

プロジェクト用は .claude/agents/名前.md、自分用は ~/.claude/agents/名前.md に置きます。

同じ名前のものが複数あるときの優先順位は？

優先順位は、1 組織の管理設定、2 起動時の --agents フラグ、3 .claude/agents/（プロジェクト）、4 ~/.claude/agents/（自分用）、5 プラグインの agents/ の順です。

必須の設定は、何ですか？

name と description の2つで、本文がそのサブエージェントへの指示になります。

nameは256文字以内で、:を含めず、-で始めない名前にします。

description は「いつ使うか」で、Claude はこれを見て任せるかを決めます。

「use proactively」と書くと、積極的に任されやすくなると書かれています。

使うモデルや、使えるツールは決められますか？

toolsで対象を限定できます。省略時も、サブエージェントへの提供対象外のツールやバックグラウンド実行の制限は残ります。

model には sonnet・opus・haiku・fable・完全なモデル ID・inherit（メインと同じ）を指定できます。

haiku にすると、軽い作業を安く回せます。

disallowedTools・permissionMode・maxTurns・skills・mcpServers・effort などで、細かく制御もできます。

組み込みのサブエージェントには、何がありますか？

Explore（読み取り専用でファイルを探す。quick・medium・very thorough の3段階）、Plan（プランモード中の調べ物。読み取り専用）、general-purpose（調べて変更もする、複数手順の作業）です。

サブエージェントは、どうやって呼び出しますか？

名前を挙げて頼む、@"code-reviewer (agent)" のように @ で指定する、claude --agent 名前でセッション全体をそのエージェントとして動かす、--agents にJSONを渡してそのセッションだけのサブエージェントを作る、の4つがあります。

気をつけることは？ Skillsとの使い分けは？

自作のサブエージェントの説明の合計が15,000トークンを超えると、起動時に警告が出ます。

サブエージェントはメインから3階層下まで子を作れます（CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で変更）。

特定のサブエージェントを止めるなら --disallowedTools "Agent(Explore)" などを使います。