Claude Codeのサブエージェントを作る — 作成ナレッジとメリット・デメリット

この記事で扱うこと

Claude Codeにはビルトインのサブエージェント(Explore / Plan / general-purpose 等)に加えて、.claude/agents/ 配下にMarkdownファイルを置くだけで独自のサブエージェントを定義できる仕組みがあります。code-reviewer・db-reader・data-scientistのように、専門領域を担うエージェントを自分で作って運用に組み込めます。

本記事は「サブエージェントをどう作るか / なぜ作るか / 作らないほうがよいケース」を網羅した作成ナレッジです。並列で動かす活用パターンについてはサブエージェント完全活用 — Taskツールで作る並列開発パターンを、複数セッションを束ねるUIについてはClaude Codeのagent view — 複数セッションを束ねる常駐プロセス設計を参照してください。

サブエージェントを自作するメリット

.claude/agents/ に独自定義を置くと、ビルトインの汎用エージェントでは取りにくい5つの効果が得られます。

「主な指示を毎回ペーストしている」「読みたくない調査ログでメイン文脈が埋まっている」のどちらかが当てはまれば、サブエージェント化の効果が出やすい場面です。

サブエージェントを自作するデメリット・コスト

メリットの裏返しとして、運用上の負担も発生します。

• メンテナンスコスト:システムプロンプトが詳細であるほど、Claude本体や周辺機能(Skills / MCP)のアップデートに追随するメンテが必要になる
• デバッグの難しさ:メインに返るのは要約だけなので、サブエージェント内部で何が起きたかを追うにはtranscriptファイル(~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl)を直接読みに行く必要がある
• 過剰な特化の罠:狭く作りすぎると「結局メインで自分でやった方が早い」状態になり、呼び出されなくなる
• 委任の境界の歪み:メインから見るとブラックボックスなので、「途中で軌道修正したい」「経過を見たい」用途とは相性が悪い
• 権限設計の責任:bypassPermissions を不用意に付けるとサブエージェント側で .git / .claude 等への書き込みが通る。自由度と安全性のトレードオフを毎回意識する必要がある

公式は「Subagents work within a single session」「Subagents cannot spawn other subagents」と明示しています。1セッション内の専門ワーカーであり、無制限に階層化できる仕組みではありません。

作成の最小単位

/agents コマンド経由(推奨)

最も手早いのはClaude Code内で /agents を実行してUIから作成する方法です。タブ式のインターフェースで Library から「Create new agent」を選び、Generate with Claude で説明文を渡すと、識別子・description・システムプロンプトの雛形が自動生成されます。ツール許可・モデル・色・メモリスコープを順に選んでいくだけで完成し、編集も /agents の中から続けて行えます。/agents 経由で作ったサブエージェントはセッション再起動なしで即時利用可能です。

手書きで作る

.claude/agents/<name>.md を直接書く場合は「YAMLフロントマター + システムプロンプト本文」のMarkdownファイル1つで完結します。最小例:

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

必須は name と description の2つだけ。あとは省略するとデフォルトに従います(model は inherit、tools はメインから全継承)。手書きで作成・編集した場合はセッション再起動が必要(/agents UI経由なら即時反映)。

セッション全体をサブエージェント化する(--agent)

委任ではなく「そのセッション全体をサブエージェントとして起動する」モードもあります。

claude --agent code-reviewer

このとき、サブエージェント定義のシステムプロンプトがClaude Codeのデフォルトシステムプロンプトに置き換わり、tools / model 制限もセッション全体に適用されます。プロジェクトのデフォルトとして固定したい場合は .claude/settings.json に {"agent": "code-reviewer"} を書きます(CLIフラグの方が優先)。プラグイン提供のサブエージェントを使う場合は claude --agent <plugin-name>:<agent-name> のようにスコープ付き名を指定します。

スコープと優先順位

ファイル配置でスコープが決まり、同名で衝突すると優先度の高い場所が勝ちます。

プロジェクト用のサブエージェントは .claude/agents/ に置いてgit管理するのがチーム共有の基本形です。--add-dir で追加したディレクトリはファイルアクセスは付与されるがagentsは走査されないので、別プロジェクトのサブエージェントを呼び出したい場合は ~/.claude/agents/ かplugin経由を選びます。

プラグイン経由で配布する場合の制約:Plugin由来のサブエージェントは hooks / mcpServers / permissionMode フィールドが無視されます(セキュリティ仕様)。これらを使いたければ、プラグイン提供のファイルを .claude/agents/ か ~/.claude/agents/ にコピーするか、permissions.allow を settings.json 側で明示する必要があります。

フロントマター仕様(全フィールド)

公式が定義しているフロントマターを網羅します。name と description 以外はすべて任意。

特に効くフィールドを4つだけ深掘りします。

ツール許可と禁止の併用(tools / disallowedTools)

両方指定すると disallowedTools が先に適用され、その後 tools の許可リストで絞られます。例:tools: Read, Bash + disallowedTools: Write, Edit で「ReadとBashは使えるが書き込み系は禁止」という設計が可能。Bash のような単一ツールの内部コマンド単位の細粒度制御(例:rm だけ禁止)はsubagent定義ではなく permissions.deny 側で扱います。

Agent(worker, researcher) のような書き方は「claude --agent でメインスレッドとして起動したエージェントが、どのサブエージェント型をspawnできるか」を絞る用途です。通常のsubagent定義の tools フィールドに書いても効果はありません(公式に「Subagents cannot spawn other subagents」と明示されており、サブエージェントは他のサブエージェントを呼べないため)。

model の解決順序

サブエージェントのmodelは次の優先順位で解決されます:

1. CLAUDE_CODE_SUBAGENT_MODEL 環境変数
2. 呼び出し時のper-invocation model パラメータ
3. サブエージェント定義の model フロントマター
4. メイン会話のモデル(デフォルト)

「定義ではHaikuなのにテスト時だけSonnetで動かしたい」場合は環境変数を一時的に上書きするのが手軽です。

memory で永続化された知識を持たせる

memory: project を指定すると .claude/agent-memory/<name>/ に「会話を跨いで保持される知識」を蓄積できます。レビュー専任エージェントなら「過去に見つけたバグのパターン」や「このプロジェクトの命名規則」を MEMORY.md に蓄積し、次回起動時に冒頭200行(または25KB)が自動でcontextに注入されます。

project が推奨のデフォルト。チームで共有したい知識はgitに乗せ、個人スクラッチパッドは local を選びます。

isolation: worktree で踏み合いを防ぐ

並列実行する複数のサブエージェントが同じファイルを編集すると衝突します。isolation: worktree を指定すると、起動時に一時的なgit worktreeに作業領域が切り替わり、編集差分は隔離された状態でメインに返ります。サブエージェントが何も変更しなければworktreeは自動削除されます。claude --bg でバックグラウンド実行するagent view経由の運用とも整合する設計です。

作成すべき / 作成すべきでない判断軸

サブエージェント化の効果は「反復性 × コンテキスト浪費」で見ると判断しやすくなります。

「毎回同じワーカーを同じ指示で起動している」が自作の最大シグナルです。公式も Define a custom subagent when you keep spawning the same kind of worker with the same instructions. と明示しています。

失敗パターンと回避策

1. description が抽象的すぎて呼ばれない

description: General helper のような汎用説明だと、Claudeが委任タイミングを判断できません。「いつ使うか」を具体的に書き、Use proactively after code changes. のような誘発フレーズを入れると自動委任が起きやすくなります。

2. システムプロンプトが長大すぎる

サブエージェントは独立contextで動きますが、システムプロンプト自体がそのまま入力に乗ります。1,000行を超えるとサブエージェント側でcontext圧迫が起きます。500行を上限の目安に、詳細な参照資料は skills で外部化するか、Memoryに蓄積する設計が安全です。

3. bypassPermissions 乱用

ツール承認を全部スキップする bypassPermissions は便利ですが、.git / .claude / .vscode 等への書き込みも通ります。利用するときは「信頼済みの作業領域に閉じている」「isolation: worktree併用」の2条件を意識します。

なお、親(メイン会話)が bypassPermissions / acceptEdits を有効化していると、子サブエージェントの permissionMode 指定は無視されて親モードが継承されます。親が auto モードの場合も、子の permissionMode は効かず、ツール呼び出しは親の分類器でチェックされます。サブエージェント側で「安全側に倒したい」と思っても、親モードが緩いと意図通りには絞れない仕様です。

4. テスト不能なblack box

サブエージェントの応答だけ見て「何かおかしい」と感じても、transcriptを読まないと因果を追えません。デバッグのために以下を運用に組み込みます:

• ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl を時々開く
• Stop hookで結果を集計ファイルに追記しておく
• 失敗時に「再現用の最小プロンプト」をメインから渡してチェックする

5. 別サブエージェントとの責務重複

「コードレビュー」「コードの品質判定」「コードの改善提案」のように似た役割を別ファイルで持ってしまうと、Claudeが委任先を判断できず精度が落ちます。1つのサブエージェントに1つの焦点を徹底し、責務が増えてきたら専門ごとに分割するのが運用上のセオリーです。

関連機能との使い分け

サブエージェントは「セッション内で動く専門ワーカー」ですが、似た目的の機能が他にもあります。

「自走させたい / contextを汚したくない / 権限を制限したい」ならサブエージェント、「毎回同じ手順を呼びたい」ならSkills、「常に効いている前提情報を持たせたい」ならCLAUDE.md、という棲み分けが基本です。Skillsとサブエージェントの細かい使い分けは別記事Skillsの作成・運用ガイドで扱います。

まとめ

自作サブエージェントのROIは「反復性が高い / 出力が長い / 権限を絞りたい / コストを下げたい」のいずれかに該当するかで決まります。

• 最小単位は .claude/agents/<name>.md のYAMLフロントマター + システムプロンプト
• スコープはManaged > CLI > project > user > pluginの優先順位
• 効くフィールドは tools / model / memory / isolation
• 「同じ指示を毎回ペースト」「メイン会話のcontextを浪費」が最大の作成シグナル
• 失敗パターン(曖昧なdescription / 長すぎるプロンプト / bypassPermissions乱用 / 責務重複)を意識すれば運用負荷は下げられる

「並列で何本も走らせる活用編」はTaskツールで作る並列開発パターン、「複数セッションを横断管理するUI」はagent view記事で扱っています。サブエージェントとSkillsのどちらを作るべきかはSkills作成・運用ガイドも合わせて読むと判断軸が立ちやすくなります。