Claude Code Subagents 公式ドキュメントリファレンス 2026

これは Anthropic 公式ドキュメント (2026年5月版) ベースの Claude Code subagents 完全リファレンス。subagent とは何か、いつ使うか、全設定項目を知りたい人のための深掘り版。

ベストプラクティスや設計パターンは Claude Code Subagents ベストプラクティス を参照。このリファレンスは 公式 docs が実際に何を言ってるか に集中する。

Subagent とは何か

Subagents は単一の Claude Code セッション内で、特定タスクを担う専門 AI アシスタント。各 subagent は:

• 独立したコンテキストウィンドウ で動作（親会話と分離）
• カスタム system prompt で動作を絞り込み
• 特定の tool アクセス（制限可能）で動作
• 独立した権限 を持つ
• サマリーのみ を親会話に返す

サブタスクが検索結果・ログ・ファイル内容で本会話を埋め尽くしそうな時に使う。subagent が独自コンテキストで作業し、結果だけ返す。

Subagents は 単一セッション内 で動作。並列の独立セッションには background agents、通信するセッションには agent teams を使う。

組み込み Subagents

Claude Code には複数の組み込み subagent が含まれ、適切な場面で自動使用される。

Explore

コードベース検索・分析に最適化された高速 read-only エージェント。

• モデル: Haiku（高速・低遅延）
• Tools: Read-only（Write / Edit は拒否）
• 目的: ファイル発見、コード検索、コードベース探索
• 特別な挙動: 速度のため CLAUDE.md と親セッションの git status をスキップ
• 徹底度レベル: quick、medium、very thorough

Plan

Plan モード中に context 収集のために使われるリサーチエージェント。

• モデル: 親会話から継承
• Tools: Read-only（Write / Edit 拒否）
• 目的: 計画立案のためのコードベース調査
• 特別な挙動: CLAUDE.md と親 git status をスキップ（Explore と同じ）

General-purpose

探索とアクション両方が必要な複雑マルチステップタスク向けの能力エージェント。

• モデル: 親会話から継承
• Tools: 全ツール
• 目的: 複雑な調査・マルチステップ操作・コード変更

その他の組み込み

カスタム Subagents の作成

Subagents は YAML frontmatter 付き Markdown ファイルで定義。作成方法は2つ:

1. /agents コマンド — 対話型 UI（推奨）
2. .md ファイル手動作成 — 自動化・バージョン管理向け

Quickstart（/agents 経由）

/agents

1. Library タブに切り替え
2. Create new agent を選択
3. 場所を選ぶ: Personal（~/.claude/agents/ に保存）/ Project（.claude/agents/）/ Managed
4. Generate with Claude を選択して subagent の説明を記述
5. Tool を選ぶ（Read-only / All / Custom）
6. モデルを選ぶ（Sonnet / Haiku / Opus / Inherit）
7. 色を選ぶ（UI 識別用）
8. メモリ設定（User scope or None）
9. 保存

subagent は即時利用可能。

手動作成（YAML Frontmatter）

~/.claude/agents/my-agent.md（ユーザースコープ）または .claude/agents/my-agent.md（プロジェクトスコープ）に Markdown ファイルを作成:

---
name: code-reviewer
description: コードレビュー専門家。コード変更後に積極的に使用。
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: sonnet
color: blue
---

あなたは以下を専門とするシニアコードレビュアー:
1. コード品質と可読性
2. セキュリティ脆弱性
3. パフォーマンス問題
4. ベストプラクティス

見つけた各問題について:
- ファイルと行番号
- 該当コードのスニペット
- 改善案
- 理由

Subagent スコープと優先順位

Subagents は複数の場所で定義可能。重複時は優先度高いものが勝つ。

プロジェクト subagents (.claude/agents/) — チーム共有のため git に commit。 ユーザー subagents (~/.claude/agents/) — 全プロジェクトで使える個人 subagent。

.claude/agents/ と ~/.claude/agents/ は 再帰的にスキャン。サブフォルダは識別に影響せず、name frontmatter フィールドだけが識別子。

命名衝突警告: 同スコープ内で2ファイルが同じ name を宣言した場合、Claude Code は片方を保持しもう片方を 警告なしに破棄 する。

Plugin スコープ識別子

Plugin subagents はスコープ付き識別子を持つ。プラグイン my-plugin の agents/review/security.md は my-plugin:review:security として登録される。

Frontmatter 完全リファレンス

---
name: my-agent              # 必須。一意の識別子
description: いつ使うか       # 必須。Claude が委譲判断に使う
tools:                       # オプション。デフォルトは全継承
  - Read
  - Grep
  - Bash
model: sonnet                # オプション。sonnet, haiku, opus, inherit, default
color: blue                  # オプション。UI 背景色
permission-mode: ask         # オプション。ask, accept-edits, plan-mode, bypass
hooks:                       # オプション。subagent 固有 hooks
  PostToolUse:
    - matcher: Write
      command: prettier
skills:                      # オプション。読み込む skills
  - skill-name
load-claude-md: true         # オプション。デフォルト true（組み込みは異なる）
allowed-paths:               # オプション。パスアクセス制限
  - "src/**"
---

name フィールド

• 必須
• スコープ内で一意（大文字小文字区別）
• Use the {name} agent to ... 呼び出しで使われる
• Plugin subagents はスコープ形式: plugin-name:subfolder:name

description フィールド

• 必須
• Claude が委譲判断に使うので明確に
• ベストプラクティス: 具体的に。「use proactively」「expert in」「specialized for」等のトリガー語を含める

tools フィールド

• オプション。デフォルトは親会話から継承
• ツール名の配列または *（全ツール）
• 共通制限パターン:
  • Read-only: [Read, Grep, Glob, WebFetch]
  • Build-only: [Read, Grep, Bash]
  • Write-only: [Read, Write, Edit]

model フィールド

• オプション: sonnet、haiku、opus、inherit、default
• inherit (デフォルト挙動) は親モデルを使う
• read 重視 subagent は haiku 推奨（速くて安い）
• 複雑な推論には opus

permission-mode フィールド

• ask — 確認プロンプト
• accept-edits — 自動承認
• plan-mode — Plan モード強制
• bypass — プロンプトなし（慎重に使う）

起動時にロードされるもの

subagent 起動時に以下がロードされる:

これが Explore と Plan が速い理由 — 重いコンテキストをスキップする。

Subagents の Persistent Memory

Subagents は会話を越えて自分のメモリを維持できる:

• 保存場所: ~/.claude/agent-memory/{agent-name}/
• 設定: subagent 作成時に「User scope」メモリを選択
• 内容: MEMORY.md インデックス + Claude が書くトピックファイル

使用例: code-reviewer subagent がレビュー間でコードベースパターンと再発問題を蓄積。

無効化: 作成時に「None」を選択、または frontmatter で auto-memory-enabled: false に設定。

Subagents の使い方

明示的呼び出し

code-reviewer agent を使ってこの PR をレビューして。

Claude が指定された subagent に委譲する。

暗黙的委譲

subagent の description にマッチするタスクを書くと、Claude が自動委譲する可能性がある。description が明確であるほど自動ルーティングが信頼できる。

現会話を Fork

現会話を subagent に fork できる:

/fork code-reviewer

subagent は現会話状態を受け取り、自身の system prompt で続行。

複数 Subagent を並列実行

Claude は複数 subagent を spawn してタスクの異なる部分を同時処理できる。本会話が調整:

3つのレビューエージェントを並列実行:
1. security-reviewer で OWASP 問題
2. perf-reviewer でパフォーマンス懸念
3. style-reviewer でコードスタイル

結果を単一レポートに統合して。

CLI 定義 Subagents

起動時に --agents フラグに JSON を渡す:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer.",
    "prompt": "You are a senior code reviewer.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors.",
    "prompt": "You are an expert debugger."
  }
}'

セッション限定で、ディスクに保存されない。

Tool 制限パターンライブラリ

Read-only Reviewer

tools:
  - Read
  - Grep
  - Glob
  - WebFetch

Build-only Worker

tools:
  - Read
  - Grep
  - Bash
permission-mode: ask

Test Runner

tools:
  - Read
  - Bash
hooks:
  PostToolUse:
    - matcher: Bash
      command: "npm run test"

Documentation Writer

tools:
  - Read
  - Write
  - Edit
allowed-paths:
  - "docs/**"
  - "README.md"

Subagents 用 Hooks

Subagents は自身の hooks を持てる:

hooks:
  PreToolUse:
    - matcher: Bash
      command: "logger -t claude-code 'Subagent running bash'"
  PostToolUse:
    - matcher: Write|Edit
      command: "prettier --write {file}"
  Stop:
    - command: "echo 'Subagent finished' >> ~/agent.log"

これらの hooks は その subagent がアクティブな時だけ 発火する（親会話では発火しない）。

Subagents 用 Skills

Subagents は親会話と同様に skills を読み込める:

skills:
  - testing
  - api-design

subagent が読み込んだ skill は、その subagent のコンテキストウィンドウに限定される。

Subagents ができないこと

• 他の subagent を spawn できない（無限ネスト防止）
• セッション間で状態を保持できない（memory ディレクトリだけ）
• tools ホワイトリスト外のツールにアクセスできない
• 単一セッション内で互いに通信できない（それには agent teams を使う）

Subagents のデバッグ

利用可能な subagent 確認

/agents

Library タブで利用可能な subagent 全てとその定義場所が表示される。

Subagent アクティビティ確認

/agents

Running タブで起動中の subagent、現タスク、停止操作ができる。

ログ

Subagent アクティビティは以下にログされる:

• ~/.claude/logs/agents/{session-id}/{agent-name}.log

subagent が起動した（しなかった）理由のデバッグに使える。

InstructionsLoaded Hook

hooks:
  InstructionsLoaded:
    - command: "echo 'Loaded: {instructions}' >> ~/agent-debug.log"

subagent が起動時に受け取ったコンテキストを確認できる。

Subagent の実例

code-reviewer

---
name: code-reviewer
description: コードレビュー専門家。コード変更後に積極的に使用。品質・セキュリティ・ベストプラクティス。
tools:
  - Read
  - Grep
  - Glob
model: sonnet
color: blue
---

あなたは以下を専門とするシニアコードレビュアー:
- コード可読性と保守性
- セキュリティ脆弱性 (OWASP Top 10)
- パフォーマンス最適化
- 言語固有のベストプラクティス

レビューする各ファイルについて:
1. 重要度順に問題リスト
2. 問題のあるコードスニペット
3. 具体的改善案
4. 理由説明

表面的な問題はスキップ。シニアレビュアーが目を留めるレベルに集中。

test-runner

---
name: test-runner
description: テスト実行と失敗分析。テストコマンド失敗時 or カバレッジ分析時に使用。
tools:
  - Read
  - Bash
  - Grep
model: haiku
color: green
---

あなたはテスト実行専門家。呼び出されたら:

1. 関連テストコマンド実行 (npm test, pytest 等)
2. 失敗があれば出力を分析
3. 根本原因を特定（症状ではなく）
4. ファイル:行参照付きで修正案

成功時はカバレッジ報告とカバーされてないブランチをフラグ。

research-agent

---
name: research-agent
description: Web リサーチ専門家。最新ドキュメント、ライブラリ比較、技術調査が必要な時に使用。
tools:
  - WebFetch
  - WebSearch
  - Read
  - Write
model: sonnet
color: purple
---

あなたは技術リサーチ専門家。呼び出されたら:

1. 権威ある情報源を検索（公式 docs 優先）
2. 複数情報源でクロスチェック
3. 発見を実行可能なサマリーに統合
4. URL 付きで出典明記
5. バージョン固有情報はメモ

AI生成サマリーは避け、一次情報源を優先。

関連記事

• Claude Code Subagents ベストプラクティス
• Claude Code Plugins 完全リファレンス 2026
• Claude Code Hooks 完全リファレンス 2026
• Claude Code Skills 厳選15本
• Claude Code は AGENTS.md をサポートしているか？

FAQ

Subagents と Skills の違いは？

Skills はオンデマンドで呼び出される再利用可能な指示モジュール。Subagents は独自コンテキストウィンドウ・tool 制限・system prompt を持つ専門 AI アシスタント。Skills は本会話の挙動を拡張、subagents は隔離された実行環境を作る。

Subagents は他の subagent を spawn できる？

できない。無限ネスト防止のため。並列作業が必要なら、親会話が複数 subagent を直接 spawn する必要がある。

Subagents をプロジェクト間で共有するには？

~/.claude/agents/ (ユーザースコープ) に置けば全プロジェクトで使える。チーム共有はプラグインまたは .claude/agents/ を git commit。

Read-only subagent に使うべきモデルは？

Haiku (速くて安い)。低遅延 read 操作に最適化されている。複雑な推論が必要な subagent には Sonnet / Opus を温存。

Subagents は自分の CLAUDE.md を持てる？

通常 subagent はプロジェクト + ユーザー CLAUDE.md をデフォルトで読む (Explore と Plan は速度のためスキップ)。無効化は frontmatter で load-claude-md: false。

Subagent の破壊的変更を防ぐには？

tools フィールドを read-only に制限、または permission-mode: ask で機密操作に確認必須化。

Subagent ログはどこ？

~/.claude/logs/agents/{session-id}/{agent-name}.log — subagent が起動した（しなかった）理由のデバッグに有用。

Agent SDK でも subagents 使える？

可能。Agent SDK は同じ subagent システムを公開。自動化スクリプトからプログラマブルに subagent を呼び出せる。