Claude Code Subagents 完全リファレンス 2026 — frontmatter全17項目・5スコープ・built-in 3種・本番パターン6選

Claude Code Subagents ベストプラクティス 2026 で なぜ・どう設計するか を読んだあなたへ、本記事は 完全リファレンスページ —— 全frontmatter項目、全スコープロケーション、全built-in を Anthropic 公式 Claude Code docs（2026年5月版）に対して検証して並べた一枚。

Subagents を本番運用するなら、このページをブックマークしてほしい。

Subagent とは（1段落で）

公式docs（2026年5月）から：「Subagents are specialized AI assistants that handle specific types of tasks. Use one when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again: the subagent does that work in its own context and returns only the summary.」

Subagent は YAML frontmatter 付きの Markdown ファイル。5つのスコープロケーションのいずれかに格納され、タスクが description にマッチすると Claude Code が委譲する。Subagent は 独自のコンテキストウィンドウ で動作し、結果のサマリーだけを親に返す — これが subagent を使う最大の理由。

5つのスコープロケーション（優先順位順）

同じ name の subagent が複数あれば、優先度の高いロケーションが勝つ：

Claude Code は .claude/agents/ と ~/.claude/agents/ を 再帰的に スキャン。agents/review/ や agents/research/ のサブフォルダで整理してOK。サブディレクトリのパスは識別子に影響しない（識別は name フィールドだけ）。name 値はツリー全体でユニークに保つこと。同じスコープ内で2ファイルが同じ name を持つと、1つだけ残り、もう1つは警告なしに破棄される。

プラグイン subagent の例外：プラグイン my-plugin の agents/review/security.md は my-plugin:review:security という scoped 識別子で登録される。サブフォルダが名前の一部になる。

frontmatter 全17項目

Subagent ファイルは YAML frontmatter を使う。必須は name と description のみ。

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

本文がシステムプロンプトになる。Subagent が受け取るのは このシステムプロンプト + 環境情報（作業ディレクトリなど）のみ で、Claude Code の完全システムプロンプトは入らない。

必須フィールド

ツール制御

特殊構文：tools: Agent(worker, researcher), Read, Bash — spawnできる subagent type を制限。許可リスト方式で、worker と researcher だけ spawn 可能。Agent のみで括弧なしなら任意のsubagent spawn可能。Agent 省略なら spawn 不可。

モデル選択

Claude がsubagent を invoke する時のモデル解決順序：

1. CLAUDE_CODE_SUBAGENT_MODEL 環境変数（設定されていれば）
2. invoke 時の model パラメータ
3. subagent 定義の model フィールド
4. 親会話のモデル

高速・安価な探索系には haiku（built-in Explore がこれ）。深い推論には opus。親と同等の能力なら inherit。

Permission Modes

プラグイン subagent では permissionMode 無視（セキュリティ制限）。

永続メモリと実行制御

isolation: worktree は強力：subagent が変更しなければ worktree は自動クリーンアップ、変更しても親リポに影響しない。実験的リファクタに最適。

他プリミティブとの統合

mcpServers のインライン定義テクニック：.mcp.json に書く代わりに subagent インラインで定義すると、MCP ツールが親セッションのコンテキストに乗らない。Subagent だけが使う MCP は subagent でインラインに。

Built-in Subagent 3種

Claude Code はビルトインで3種類同梱。親エージェントが自動で invoke する。各々親の権限を継承するが追加ツール制限あり。

Explore

• モデル：Haiku（高速・低レイテンシ）
• ツール：Read-only（Write/Edit禁止）
• 目的：ファイル探索、コード検索、コードベース探索

変更なしで「探索だけ」したい時 Claude が委譲する。invocation 時に thoroughness レベル指定：quick（ピンポイント）/ medium（バランス）/ very thorough（包括的）。

「このコードベース教えて」系ワークフローの主力。Haikuベースなので並列で5-10個 spawn しても安い。

Plan

• モデル：親会話と同じ（inherit）
• ツール：Read-only
• 目的：プランモード時のコードベース調査

plan mode でプラン提示前のコンテキスト収集に使う。Subagent は subagent を spawn できないので（無限ネスト防止）、Plan は「メインがプラン提示モードのまま、調査担当」として機能。

general-purpose

• モデル：親会話と同じ（inherit）
• ツール：全ツール
• 目的：探索 + アクションが両方必要な複雑な多段タスク

探索と変更の両方、複雑な推論、複数の依存ステップが必要な場合に Claude が委譲する。最も capable だが最も高価な built-in。

その他のヘルパー

本番パターン6選

Pattern 1: 安価な探索者 + 高価なクローザー

Haiku ベースの Explore subagent を並列で大量 spawn し、コンテキスト収集。Opus ベースのメイン会話が合成。コードベース Q&A・リファクタ計画に最適なコスト設計。

---
name: codebase-mapper
description: Maps a codebase area with read-only Haiku for cost efficiency
tools: Read, Grep, Glob
model: haiku
---

Pattern 2: 実験的リファクタは isolation:worktree

isolation: worktree を設定して実験的リファクタ用 subagent を作る。Subagent は独自のリポコピーを持ち、変更したらブランチに commit、しなかったら worktree 自動クリーンアップ。

---
name: refactor-tryout
description: Try refactor in isolated worktree. Main repo unaffected.
isolation: worktree
permissionMode: acceptEdits
---

Pattern 3: MCP は subagent スコープに

Playwright を browser テストで使いたいが、30+ ツール記述で親コンテキスト消費したくない時 — subagent にインライン定義。

---
name: browser-tester
description: Tests features in a real browser
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

MCP サーバは subagent 起動時に接続、終了時に切断。親会話は Playwright ツールを一切見ない。

Pattern 4: 学習する subagent には memory:project

memory: project を付けて、subagent が conversation 横断で insight 蓄積。プロジェクトの conventions を時間と共に学習する code-reviewer に最適。

---
name: code-reviewer
description: Reviews code; learns project conventions over time
memory: project
model: sonnet
---

メモリは ~/.claude/agent-memory/<project>/<agent-name>/ に保存。Subagent 起動時に MEMORY.md の先頭200行（または25KB）が context に load。

Pattern 5: 長時間実行はバックグラウンドに

background: true を設定すると、その subagent は常にバックグラウンドタスクとして spawn。メイン会話をブロックしない「監視と通知」エージェントに最適。

---
name: test-watcher
description: Watches test output and notifies on failures
background: true
tools: Read, Bash
---

Pattern 6: コーディネータの spawn 制限

メインスレッドとしてエージェントを起動（claude --agent coordinator）すると、Agent ツールで subagent を spawn できる。spawn できる type を制限するなら Agent(type1, type2) 構文：

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

coordinator が許可外を spawn しようとすると失敗、prompt 内でも許可された type だけしか見えない。

Subagents vs Skills vs Hooks（3方判定）

最も混同しがちな Subagent vs Skill：別の context window が必要なら subagent（メインが汚れないように）。メインセッション内インラインで動く再利用手順なら skill。

設定ファイル全体比較は AGENTS.md vs CLAUDE.md vs .cursor/rules を参照。

よくある落とし穴

1. name の衝突。同じスコープに同じ name のファイル2つ — 1つが警告なしに消える。~/.claude/agents/ と .claude/agents/ を grep して重複チェック。
2. subagent から subagent を spawn できない忘れ。設計上の制約（無限ネスト防止）。さらに委譲したいなら agent teams を使う。アーキテクチャは「main + 1段目 subagents」の2層フラット。
3. MCP コンテキスト肥大。.mcp.json で定義すると全セッションで MCP ツール記述が見える。Subagent にインライン定義してスコープを絞ろう。
4. ファイル直接編集してホットリロード期待。Subagent はセッション開始時にロード。直接編集→再起動。/agents UI 経由なら即時反映。
5. 作業ディレクトリ外で acceptEdits。このモードは作業ディレクトリと additionalDirectories のパスだけ自動承認。外はプロンプト出る。
6. plan モードで Plan subagent を上書き。メインがプランモードでコードベース調査が必要な時 Plan built-in に委譲される。同名のカスタム subagent で Plan を shadow していると微妙に壊れる。

CLI 定義 subagent（一過性）

1回限りのテストや自動化スクリプト向けに、subagent 定義を JSON で起動時に渡せる。ディスクに保存されず、セッション限り：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on quality, security, best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, provide fixes."
  }
}'

--agents フラグはファイルベース subagent と同じフィールドを JSON で受け取る。prompt がシステムプロンプト（markdown 本文と等価）。

FAQ

Subagent と agent teams の違いは？

Subagent は 単一セッション内 で動作し、サマリーを親に返す。Agent team は 互いに通信する独立セッション。並列で動かして1箇所から監視するならbackground agents 機能を参照。

Subagent から subagent を spawn できる？

できない（設計上の制約）。無限ネスト防止。アーキテクチャは「main + 1段目 subagents」の2層。委譲チェーンが必要なら agent teams へ。

Subagent のメモリはどこに保存される？

~/.claude/agent-memory/<project>/<agent-name>/MEMORY.md。先頭200行（または25KB）が起動時に load。詳細ファイル（debugging.md、patterns.md）はオンデマンド読込。machine-local — マシン間・クラウド環境間で共有されない。

Subagent のデフォルトモデルは？

inherit — メイン会話と同じ。sonnet / opus / haiku / フルモデルID で上書き可。CLAUDE_CODE_SUBAGENT_MODEL 環境変数も使える。

Read-only な subagent を作るには？

tools: Read, Grep, Glob（allowlist）または disallowedTools: Write, Edit, MultiEdit, NotebookEdit（denylist）。数ツールだけ使うなら allowlist の方がクリーン。

Subagent から MCP server にアクセスできる？

3通り：(1) mcpServers 省略時はメインから継承、(2) インライン定義で subagent スコープ限定、(3) セッション設定済みサーバ名の文字列参照。インライン定義は MCP コンテキストをメイン会話から隔離する技。

isolation: worktree とは？

一時的な git worktree（リポの隔離コピー）で subagent を実行する設定。Subagent の変更は commit & merge しない限りメインリポに影響しない。Subagent が変更を残さなければ worktree 自動クリーンアップ。実験的リファクタに最適。

プラグイン subagent の制約は？

プラグインは hooks、mcpServers、permissionMode を使えない（セキュリティ制限）。これら必要なら、エージェントファイルを .claude/agents/ または ~/.claude/agents/ にコピー。

ロードされている subagent をどう確認する？

Claude Code で /agents を実行。Library タブで全 subagent（built-in、user、project、plugin）が見える。Running タブで稼働中 subagent を確認・停止できる。

Subagent のファイル名は name と一致する必要がある？

ない。識別は name フィールドだけ。ファイル名・サブディレクトリパスは識別・invocation に影響しない —— プラグイン subagent を除く（サブフォルダが scoped 識別子の一部になる：my-plugin:review:security）。

関連記事

• Claude Code Subagents ベストプラクティス 2026
• AGENTS.md vs CLAUDE.md vs .cursor/rules 3方比較
• Career-Opsの内部構造：14モードSkillsアーキテクチャ
• Career-Ops 完全リファレンス 2026
• 2026年インストールすべきClaude Code Skills ベスト15
• 165以上のAIコーディングルール実例集

外部参考

• Create custom subagents — Claude Code Docs（Anthropic、2026年5月）
• Background agents
• Agent teams