Claude Code Subagent自作ガイド2026
Claude CodeのSubagent機能を使うと、.claude/agentsに1枚ファイルを置くだけでミニClaude Codeを追加できる。ビルドもインストールも要らない。
この記事の要点
- subagentの実体は
.claude/agents/に置くYAMLフロントマター付きMarkdownファイル1枚だけ - 必須フィールドは
nameとdescriptionの2件のみ。toolsを絞れば渡す権限を最小化できる - descriptionに「use proactively」を書くかどうかで、自動委譲される頻度が変わる
このAI Career Japanのリポジトリにも、2026年7月時点で実際に運用しているsubagentが4件ある。競合記事のH2見出しを抜き出すcompetitor-analyzer、AI臭い文章を検出するfreshness-gate、読者の悩みを集めるpersona-researcher、最新トレンドを追うtrend-researcherだ。この記事はそれらの実物のfrontmatterと、Anthropic公式ドキュメントの仕様を突き合わせて書いている。
サブエージェントとは何か
サブエージェント（subagent）は、独立したコンテキストウィンドウを持つミニClaude Codeだ。メインの会話とは別のスレッドで動き、指示された作業を終えたら要約だけを親会話に返す。
独立コンテキストという設計
効果は明確だ。競合記事を10本読んで比較表にまとめる作業をメインの会話でやると、10本分のHTML本文がそのままコンテキストに残り続ける。subagentに投げれば、親会話が受け取るのは「比較表と結論」だけになる。長い調査タスクほど、この差が響く。
このリポジトリでcompetitor-analyzerを動かしてみると、1回の呼び出しで約7万トークン・約20回のツール呼び出しを消費した。7万トークンがメインの会話に残らずに済む。これがsubagentを使う理由の中核だ。
向く作業・向かない作業
サブエージェントが向く作業
大量の中間出力が出る調査・検索・ログ解析。結論だけ持ち帰ればいい作業。
サブエージェントが向かない作業
数手先を親と相談しながら進める編集作業。会話の文脈を細かく共有し続ける必要がある処理。
最小構成で1体作る
ディレクトリとファイル名
まずは動くものを作る。.claude/agents/ディレクトリが存在しなければ作成し、その中にMarkdownファイルを1枚置く。ファイル名がそのままエージェント名になるわけではなく、frontmatter内のnameフィールドが識別子になる。
mkdir -p .claude/agents
cat > .claude/agents/log-summarizer.md << 'EOF'
---
name: log-summarizer
description: ビルドログやテスト失敗ログを読み、原因と該当箇所を要約するエージェント。長いログを扱うときに使う。
tools: Read, Grep, Glob
model: sonnet
---
あなたはログ解析の専門エージェントです。
## 役割
渡されたログファイルを読み、エラーの原因・発生箇所・再現条件を
簡潔にまとめて返します。
## 出力フォーマット
- 原因: [1行で]
- 該当ファイル・行番号
- 再現条件
- 推奨する次のアクション
EOF動かして確認する
これだけで新しいsubagentが使えるようになる。tools: Read, Grep, Globと書いた時点で、このエージェントはファイルの書き換えも実行もできない。読んで要約するだけの専門職として封じ込められる。
ここは見落としがちだが
frontmatterのtoolsを書かなければ、サブエージェントは親と同じ全ツールを継承する。「読むだけでいい」作業ほど、明示的に絞ったほうが事故が減る。
frontmatterの必須・任意フィールド
公式ドキュメント「Create custom subagents」で確認できるフィールドを、必須・任意で分けて整理する。
必須は2フィールドだけ
| フィールド | 必須 | 説明 |
|---|---|---|
name | 必須 | 小文字とハイフンのみ。エージェントの識別子 |
description | 必須 | Claude Codeが自動委譲するかどうかの判断材料になる文章 |
tools | 任意 | 許可するツールのリスト。省略時は親を継承 |
disallowedTools | 任意 | 拒否リスト。toolsより先に適用され、重複分は除外される |
model | 任意 | sonnet/opus/haiku/fable/フルIDまたはinherit。デフォルトはinherit |
permissionMode | 任意 | default/acceptEdits/plan等。省略時は親の設定を継承 |
isolation | 任意 | worktreeを指定すると独立したgit worktreeで作業する |
background | 任意 | trueでバックグラウンド実行。組み込みツールに縮小される |
tools/disallowedToolsの解決順
ツール権限はdisallowedToolsが先に適用され、そのあとtoolsが適用される。両方に同じツール名があれば除外される側が優先される。MCPサーバーのツールだけ許可したい場合はmcp__サーバー名やmcp__サーバー名__*の形式でtoolsに書ける。
modelの解決順
modelを省略するとinheritになり、親会話と同じモデルが使われる。解決順は環境変数によるサブエージェント指定、呼び出し時の引数、frontmatterのmodel、親のモデルという4件の参照先を順番に見ていく設計だ。このリポジトリの4件のsubagentは全員model: sonnetを明示している。inheritのまま任せず固定しているのは、親の会話でモデルを切り替えても調査系エージェントの挙動を一定に保ちたいからだ。
descriptionの書き方で発動頻度が変わる
descriptionはただの説明文ではない。Claude Codeが「このタスクをこのsubagentに投げるべきか」を判断する唯一の材料だ。曖昧なdescriptionは、いつまで経っても自動発動しない。
このリポジトリのtrend-researcherは次のように書いている。
description: AI/キャリア関連の最新トレンドをWeb検索で調査し、記事ネタに使える要約を返すエージェント。/run や /research 実行時にリサーチフェーズで使用する。「何をするエージェントか」だけでなく「いつ使うべきか」まで書いてある。ここが薄いと、メインのClaude Codeは自力で調査を始めてしまい、subagentは存在しないのと同じになる。
強制発動フレーズ
もったいないと感じるのが
descriptionに「use proactively」「must be used」のような強制発動フレーズを入れないケースだ。公式ドキュメントでも明記されている手法で、頻繁に使いたいサブエージェントほどこの一言の有無で発動率が変わる。
既存4件を実例として読み解く
権限を絞った例
freshness-gateのtoolsはRead, Globの2件だけだ。WebSearchもBashも渡していない。理由は単純で、このエージェントの仕事は「完成した記事HTMLを読んでAI臭い表現を指摘する」ことに限定されているから、それ以外の権限は不要という判断だ。
---
name: freshness-gate
description: 記事HTMLからAI臭い文章パターンを検出し、具体的な書き換え案を提示するエージェント。記事完成前の品質チェックに使用する。
tools: Read, Glob
model: sonnet
---権限を広げた例
対してcompetitor-analyzerとpersona-researcher、trend-researcherの3件はRead, Grep, Glob, Bash, WebSearch, WebFetchという同じ6件のツールを共有している。Web検索と外部ページ取得が要る調査系タスクという共通点があるからだ。tools行を見るだけで、そのエージェントが何をする役割か推測できる設計になっている。
| エージェント | tools | 役割 |
|---|---|---|
| competitor-analyzer | Read, Grep, Glob, Bash, WebSearch, WebFetch | 競合記事のH2構成抽出 |
| freshness-gate | Read, Glob | AI臭い文章の検出 |
| persona-researcher | Read, Grep, Glob, Bash, WebSearch, WebFetch | 読者の悩み収集 |
| trend-researcher | Read, Grep, Glob, Bash, WebSearch, WebFetch | 最新トレンド調査 |
ファイルサイズを調べてみると、4件を合計しても約17KBのMarkdownで、4つの専門職が定義されている。1件あたり平均4KB弱という軽さも、subagentを増やすハードルの低さを裏付けている。
サブエージェントとAgent Teamsの違い
Claude Codeには、subagentとよく混同される機能がもう1つある。複数のセッションを並行稼働させる「Agent Teams」だ。両者の違いは「結果だけ返すか、互いに直接会話できるか」に集約される。バックグラウンドで動かした複数セッションを1画面で管理する「Agent View」という別機能もあり、こちらは並列実行の監視に特化している。
使い分けの基準
subagentは親（呼び出し元）にしか結果を報告しない。一方Agent Teamsのメンバー同士は、共有タスクリストを介して直接メッセージをやり取りする。セキュリティ・性能・テストカバレッジを別々の観点でレビューさせたいときはAgent Teams、単発の調査結果だけ欲しいときはsubagentという住み分けだ。
Subagent向き
結果だけ受け取れればいい単発調査。トークンコストを抑えたいとき。メインエージェントが全工程を管理する場合。
Agent Teams向き
複数の視点を突き合わせたい議論・レビュー。担当ファイルが分かれた並行実装。仮説を競わせるデバッグ。
| 項目 | Subagent | Agent Teams |
|---|---|---|
| 通信 | 親にのみ結果を報告 | メンバー同士が直接メッセージ |
| 調整方法 | 親エージェントが一括管理 | 共有タスクリストで自律調整 |
| トークンコスト | 低い（要約のみ返る） | 高い（各自が独立インスタンス） |
| 既定状態 | 常に利用可能 | 既定で無効。環境変数で有効化が必要 |
Agent Teamsは既定で無効になっており、有効化には環境変数の設定が要る。公式ドキュメントは推奨チーム規模として3〜5件のteammateを挙げており、1メンバーあたり5〜6件のタスクを持たせるとコーディネーションが崩れにくいとしている。TeammateIdle・TaskCreated・TaskCompletedという3件のhooksでチーム側の品質ゲートを組めるのも、subagentにはない特徴だ。
迷ったら、まずsubagentから試すのがいい。Agent Teamsはコーディネーションのオーバーヘッドが確実に乗る分、並行調査・並行レビューのように「複数の視点が本当に必要な場面」でだけ使う機能だと考えている。
出力フォーマットを固定して事故を減らす
subagentの本文（Markdown部分）には、役割の説明だけでなく出力フォーマットも書き込んでおく。competitor-analyzerの本文には、見出し構成・比較表・KW実測データという3ブロックのテンプレートが埋め込まれている。
これをやらないと、同じsubagentを2回呼んだときに毎回違う形式で結果が返ってくる。親会話側でパースするコードを書くなら尚更、フォーマットの固定は必須だ。
禁止事項セクションを本文末尾に書く
これだけで、同じsubagentを2回呼んだときの出力形式のブレが減る。freshness-gateやcompetitor-analyzerには「主観的な評価はしない」「記事構成の推奨はしない」という禁止事項が明記されている。役割を狭めるほど、返ってくる結果の再現性が上がる。
つまずきやすいポイント
toolsを書き忘れて権限が広すぎる
toolsを省略すると親のツールをすべて継承する。読み取り専用のはずのエージェントにEdit/Writeが渡っていないか、frontmatterを見直す。
descriptionが短すぎて自動発動しない
「〇〇するエージェント」だけでなく「いつ使うか」まで書く。このリポジトリの4件は全員、末尾に用途（「記事作成時のSEO戦略立案に使用する」等）を添えている。
優先順位を誤解する
同名エージェントは、Managed settings、--agentsフラグ、プロジェクトの.claude/agents/、ユーザーの~/.claude/agents/、プラグインという5件の優先順で解決される。プロジェクト側の定義がユーザー側より優先されると誤解しやすい。
backgroundを付けたのにツールが足りない
バックグラウンド実行では組み込みツールがRead/Grep/Glob/Bash/Edit/Write等に縮小される。frontmatterでtoolsを広く指定していても除去される点に注意する。
よくある質問
Q. サブエージェントとカスタムスラッシュコマンドは何が違う？
スラッシュコマンドは決まった手順を呼び出すショートカットで、実行はメインの会話のコンテキストで行われる。subagentは独立したコンテキストで動き、ツール権限も個別に絞れる。中間出力を大量に出す調査系はsubagent向きだ。
Q. サブエージェントからさらにサブエージェントを呼べるか？
ネストは可能だが、無制限ではない。深さの上限を設定する環境変数が用意されており、意図しない多段呼び出しでコストが膨らむのを防いでいる。なおAgent Teamsのteammateは自分のteammateを持てず、これは明確な制限として公式ドキュメントに明記されている。
Q. モデルを指定しないとどうなる？
デフォルトはinheritで、親会話と同じモデルが使われる。解決順は環境変数のサブエージェント指定、呼び出し時の引数、frontmatterのmodel、親のモデルの順で上書きされる。
Q. MCPサーバーのツールだけ許可したい場合は？
mcp__サーバー名やmcp__サーバー名__*の形式でtoolsに書ける。特定のMCPサーバーだけ使わせたいときに使う。
Q. subagentとAgent Teamsはどちらを先に覚えるべき？
subagentを先に覚えるべきだ。常時利用可能で設定も名前とdescriptionの2件だけで動く。Agent Teamsは既定で無効な実験的機能なので、subagentで手が届かなくなってから検討すればいい。
まとめ
subagent自作の要点は3つに絞れる。name/descriptionの2件だけで動く最小構成から始めること、toolsで権限を必要最小限に絞ること、descriptionに「いつ使うか」まで書いて自動委譲の精度を上げること。この3つを外すと、せっかく作ったsubagentは呼ばれないか、権限過多で事故る。
自分ならまず既存の会話を振り返り、「同じ調査を何度も手作業でやっている」箇所を1つ見つけてsubagent化する。汎用的な万能エージェントを最初から目指さず、freshness-gateのように役割を1つに絞ったものから増やしていく。Agent Teamsに手を出すのは、subagentを3〜4件運用してみて「メンバー同士の会話が要る」と実感してからで十分だ。