Claude Code リファレンス: サブエージェント

クイックリファレンス

サブエージェント ファイル形式

---
name: agent-name              # 必須: 小文字とハイフン
description: When to use      # 必須: 自動委譲をトリガー
tools: Read, Grep, Glob       # オプション: 省略時はすべて継承
disallowedTools: Write, Edit  # オプション: 継承セットから削除
model: sonnet                 # オプション: sonnet|opus|haiku|inherit|full-ID
permissionMode: default       # オプション: default|acceptEdits|dontAsk|bypassPermissions|plan
maxTurns: 25                  # オプション: 最大エージェント操作回数
skills:                       # オプション: スキルコンテンツを起動時に挿入
  - skill-name-1
  - skill-name-2
mcpServers:                   # オプション: このエージェントにスコープされたMCPサーバー
  - server-name               # 文字列 = 親の接続を再利用
  - custom-server:             # オブジェクト = インライン定義
      type: stdio
      command: npx
      args: ["-y", "@some/server"]
hooks:                        # オプション: エージェントにスコープされたライフサイクルフック
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./validate.sh"
memory: user                  # オプション: user|project|local
background: false             # オプション: バックグラウンドタスクとして実行
isolation: worktree            # オプション: 分離されたgit worktreeで実行
---

System prompt goes here. This is what the subagent receives as its instructions.

すべてのフロントマター フィールド

フィールド	必須	型	説明
name	はい	文字列	小文字とハイフン
description	はい	文字列	Claudeがこのエージェントに委譲すべき場合
tools	いいえ	文字列 (CSV)	ツールの許可リスト。省略時はすべて継承
disallowedTools	いいえ	文字列 (CSV)	継承/指定セットから削除するツール
model	いいえ	文字列	sonnet, opus, haiku, 完全なモデルID、または inherit (デフォルト)
permissionMode	いいえ	文字列	パーミッションモード オーバーライド
maxTurns	いいえ	数値	停止までの最大エージェント操作回数
skills	いいえ	リスト	起動時にコンテキストに挿入されるスキル
mcpServers	いいえ	リスト	MCPサーバー(文字列参照またはインライン定義)
hooks	いいえ	オブジェクト	このエージェントにスコープされたライフサイクルフック
memory	いいえ	文字列	永続メモリ: user, project, または local
background	いいえ	ブール値	常にバックグラウンドタスクとして実行
isolation	いいえ	文字列	worktree で分離されたgit worktree
color	いいえ	文字列	背景色 (/agents UIで生成、部分的に記載)

ビルトイン サブエージェント

エージェント	モデル	ツール	用途
Explore	Haiku	読み込み専用 (Write/Edit なし)	高速コードベース検索と分析
Plan	継承	読み込み専用 (Write/Edit なし)	プランモード用研究
General-purpose	継承	すべて	複雑なマルチステップタスク
Bash	継承	Bash	個別コンテキストのターミナルコマンド
Claude Code Guide	Haiku	読み込み専用	Claude Code機能に関する質問

注記: 公式ドキュメントでは、3つのコアビルトインエージェント(Explore、Plan、general-purpose)が記載されています。追加の特殊なエージェント(Bash、Claude Code Guide)は、環境とバージョンによって利用可能な場合があります。

サブエージェント スコープと優先度

場所	スコープ	優先度
--agents CLIフラグ (JSON)	現在のセッション	1 (最高)
.claude/agents/	現在のプロジェクト	2
~/.claude/agents/	すべてのユーザープロジェクト	3
プラグイン agents/ ディレクトリ	プラグインが有効な場所	4 (最低)

同じ名前 → 優先度が高いものが適用されます。

主要な制約

• ネストなし: サブエージェントは他のサブエージェントをスポーンできません
• スキル継承なし: サブエージェントは親からスキルを継承しません — 明示的にリストする必要があります
• システムプロンプトのみ: サブエージェントはMarkdownボディ + 環境詳細を受け取り、完全なClaude Codeシステムプロンプトは受け取りません
• CLAUDE.md継承なし: サブエージェントはCLAUDE.mdコンテンツを受け取りません — Markdownボディのコンテキストのみで動作します
• 一方向通信: 親はAgentツールプロンプト文字列経由で情報を渡します; 子の最終メッセージのみが親に返されます
• tools内のAgent(type): メインスレッドエージェントがスポーンできるエージェントを制限するには、tools内で Agent(worker, researcher) を使用します (claude --agent にのみ適用され、サブエージェントには適用されません)
• 即時利用可能: 新しいエージェントは即座に利用可能です(再起動は不要です(/agents経由))

メモリ スコープ

スコープ	場所	使用場面
user	~/.claude/agent-memory/<name>/	すべてのプロジェクト全体での学習
project	.claude/agent-memory/<name>/	プロジェクト固有、git経由で共有可能
local	.claude/agent-memory-local/<name>/	プロジェクト固有、gitに含めない

メモリが有効な場合: Read/Write/Editツールが自動追加され、システムプロンプトにメモリ命令が含まれ、MEMORY.mdの最初の200行が挿入されます。

CLI定義エージェント

claude --agents '{
  "my-agent": {
    "description": "...",
    "prompt": "...",
    "tools": ["Read", "Bash"],
    "model": "sonnet"
  }
}'

prompt フィールド = システムプロンプト (ファイルベースエージェントのMarkdownボディと同等)。

エージェント ツール リネーム

AgentツールはClaude Code v2.1.63でTaskツールから改名されました。SDKの agents パラメータを経由して定義されたプログラマティックエージェントは、同じ名前のファイルシステムベースエージェントより優先されます。

エージェント SDK

エージェント SDK (Python: claude-agent-sdk, TypeScript: @anthropic-ai/claude-agent-sdk) は、Claude Codeのエージェントループへのプログラマティックアクセスを提供します。SDKはClaude Code CLIプロセスをstdin/stdout JSON経由でラップします — 生Messages APIを直接呼び出しません。

コア API: query()

query() 関数はメッセージをイールドする非同期ジェネレータです:

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Find and fix the bug in auth.py",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash"],
        permission_mode="acceptEdits",
        max_turns=10,
        max_budget_usd=5.0
    )
):
    print(message)

ClaudeSDKClient

Pythonは、双方向のマルチターン会話のための ClaudeSDKClient も提供します。@tool デコレータと create_sdk_mcp_server() を経由したPython関数として定義されたカスタムツールをサポートします。

プログラマティック サブエージェント定義

サブエージェントは、ファイルシステム定義を回避して、query() の agents パラメータを経由して定義できます:

const result = query({
  prompt: "Review the authentication module",
  options: {
    agents: {
      'code-reviewer': {
        description: 'Expert code review specialist.',
        prompt: 'You are a code review specialist...',
        tools: ['Read', 'Grep', 'Glob'],
        model: 'sonnet'
      }
    }
  }
});

プログラマティックに定義されたエージェントは、同じ名前のファイルシステムエージェントより優先されます。

SDK内のCLAUDE.md

CLAUDE.mdは、settingSources: ["project"] を経由して明示的に設定された場合にのみ読み込まれます。SDKの claude_code システムプロンプトプリセットは自動的にロードしません。

エージェント チーム

エージェントチームは実験的機能であり、デフォルトで無効です。単一セッション内で動作するサブエージェントとは異なり、個別のClaude Codeインスタンス全体で調整されます。

有効化

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Claude Code v2.1.32以上が必要です。

チーム ツール

ツール	用途
TeamCreate	Claudeインスタンスの新しいチームを作成
TaskCreate	チームメートにタスクを割り当て
TaskUpdate	タスクステータスを更新
TaskList	すべてのタスクとステータスをリスト
SendMessage	チームメート間の直接通信

アーキテクチャ

1つのセッションがチームリーダーとして機能し、作業を調整し結果を統合します。チームメートは独自のコンテキストウィンドウで独立して作業し、互いに直接通信できます — サブエージェントとは異なり、親に報告するのみです。

制限事項

• 標準セッション比で約 7倍のトークン使用量
• インプロセスチームメートでのセッション再開なし
• 潜在的なタスクステータスラグ
• リーダーが早期に完了を宣言する可能性

ガードレール トライアド

3つのガード システムがエージェント動作を制約するために連携します:

システム	メカニズム	設定
パーミッションモード	承認が必要な処理を制御	acceptEdits, bypassPermissions, default, dontAsk (TSのみ), plan
ツール許可/拒否リスト	利用可能なツールを制限	フロントマターの tools (許可) と disallowedTools (拒否)
フック	ライフサイクルポイントでの型付きコールバック	PreToolUse は実行を拒否可能; PostToolUse, SubagentStart, Notification, UserPromptSubmit

公式 ソース

上記のクイックリファレンス以上の完全なドキュメントが必要な場合は、サブエージェントの公式Claude Codeドキュメントを参照してください。参照するべき主要ページ:

• サブエージェント ドキュメント — ビルトインエージェント、作成、すべてのフロントマターフィールド、ツール制御、MCPスコーピング、フック、メモリ、例
• エージェント チーム ドキュメント — マルチエージェント調整、チーム設定、通信パターン

上記のクイックリファレンスセクションはほとんどのタスクに対する重要なスキーマを含みます。クイックリファレンスが特定の質問をカバーしていない場合にのみ、完全なドキュメントを参照してください。

実際のドキュメント ファイルを読んでください。フロントマターフィールド、ツール名、モデルオプション、またはネスト制約については、トレーニング知識に頼らないでください。