第4章 §1-A

サブエージェント活用詳細（Claude中心）

Claude Code / Claude Desktop Appでサブエージェントを定義し、呼び出し、並列・自動化の単位に拡張する方法をClaude系列に限定してまとめた詳細文書 | 共通の概念は第4章 §1リファレンスで、Antigravity系列は第4章 §1-B Antigravity中心で扱う。

対象バージョンClaude Code / Claude Desktop App 2026-07リリース — Antigravity対応は§1-Bを参照

参照文書URLcode.claude.com/docs/en/sub-agents

文書収集日2026-07-14

バージョン確認方法Claude Code/App: claude --version

1. サブエージェントの定義

Claude Desktop AppとClaude Codeは、プロジェクトフォルダ配下にMarkdownファイル1つでサブエージェント1つを事前に定義する。Claude Desktop AppとClaude Codeは同じファイルを共有する — どちらも.claude/agents/*.mdを完全に同じ方式で認識する。

Claude Desktop App .claude/agents/*.md

プロジェクトルートの.claude/agents/フォルダにMarkdownファイルを置くと、Claude Desktop Appでも自動的にカスタムサブエージェントとして認識される。nameが後でsubagent_typeとして参照する識別子になる。Claude Code（CLI）でも全く同じファイルが全く同じ方式で動作する — 両者は同じサブエージェント定義フォーマットを共有している。

---
name: reviewer
description: テキストファイルの誤字と
  論理的な穴を検討する。
tools: Read, Grep
model: sonnet
---

あなたはレビュアーの役割を担う。与えられたファイルを
読み、改善点をリストにまとめて報告する。

Claude Code (CLI) — Claude Desktop Appと同一の.claude/agents/*.md

Claude Desktop Appで書いたものと全く同じ.claude/agents/*.mdファイルをそのまま認識する。Desktop AppとCLIの間でサブエージェント定義方式に違いはない。

frontmatterフィールド	Claude Desktop App / Claude Code (.claude/agents)
`name`	必須。`subagent_type`の値と一致して初めて呼び出し可能
`description`	このエージェントがいつ使われるかを説明し、自動トリガー判断の参考になる
`tools`	使用可能なツールの一覧。省略時はデフォルトセットを継承
`model`	`sonnet` / `opus` / `haiku`などのエイリアスを指定

2. サブエージェントの呼び出し/委任

Claude Desktop AppとClaude CodeはいずれもAgentツール（文書ではTaskツールとも呼ばれる）を呼び出し、独立したコンテキストを持つサブエージェントを起動する。

Claude Desktop App Agent(Task)ツール

Claude Desktop AppでもメインセッションはAgentツール（文書ではTaskツールとも呼ばれる）を呼び出し、独立したコンテキストを持つサブエージェントを起動する。サブエージェントはメインセッションの会話履歴を見ることができないため、promptに必要な背景を自己完結的に含めなければならない。Claude Code（CLI）も同じAgent/Taskツールをそのまま使う — チャット欄に自然言語で依頼すると、内部的には以下のような形で呼び出される。

Agent(
  description   = "認証モジュールのレビュー",
  prompt         = "src/auth/login.tsの
    セッション期限切れ処理ロジックを検討し、バグを探して。",
  subagent_type  = "reviewer"
)

Claude Code (CLI) — Claude Desktop Appと同一のAgent(Task)ツール

Claude Desktop Appと全く同じAgent/Taskツールの呼び出し方式である。ターミナルで自然言語で依頼すると、同じ方式でサブエージェントが起動する。

3. 並列実行

Claude系列は2つの方式で並列実行をサポートする。

Claude Desktop App Agent Teams — in-process

Claude Desktop Appでも実験的機能であるAgent Teamsをオンにすると、複数のチームメイトが並列で作業する。ただし、Desktop AppではteammateMode: in-processしか使えず、一部のキーボードナビゲーション（Shift+Downなど）が制限される。Claude Code（CLI）でも同じin-processモードがそのまま動作し、CLIではさらにtmux分割ウィンドウを使うtmuxモードも選択できる。

同じディレクトリ・Workspaceで複数のエージェントを同時に動かすと、「認知的重複（cognitive overlap）」が発生することがある — あるエージェントが同じフォルダで作業中の別エージェントの結果を、自分の作業コンテキストと誤認（ハルシネーション）してしまう問題である。作業ディレクトリやworktreeでエージェントを分離することが推奨される慣行である。

Claude Code (CLI) — 1つのメッセージで複数のAgent呼び出し

互いに依存関係のない作業が複数ある場合、1つのメッセージの中にAgent呼び出しを複数並べて同時に実行できる。Claude Codeはこれらの呼び出しを並列にディスパッチする。

Agent(description="APIドキュメント草案作成",
  prompt="...", subagent_type="writer")
Agent(description="テストカバレッジ点検",
  prompt="...", subagent_type="reviewer")

項目	Claude Desktop App	Claude Code (CLI)
並列実行単位	Agent Teams（in-processのみ）	1メッセージ内での複数Agent呼び出し / Agent Teams（in-process + tmux）

4. 自動化/フック

Claude系列における自動化・フックの違いは、AppとCodeの間にある。

Claude Desktop App — フック未発火

.claude/settings.jsonにPostToolUse/TeammateIdle/TaskCompletedフックを定義しても、Claude Desktop Appでは自動的に発火しない。フックが行うはずだった処理（例：監査スクリプトの実行）は、セッション終了後に手動で実行する必要がある。Claude Code（CLI）では同じ設定ファイルのフックがイベントに合わせて自動的に発火する — 自動化ゲートが必要なチームは、この点でコマンドラインインターフェース（CLI）を選ぶのが合理的である。

Claude Code (CLI) — フック自動発火

.claude/settings.jsonのPostToolUse/TeammateIdle/TaskCompletedフックが、ファイル保存や作業完了などのイベントに合わせて自動的に実行される。

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "bun scripts/audit.ts" }] }
    ]
  }
}

Agent Teamsは急速に発展中の機能である — フラグ名、デフォルト動作、UI構成がリリースごとに変わる可能性があるため、プロダクションワークフローに依存する前に最新のリリースノートを確認すること。

参考リンク

Claude Code/App 2026-07基準 | 2026年7月

← 前へ

第4章 §1・リファレンス

第4章 §1

Claude (A) Antigravity (B)

第4章 §2-A・実習