Subagentsで並列・分離処理する

Subagentとは何か

Subagentは、独立したコンテキストウィンドウで自律的に動作するエージェントです。.claude/agents/<name>.mdにMarkdownファイルとして定義し、 メインの会話とは完全に分離されたコンテキストでタスクを実行します。

メインの会話を汚さずに複雑なタスクを処理できるのが最大の利点です。 たとえば「大量のファイルを調査してレポートを作る」「APIからデータを取得して整形する」といった作業を Subagentに委譲すれば、メインの会話はシンプルなまま保てます。

Agent定義ファイルの全フロントマター

.claude/agents/<name>.mdのYAMLフロントマターで、Agentの動作を細かく制御できます。 以下が利用可能な全フィールドです。

---
name: my-agent
description: "PROACTIVELY use this agent when data fetching is needed"
tools:
  - WebFetch
  - Read
  - Write
  - Edit
disallowedTools:
  - Bash
model: sonnet
effort: medium
color: green
maxTurns: 5
permissionMode: acceptEdits
memory: project
skills:
  - my-domain-skill
mcpServers:
  my-api:
    command: npx
    args: ["-y", "@my-org/api-mcp"]
isolation: worktree
---

# Agent本文

ここにAgentの具体的な指示を記述します。

各フィールドの役割を解説します。

• name — 一意識別子。小文字とハイフンで構成します
• description — Agentの呼び出し条件を記述する最重要フィールド。PROACTIVELYというキーワードを含めると、Claudeが自動的にこのAgentを呼び出す頻度が上がります
• tools — このAgentが使用できるツールの一覧。省略すると全ツールを継承しますが、 必要最小限に制限することでAgentの行動範囲を絞れます
• disallowedTools — 明示的に拒否するツール。toolsの逆で、特定のツールだけを除外したいときに使います
• model — 使用するモデル。sonnet、opus、haiku、inherit（親と同じ）から選択
• effort — 思考レベル。low / medium / high / maxから選択
• color — CLI出力時の色。複数Agentを並列実行するときに区別しやすくなります
• maxTurns — 最大ターン数。暴走防止のために必ず設定してください。 設定しないとAgentが無制限に動作し続ける可能性があります。私は基本的に5を設定しています
• permissionMode — 権限モード。default（都度確認）、acceptEdits（編集自動承認）、dontAsk（全自動）、bypassPermissions（全チェックスキップ）、plan（読み取り専用）から選択
• memory — 永続メモリのスコープ。project、user、agentから選択。 セッション間で知識を保持できます
• skills — プリロードするSkill名のリスト。Agentの起動時にSkillの内容がコンテキストに注入されます
• mcpServers — このAgent専用のMCPサーバー設定。 特定のAPIやデータベースへの接続をAgent単位で管理できます
• isolation — worktreeを指定すると、git worktreeを使って独立したブランチで作業を実行します

Test Time Compute

同じモデルであっても、別のコンテキストウィンドウで実行するだけで結果が改善するという現象があります。 これはTest Time Compute（推論時計算）の考え方に基づいています。

Borisが推奨するパターンの1つに「1つのAgentがコードを書き、別のAgentがそのコードのバグを発見する」というものがあります。 同じSonnetモデルを使っていても、コンテキストが分離されているため、 2番目のAgentは1番目のAgentが持っていたバイアスに影響されません。

Git Worktreeでの分離実行

isolation: worktreeを設定すると、Agentは独立したgitブランチ上で作業を行います。 メインブランチのコードには一切影響を与えないため、安全に実験的な変更を行えます。

Borisが提唱する5つの活用法を紹介します。

• 1. 機能開発の並列化 — 複数の機能を別々のworktreeで同時に開発。 Agent Aが認証機能、Agent Bが通知機能を同時に実装するイメージです
• 2. レビューとコーディングの同時実行 — 1つのAgentがコードを書いている間に、 別のAgentが既存コードのレビューを行います。互いに干渉しません
• 3. 実験的変更の隔離 — 「このリファクタリングがうまくいくか試してみたい」という場面で、 メインブランチを汚さずに安全に実験できます
• 4. テストの並行実行 — テストスイートを複数のworktreeで並行に実行し、結果を集約します
• 5. リファクタリングの安全な実施 — 大規模なリファクタリングを隔離されたworktreeで実行し、 問題がなければメインブランチにマージします

---
name: feature-developer
description: "PROACTIVELY use for independent feature development"
model: sonnet
maxTurns: 10
permissionMode: acceptEdits
isolation: worktree
---

# 機能開発エージェント

独立したworktreeで機能開発を行います。
メインブランチに影響を与えずに安全に作業を進めてください。

Agent Memory

memoryフィールドを設定すると、Agentはセッション間で知識を永続化できます。 3つのスコープが用意されています。

• project — プロジェクト単位のメモリ。同じリポジトリ内の全Agentから参照可能
• user — ユーザー単位のメモリ。全プロジェクトで共有される個人設定や好み
• agent — Agent固有のメモリ。そのAgent専用の学習内容を保持

メモリは.claude/agent-memory/ディレクトリに保存されます。 SettingsのautoMemoryDirectoryで保存先をカスタマイズすることも可能です。

---
name: code-reviewer
description: "PROACTIVELY review code changes for quality issues"
model: sonnet
maxTurns: 5
memory: agent
---

# コードレビューエージェント

過去のレビューで発見したパターンをメモリに蓄積し、
次回以降のレビュー精度を向上させます。

Agent作成方法

Agentの作成方法は2つあります。

方法1: /agentsコマンドで対話的に作成

Claude Code内で/agentsコマンドを実行すると、対話形式でAgentを作成できます。 名前、説明、ツール制限などを質問に答える形で設定していきます。

方法2: Claudeに依頼して生成

「こういう用途のAgentを作って」とClaudeに指示すれば、.claude/agents/<name>.mdに適切なフロントマターと本文を生成してくれます。

複数Agentの連携パターン

実際のプロジェクトでは、1つのSubagentだけでなく複数のAgentを組み合わせてワークフローを構築するケースが多くなります。 ここでは実践的な3つの連携パターンを紹介します。

パターン1: パイプライン（直列処理）

リサーチAgent → 実装Agent → レビューAgentのように、前のAgentの出力を次のAgentの入力にするパターンです。 各Agentが専門領域に特化するため、それぞれの品質が向上します。

# コマンド側でパイプラインを制御する例（.claude/commands/implement-feature.md）

1. リサーチAgentに調査を委譲
   → Agent(subagent_type="researcher", prompt="○○の実装パターンを調査し、
      research-report.md に結果を書き出してください")

2. リサーチ結果を踏まえて実装Agentに委譲
   → Agent(subagent_type="implementer", prompt="research-report.md を読んで
      最適なパターンで実装してください")

3. 実装結果をレビューAgentに委譲
   → Agent(subagent_type="code-reviewer", prompt="今回の変更差分を
      レビューし、問題があれば修正してください")

このパターンのポイントは、各Agentが別々のコンテキストウィンドウで動作することです。 レビューAgentは実装Agentのバイアスに影響されないため、Test Time Computeの原理で品質が向上します。

パターン2: ファンアウト（並列調査→統合）

複数のAgentに並列で異なる調査を実行させ、結果を1つのAgentが統合するパターンです。 調査範囲が広い場合に特に有効です。

# 並列調査の例: 技術選定レポートの作成

# メインの会話から3つのAgentを同時に起動
Agent(subagent_type="researcher", prompt="Reactのstate管理ライブラリを
  調査し、react-state-report.md に書き出してください")

Agent(subagent_type="researcher", prompt="CSSフレームワークの選択肢を
  調査し、css-framework-report.md に書き出してください")

Agent(subagent_type="researcher", prompt="テストフレームワークの比較を
  調査し、testing-report.md に書き出してください")

# 3つのレポートが出揃ったら、統合Agentで最終レポートを作成
Agent(subagent_type="report-writer", prompt="*-report.md を全て読み、
  技術選定レポートとして統合してください")

並列実行のメリットは速度です。3つの調査を直列で行えば3倍の時間がかかりますが、 並列なら最も遅いAgentの完了を待つだけで済みます。

パターン3: 実装＋検証の対抗ペア

1つのAgentがコードを書き、別のAgentがそのコードのバグを見つける対抗的なペアです。 Borisが特に推奨するパターンで、同じSonnetモデルでも分離コンテキストのおかげでバグ発見率が上がります。

# .claude/agents/implementer.md
---
name: implementer
description: "PROACTIVELY use for feature implementation"
model: sonnet
maxTurns: 10
permissionMode: acceptEdits
---

# 実装エージェント
要求された機能を実装してください。
テストコードも書いてください。

# .claude/agents/bug-finder.md
---
name: bug-finder
description: "PROACTIVELY use to find bugs in recent changes"
model: sonnet
maxTurns: 5
permissionMode: plan
---

# バグ発見エージェント
直近の変更差分を読み、以下の観点でバグを探してください:
- エッジケースの漏れ
- nullチェック・型安全性
- 競合状態・非同期処理の問題
発見した問題を箇条書きでレポートしてください。

Agent間のコンテキスト共有

Subagentはそれぞれ独立したコンテキストウィンドウで動作するため、Agent間で直接データを受け渡す仕組みはありません。 では、どうやってAgent間で情報を共有するのか。3つの手法があります。

手法1: ファイルシステム経由（最も基本）

前のAgentがファイルに書き出し、次のAgentがそのファイルを読む。最もシンプルで確実な方法です。

# Agent Aの指示
「調査結果を /tmp/research-output.md に書き出してください」

# Agent Bの指示
「/tmp/research-output.md を読んで、その内容をもとに実装してください」

• メリット — 仕組みがシンプル。どのAgentでも利用可能。ファイルとして残るので後から確認できる
• デメリット — ファイルパスの管理が必要。一時ファイルのクリーンアップを忘れやすい
• 適する場面 — パイプライン型の連携、レポートや調査結果など構造化されたデータの受け渡し

手法2: Agent呼び出し時のpromptに結果を埋め込む

親のコンテキストがAgent Aの戻り値を受け取り、それをAgent Bのpromptに直接含める方法です。

# Commandやメインの会話で制御するイメージ

# Step 1: Agent Aを呼び出し、結果を受け取る
Agent(subagent_type="researcher",
  prompt="Reactのstate管理について調査してください")
→ Agent Aの結果がメインのコンテキストに返る

# Step 2: Agent Aの結果をAgent Bのpromptに含める
Agent(subagent_type="implementer",
  prompt="以下の調査結果を踏まえて実装してください: [Agent Aの結果]")

• メリット — ファイルを作らずに済む。Agent Bが必要な情報だけを受け取れる
• デメリット — 情報量が多いとpromptが長くなる。親のコンテキストも消費する
• 適する場面 — 受け渡す情報が少量のとき。「温度は25度」「ステータスはOK」などの短いデータ

手法3: Agent Memory経由（セッションをまたぐ共有）

memory: projectを設定したAgent同士は、セッションをまたいで知識を共有できます。 あるAgentが学習した内容を、別のAgentが次回のセッションで参照するという使い方です。

# .claude/agents/code-reviewer.md
---
name: code-reviewer
memory: project
---
# レビューで発見したパターンをメモリに蓄積

# .claude/agents/implementer.md
---
name: implementer
memory: project
---
# 過去のレビュー指摘をメモリから参照し、同じミスを避ける

• メリット — セッション間で知識が蓄積される。Agent同士が間接的に学び合える
• デメリット — リアルタイムの受け渡しには使えない（次回セッション以降に反映）
• 適する場面 — コードレビューの知見蓄積、プロジェクト固有のパターン学習

Subagentのデバッグ

Subagentが期待通りに動かないとき、メインの会話と違ってコンテキストの中身が見えにくいため、原因の特定に苦労することがあります。 以下のチェックリストを順番に確認してください。

1. descriptionが正しくトリガーされているか

Agentが呼び出されない場合、最も多い原因はdescriptionの記述が曖昧なことです。

• PROACTIVELYキーワードが含まれているか確認する
• 「いつ」「どんな状況で」呼び出すべきかが明確に書かれているか見直す
• 意図的に呼び出したい場合は、プロンプトに「use ○○ agent」と明示する

2. maxTurnsが足りているか

Agentが途中で止まる場合、maxTurnsの上限に達している可能性があります。 CLIの出力に「max turns reached」のような表示がないか確認してください。 まずはmaxTurnsを一時的に増やして問題が解消するか試します。

3. toolsの制限が厳しすぎないか

toolsでツールを制限している場合、Agentに必要なツールが含まれていない可能性があります。 たとえばファイルを読む必要があるのにReadが許可されていない、 コマンドを実行する必要があるのにBashが禁止されているなどです。

# デバッグ時: まず全ツールを許可して動作を確認
---
name: my-agent
# tools: を省略すると全ツールを継承
maxTurns: 10
---

# 動作確認後: 必要なツールだけに絞る
---
name: my-agent
tools:
  - Read
  - Write
  - Edit
  - Bash
maxTurns: 5
---

4. Agentの本文指示が具体的か

フロントマターの設定が正しくても、Agent本文の指示が曖昧だとAgentは迷走します。 「何をするか」だけでなく「どういう順序で」「出力をどこに書くか」まで具体的に指示してください。

• 入力：何を読むか（ファイルパス、変数名など）
• 処理：どんなステップで進めるか（番号付きリスト推奨）
• 出力：結果をどこに書くか（ファイルパス、フォーマット）

5. isolation: worktreeを活用した安全なデバッグ

Agentの動作が不安定なときは、isolation: worktreeをつけて安全に試行錯誤できます。 worktreeで実行すればメインブランチに影響を与えないため、Agentが予期しないファイル変更をしても問題ありません。

---
name: experimental-agent
description: "デバッグ用の実験的Agent"
model: sonnet
maxTurns: 10
permissionMode: acceptEdits
isolation: worktree
---

# 実験エージェント

このAgentはworktreeで隔離実行されます。
自由に実験的な変更を行ってください。
問題がなければ結果をメインブランチにマージします。

worktreeでの変更が期待通りであれば、そのままメインブランチにマージできます。 変更が不要な場合はworktreeが自動的にクリーンアップされます。

6. permissionModeを一時的に変更する

Agentが途中で権限確認のプロンプトを出して止まっている場合、 デバッグ時はpermissionMode: acceptEditsに変更して、 ファイル編集を自動承認させると原因の切り分けがしやすくなります。 ただし、本番運用では適切な権限レベルに戻すことを忘れないでください。

まとめ

Subagentは、Claude Codeの中で最もパワフルな機能の1つです。 分離コンテキストでの自律動作、git worktreeによる安全な並列開発、永続メモリによる学習の蓄積。 これらを組み合わせることで、単一のAIアシスタントでは実現できない高度なワークフローを構築できます。 まずはmaxTurns: 5を設定した安全なAgentから試してみてください。