Claude Code サブエージェントの使い方と作り方(2026年8月版)

まとめ:Claude Code のサブエージェントは、どう作って、いつ使うのか

• サブエージェントの実体は .claude/agents/ に置くマークダウン1枚。必須の frontmatter は name と description の2つで、残り13項目は任意。
• 多くの2025年の記事が案内する /agents パネルは v2.1.198 で削除された。今はファイルを自分で書くか、Claude に書かせる。
• 解決するのは速度ではなくコンテキストの汚染。途中経過が結論よりずっと長い作業だけを委譲する。
• 落とし穴:前提説明が大量に要る作業を空のコンテキストに投げると、かえって遅くなる。その場合は会話ごと引き継ぐ /subtask フォークを使う。そして「抜けを探せ」と指示されたレビュアーは、コードが健全でも何かを見つけてくる — 公式ドキュメントが直接警告している。
• 並列手段は4つに増えた(サブエージェント / agent view / agent teams / dynamic workflows)。使い分けは後半の表に。

最終更新 2026-08-25。フィールド名とバージョンは code.claude.com の現行ドキュメント基準。

2025年の記事どおりに進めると詰まる箇所

文法が少し変わった話ではなく、作り方そのものが変わっている。

モデルも世代が入れ替わった。現在は claude-opus-5 / claude-sonnet-5 / claude-fable-5 / claude-haiku-4-5。日付のサフィックスを付けてはいけない。claude-opus-5 がそのまま完全なIDだ。

サブエージェントが解く問題は1つだけ

サブエージェントは CPU コアではない。同じ作業を倍速にする装置ではなく、本流の会話がゴミで埋まるのを防ぐ装置だ。公式のベストプラクティスも、コンテキストウィンドウが性能の根本的な制約だという一文から始まる。

「この API の呼び出し箇所を全部探して」をメインセッションにやらせると、そのセッションは grep の結果で半分埋まる。本来やらせたかったリファクタリングに使う余地が残らない。同じ指示を委譲すれば、探索はあちらのコンテキストで燃え、本流には結論が数行だけ戻る。判断基準は1つ。途中経過が結論よりずっと長い作業なら委譲し、そうでなければ直接やらせる。

ファイルの置き場所と優先順位

定義はマークダウンファイルで、上が優先される。

1. 管理設定 → 2. --agents CLI フラグ → 3. .claude/agents/(プロジェクト、チームで共有) → 4. ~/.claude/agents/(個人) → 5. プラグインの agents/

3と4はサブフォルダまで再帰的に走査されるので .claude/agents/review/security.md のような整理ができる。チーム共有のレビュアーはプロジェクトへ、好みに近い検査はホームディレクトリへ。

frontmatter の全項目

必須は name(小文字とハイフン、コロン不可)と description の2つ。自動委譲はこの一文を見て判断するので、ここが雑だとそのエージェントは永遠に呼ばれない。

公式ドキュメントの最小構成はこれ。

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

2026年の項目まで使うとこうなる。保存先は .claude/agents/security-reviewer.md。

---
name: security-reviewer
description: >
  Reviews a diff for injection, authz, and secret-handling issues.
  Use after any change touching auth, DB queries, or external input.
tools: Read, Glob, Grep, Bash
model: opus
effort: high
isolation: worktree
memory: project
---

You review diffs for security defects only.

Report format:
- file:line — the problem — why it is dangerous — the smallest fix
If you find nothing, reply "no findings" and stop. Do not invent problems.

tools を読み取り専用に絞っているのは好みの問題ではない。レビュアーに書き込み権限を与えると、レビューではなく修正を始める。読み取り専用のレビュアーと書き込みできる実行役を分けるのが設計の基本だ。

呼び出し方は3通り

自動委譲は description を見て Claude が振り分ける。楽だが保証はない。Use the test-runner subagent to fix failing tests のように自然言語で名前を呼ぶこともできる。必ず通したい工程には @"code-reviewer (agent)" のメンションを使う。これは実行を保証する。セッション全体を特定のエージェントで回すなら claude --agent code-reviewer で起動する。

現在のセッションのバックグラウンド項目は /tasks、ワークフローは /workflows で見る。/agents で何かを管理しようとしてはいけない。名前の似た claude agents はまったく別の機能だ。

実際に効く4つのパターン

範囲を切った調査。 「決済関連のコードを全部洗い出して」を隔離し、戻すのはファイル一覧と要約だけにする。

敵対的レビュー。 実装したセッションに自分の仕事を採点させてはいけない。新しいコンテキストのレビュアーに diff だけ見せる。同梱の /code-review スキルが第30週からこれをバックグラウンドのサブエージェントとして実行する。後述の失敗パターン5を必ず併読すること。

フォーク(/subtask)。 通常のサブエージェントは空のコンテキストで始まるが、/subtask で起こしたサブエージェントはここまでの会話を丸ごと引き継ぐ(ツール呼び出しと結果だけが隔離される)。1時間かけて文脈を積んだセッションから枝を1本切り出すときに使う。第33週から対話セッションの既定がフォークモードになり、agent view を無効にするとコマンドは /fork に変わって /subtask は消える。

/batch。 大きな変更を5〜30個のサブエージェントに分け、それぞれ別のワークツリーで作業して個別に PR を開く。断片ごとに独立した機械的な一括変更に向く。

並列実行の4つの手段を比較する

規模の目安。同時エージェントは最大16、1回の実行で合計1,000。25個超または推定150万トークン超で Large workflow の警告が出る。スクリプト内では import() とファイルシステムへの直接アクセスが禁止で、実行中のユーザー入力も受け取れない(v2.1.154 以降)。

モデル・effort・ツール・スキーマ・作業ディレクトリが同じ兄弟エージェント同士はプロンプトキャッシュを共有する。Claude Code は最初の応答が始まるまで残りを最大5秒引き止め、キャッシュヒットを作りにいく。兄弟の設定を無意味にバラバラにしないほうがいい実務的な理由だ。

Channels は外部イベントを実行中のセッションへ押し込む機能で、並列実行の手段ではない。上の表に入れていないのはそのためだ。

よくある失敗パターン

ほとんどが公式ドキュメントの警告そのものである。

1. 範囲のない「調べて」。 数百ファイルを読んでコンテキストを焼く。範囲を絞るか隔離するかを必ずやる。
2. 前提が足りないサブエージェント。 長い説明文を書くくらいなら /subtask フォークを使う。
3. ファイル衝突。 agent teams はワークツリー隔離をしてくれない。ファイル分割は自分でやる。サブエージェントは isolation: worktree で隔離できる。
4. ファンアウトの途中で止めると高くつく。 再開すると、未完了のエージェントより後に開始されたエージェントは、すでに終わっていても全部やり直しになる。大きな1つより小さな複数のほうが進捗を保存できる。
5. レビュアーを信じすぎる。 抜けを探せと指示されたレビュアーは健全な作業でも何かを見つけ、全部追いかけると過剰設計に向かう。レビュー結果は入力であって指示ではない。
6. モデル選択の放置。 ワークフロー内の全エージェントはセッションのモデルをそのまま使う。大きな実行の前に /model を確認し、軽い工程は小さいモデルを明示する。
7. 何でも委譲すること。 結果の diff を一文で説明できるなら直接やらせたほうが速い。委譲には固定費がある。

コスト感覚

サブエージェントを複数回せばトークンは倍々で増え、そのままプランの上限に効く。並列実行はタダで速くなる話ではなく、時間をトークンで買う取引だ。/usage がスキル・サブエージェント・プラグイン・MCP サーバ別に上限の消費を分解して見せてくれる(第21週から)。大きなワークフローを一度回したあとに開けば、次はどの工程を haiku に落とすかの判断材料になる。

次に読むもの

なぜこう設計するのか、理論寄りの背景は ハーネスエンジニアリングが5要素で整理している。Mac で GUI から複数セッションを管理したいなら Conductor の使い方が別アプリ側の選択肢だ。

最後に1点。CLAUDE.md とサブエージェントを同じ引き出しに入れてはいけない。CLAUDE.md は毎セッション必ず読み込まれ、スキルとサブエージェントは必要なときだけ読み込まれる。だから CLAUDE.md は短くなければならず、サブエージェントの定義は長くてもいい。配置とマージ順は CLAUDE.md の書き方で別途扱っている。

出典

• Anthropic Claude Code サブエージェントのドキュメント