Subagents（役割分離 & 並列処理）

SubagentはClaude Code v1.x以上でサポートされる公式機能です。

単一のClaudeセッションですべてを処理していると、コンテキストが汚染され集中力が分散します。 Subagentは特定の役割のみを担う独立したAIインスタンスで、それぞれ別のコンテキストウィンドウで実行されます。

Subagentの核心的な特性

特性	説明
独立コンテキスト	メインセッションとは別のコンテキストウィンドウを持つ
ツール制限	許可されたツールのみ使用可能（セキュリティ＋トークン節約）
専用システムプロンプト	役割に合った指示を注入
独立権限	メインセッションと異なる権限レベルの設定が可能

Subagentの定義方法

.claude/agents/ フォルダにMarkdownファイルとして定義します。

📁 プロジェクトルート/
└── .claude/
    └── agents/
        ├── frontend-reviewer.md
        ├── test-writer.md
        └── db-migration.md

または会話画面で /agents コマンドを使って作成することもできます。

Subagentファイルの構造（Front-matter）

yaml

---
name: frontend-reviewer
description: React/TypeScriptコンポーネントのコードレビュー専門家。
             「UIをレビューして」「コンポーネントを確認して」という要求で自動トリガー。
tools: Read, Grep, Glob        # 読み取りのみ許可（変更不可）
model: claude-sonnet-4-5       # コスト削減のためSonnetを使用
---

あなたはReact/TypeScriptの専門家です。

## レビュー基準
- Propsの型定義が明確か
- 不要な再レンダリングがないか
- アクセシビリティ（a11y）属性が欠けていないか
- コンポーネントが単一責任の原則を守っているか

## 出力形式
問題点はファイル名と行番号を明記し、深刻度を[critical / warning / suggestion]に分類してください。

Front-matterオプションの全一覧

オプション	型	説明	デフォルト値
`name`	string	エージェントの識別子	ファイル名
`description`	string	トリガー条件を含む役割の説明	必須
`tools`	string	許可ツールの一覧（カンマ区切り）	すべて許可
`model`	string	使用するClaudeモデル	メインセッションのモデル

使用可能なツール一覧：

ツール	動作
`Read`	ファイルの読み取り
`Write`	ファイルの書き込み/作成
`Edit`	ファイルの編集
`Bash`	ターミナルコマンドの実行
`Grep`	ファイル内のテキスト検索
`Glob`	ファイルパターン検索
`WebFetch`	Webページの取得

💡 tools: Read, Grep, Glob のように読み取り専用ツールのみを許可すると、コードレビューエージェントが誤ってファイルを変更することを根本的に防ぎます。セキュリティとトークン節約の2つの効果があります。

並列 vs 逐次実行の判断基準

複数のエージェントを起動する際の最も重要な判断です。

条件	実行方式
タスクが互いに独立＋同じファイルを変更しない	並列実行 ✅
前の結果が次のステップに必要	逐次実行
同じファイルを2つのエージェントが変更する必要がある	逐次実行（競合防止）

並列実行の例（独立したタスク）：

バックエンドエージェント：/api フォルダのルート作成
フロントエンドエージェント：/components フォルダのUIコンポーネント作成
→ 異なるファイルを扱うため、同時に進行可能

逐次実行の例（依存関係のあるタスク）：

ステップ1：DBスキーマエージェント → schema.sql 生成
ステップ2：APIエージェント → ステップ1の結果を見てルート作成
→ ステップ2がステップ1の結果に依存するため逐次実行が必要

コスト計算 & 削減のヒント

サブエージェントはそれぞれ別のコンテキストウィンドウを使用します。3つのエージェントを並列実行すると、トークンが最大3倍消費されます。

モデル分離戦略（コスト削減の核心）：

bash

# メインセッション：Opus（複雑な判断、調整）
# サブエージェント：Sonnet（実行タスク）
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5"

.claude/agents/ ファイルでもモデルを個別に指定できます。

yaml

---
name: file-scanner
model: claude-haiku-4-5   # 単純なファイル探索はHaikuで
tools: Read, Glob
---

実践的な活用例

フルスタック機能開発

メインセッション（Opus）：要件分析 → タスク分割 → 結果統合
  ├── backend-agent（Sonnet）：APIルート、ビジネスロジック
  └── frontend-agent（Sonnet）：Reactコンポーネント、状態管理

コード品質パイプライン

メインセッション：/code-review コマンド実行
  ├── lint-agent：ESLint、TypeScriptエラーの検出
  ├── test-agent：テストカバレッジの分析
  └── security-agent：脆弱性スキャン

ドキュメント化の自動化

メインセッション：変更されたファイルの一覧を抽出
  └── doc-agent（Haiku）：各ファイルのJSDocコメントを更新

注意事項

サブエージェントが不要な場合 単純にタスクを「よりうまく」こなすためにエージェントを追加するのはコストの無駄です。タスクが独立して分離できない場合、単一セッションのほうがはるかに効率的です。

コンテキストの共有不可 サブエージェントはメインセッションの会話履歴を参照できません。必要なコンテキストはfront-matterのシステムプロンプトやファイルで渡す必要があります。

→ WATフレームワーク全体のコンテキストは wat-overview.md を参照

Subagents（役割分離 & 並列処理） ​

Subagentの核心的な特性 ​

Subagentの定義方法 ​

Subagentファイルの構造（Front-matter） ​

Front-matterオプションの全一覧 ​

並列 vs 逐次実行の判断基準 ​

コスト計算 & 削減のヒント ​

実践的な活用例 ​

フルスタック機能開発 ​

コード品質パイプライン ​

ドキュメント化の自動化 ​

注意事項 ​