TL;DR
- Claude Code の subagents は「数を増やせば速くなる」機能ではない。粒度設計と責務分離が精度を左右する
- 分割判断には タスク種別・コンテキスト汚染度・観点の独立性・統合コスト の4軸を使う
- 本記事では実運用で効いた設計パターン5選とアンチパターン3選を、設定ファイルの実装例とともに体系化する
なぜ subagent の「設計」が問題になるのか
分割しなければコンテキスト肥大化、分割しすぎれば統合コスト爆発
Claude Code の subagents を導入する動機は明快だ。1つのエージェントに全部任せると、探索ログ、テスト出力、レビュー観点が会話に混ざり、判断品質が落ちる。
しかし「とりあえず分割」も失敗する。3つに分けた subagent の出力を親が統合するとき、文脈のすり合わせコストがかかる。分割粒度が不適切だと、統合コストが分割メリットを上回る。
問題は「分けるか分けないか」ではなく、何を基準に分けるかだ。
判断基準がまだ共有されていない
Claude Code の subagents は Anthropic の公式ドキュメント で仕様が公開されている。しかし公式が提供するのは「subagents の仕組み」であって「どう設計すれば精度が出るか」ではない。
設計パターンの共有知はまだ少ない。本記事は、実運用で得た設計判断を体系化し、その空白を埋める。
Claude Code subagents の基本モデル（最小限おさらい）
subagent は親エージェントから独立したコンテキストで動く
Claude Code の subagents は、親エージェントが Task ツールを使って子エージェントを起動する仕組みだ（公式仕様）。子は親とは独立したコンテキストウィンドウで動作し、完了後に結果のみを親に返す。
この設計の意味は明確だ。子の探索ログやテスト出力は親のコンテキストを汚染しない。親は要件整理と最終判断に集中できる。
Agent Teams との位置づけの違い
Anthropic が発表した Agent Teams は、複数の Claude Code インスタンスが Git worktree を通じて並列に作業する仕組みだ。subagents が「1セッション内の分業」なら、Agent Teams は「複数セッションの並列作業」に当たる。
通信構造の詳細は Subagent / Agent Teams の通信構造比較 で整理している。本記事では subagents の設計パターンに集中する。
粒度設計の4つの判断軸
subagent をいつ、どう分けるかは、次の4軸で判断できる。この4軸は公式仕様ではなく、実運用から抽出した判断フレームワークだ（実務観察）。
軸1: タスク種別 ―― read-heavy か write-heavy か
ファイルを読んで分析する作業（レビュー、探索、要約）は分割しやすい。ファイルを書き換える作業（実装、リファクタリング）は競合が起きやすく、分割のリスクが高い。
まずは read-heavy タスクから subagent 化する。これは Codex の subagents でも共通する知見だ（Codex subagents の設計原則 参照）。
軸2: コンテキスト汚染度 ―― 他タスクの出力が邪魔になるか
grep の結果が 200 行、テストログが 500 行。これらが親の会話に残ると、本来の判断に必要な文脈が埋もれる。「この作業の中間出力は、親の判断にノイズか？」と問えば、分離すべきかどうかは判定しやすい。
軸3: 観点の独立性 ―― 並列実行しても結果が干渉しないか
SEOチェックとセキュリティレビューは独立して実行できる。一方、API設計とフロントエンド実装は相互に依存する。観点が独立していれば並列化の恩恵が大きい。
軸4: 成果物の統合コスト ―― 結果のマージは単純か複雑か
各 subagent の出力が「指摘リスト」や「要約」なら、親はそれを並べるだけで統合できる。出力が「コード変更」なら、コンフリクト解消が必要になる。統合コストが低いタスクほど、分割の投資対効果が高い。
flowchart TD
A["タスクを分割すべきか？"] --> B{"read-heavy か？"}
B -- Yes --> C{"観点は独立しているか？"}
B -- No --> D{"コンテキスト汚染度は高いか？"}
C -- Yes --> E{"統合コストは低いか？"}
C -- No --> F["分割せず親で処理"]
D -- Yes --> G["subagent で隔離（結果の要約のみ返す）"]
D -- No --> F
E -- Yes --> H["subagent で並列実行"]
E -- No --> I["逐次実行を検討"]
実運用で効いた設計パターン5選
以下の5パターンは、このリポジトリ（notionnext-blog）の .claude/agents/ 構成で実際に運用しているものだ（実務観察）。
パターン1: 観点別並列レビュー ―― 複数の視点を同時に走らせる
記事やコードを複数観点で同時にレビューするパターン。SEO、技術的正確性、読者体験、セキュリティなど、独立した観点を別々の subagent に割り当てる。
- 向いている場面: PR レビュー、記事の品質チェック、設計ドキュメントのレビュー
- タスク種別: read-heavy
- 統合コスト: 低（指摘リストを並べるだけ）
このリポジトリでは article-reviewer（品質・構成）と seo-specialist（SEO観点）を分けて走らせている。観点が干渉しないため、並列実行しても結果の質が落ちない。
パターン2: 探索と実装の分離（explorer / worker）
「まず調べる → 結果を踏まえて実装する」を別エージェントに分ける。explorer が影響範囲やコードベースの構造を調査し、その要約を基に worker が実装する。
- 向いている場面: バグ修正、リファクタリング、新機能の実装
- タスク種別: explorer は read-heavy、worker は write-heavy
- 統合コスト: 中（explorer の出力を worker への入力に整形する必要がある）
このリポジトリでは explorer-agent が「コードベースの探索・構造分析」を担い、実装系エージェントに情報を渡す設計になっている。
パターン3: 段階的精緻化 ―― draft → review → refine のパイプライン
1つの成果物を段階的に磨くパターン。ライターが初稿を書き、レビュアーが指摘し、ライターが改善する。逐次実行だが、各段階の責務が明確に分かれる。
- 向いている場面: 記事執筆、ドキュメント作成、設計書の策定
- タスク種別: write → read → write のサイクル
- 統合コスト: 低（パイプラインなので出力がそのまま次の入力）
このリポジトリの記事制作は article-writer → article-reviewer → 改善のパイプラインで動いている。
パターン4: ドメイン別分割 ―― フロントエンド / バックエンド / テストの専門化
コードベースのドメインごとに subagent を分ける。各エージェントは自分の領域の規約やパターンに精通した状態で作業する。
- 向いている場面: フルスタック開発、モノレポでの複数パッケージ変更
- タスク種別: write-heavy（注意が必要）
- 統合コスト: 高（ドメイン間の整合性を親が担保する必要がある）
write-heavy な分割にはリスクがある。API の型定義が変わったとき、フロントエンドとバックエンドの subagent が別々に対応すると不整合が起きる。親エージェントによる統合判断が重い。
パターン5: MCP 連携特化型 ―― 外部ツール操作を隔離する
MCP（Model Context Protocol）経由で外部ツールを操作する作業を、専用の subagent に隔離する。Slack通知、GitHub API操作、データベースクエリなど。
- 向いている場面: 外部サービスとの連携、データ取得、通知送信
- タスク種別: 混在（ただし外部I/Oが主）
- 統合コスト: 低（外部操作の結果を要約で返す）
外部ツール操作は待ち時間が発生しやすく、エラーハンドリングも固有のものが多い。親のコンテキストから切り離すことで、本体の作業が外部I/Oに引きずられなくなる。
設計パターン比較表
| パターン | 向いている場面 | タスク種別 | 統合コスト | 注意点 |
|---|---|---|---|---|
| 観点別並列レビュー | PRレビュー、品質チェック | read-heavy | 低 | 観点の重複に注意 |
| 探索 + 実装分離 | バグ修正、リファクタリング | read → write | 中 | explorer の出力形式を固定する |
| 段階的精緻化 | 記事執筆、設計書作成 | write → read → write | 低 | ループ回数の上限を決める |
| ドメイン別分割 | フルスタック開発 | write-heavy | 高 | ドメイン間の整合性を親が管理 |
| MCP 連携特化 | 外部サービス連携 | 混在 | 低 | エラーハンドリングを子に閉じる |
避けるべきアンチパターン3選
アンチパターン1: 過剰分割 ―― 統合コストが分割メリットを上回る
「細かく分ければ精度が上がる」は誤りだ。5つの subagent に分けたレビューで、各エージェントが似た指摘を出し、親がそれを重複排除する作業に追われるケースがある。
判定基準: subagent 1つあたりの作業時間が統合作業より短い場合、分割しすぎている。
アンチパターン2: 責務曖昧 ―― 重複作業と抜け漏れが同時に起きる
subagent A が「コードの品質」を、subagent B が「ベストプラクティス準拠」を担当する。この2つは重なる。結果として同じファイルに対する矛盾した指摘が出る一方、誰も担当していない観点が漏れる。
判定基準: 各 subagent の担当範囲を1文で説明できないなら、責務が曖昧だ。
アンチパターン3: 親への過負荷 ―― 統合役の親がボトルネック化する
5つの subagent がそれぞれ長文の分析結果を返す。親はそれを読み、矛盾を解消し、最終出力を組み立てる。結果として親のコンテキストが肥大化し、判断品質が落ちる。これは subagent で解決しようとした問題そのものだ。
判定基準: 親に返す出力形式を「要約 + 根拠リンク」に固定し、生データを親に渡さない設計にする。
設定ファイルで設計を実装する
CLAUDE.md での subagent 指示の書き方
Claude Code では、CLAUDE.md に subagent の利用方針を書くことで、セッション開始時から分業設計が効く（コンテキスト分業の設計 で詳述）。
## Subagent 方針
- PR レビュー時は、セキュリティ・テスト網羅性・保守性の3観点で
subagent を並列起動する
- 探索作業（grep, ファイル構造調査）は subagent に委譲し、
親には要約のみ返す
- write-heavy タスクの並列分割は原則行わない
このように方針を書いておくと、Claude Code は明示的な指示なしでも subagent を適切に起動しやすくなる（実務観察）。ただし、確実に起動させたい場合はプロンプトでの明示指示を併用すべきだ。
agents/ ディレクトリ構成の実例
このリポジトリでは .claude/agents/ に役割別のエージェント定義を置いている。以下は実際の構成の抜粋だ。
.claude/agents/
├── orchestrator.md # 全体調整・意思決定
├── explorer-agent.md # コードベース探索・構造分析（read-heavy）
├── article-writer.md # 記事執筆（write-heavy）
├── article-reviewer.md # 品質レビュー（read-heavy）
├── seo-specialist.md # SEO分析（read-heavy）
├── frontend-specialist.md # フロントエンド実装
├── backend-specialist.md # バックエンド実装
├── test-engineer.md # テスト実装
└── ...
各エージェント定義ファイルには、YAML frontmatter で name、description、tools、skills を指定する。
---
name: article-reviewer
description: 完成した記事に対してセルフレビュー、品質ゲート実行、
評価・修正を行うエージェント。
tools: Read, Grep, Glob, Bash, Write, Edit
skills: clean-code, reviewer-agent, article-self-review
---
この設計のポイントは、各エージェントの責務が description の1文で説明できることだ。1文で説明できない責務は、分割が足りないか、逆に曖昧すぎるかのどちらかである。
スキル定義ファイルの詳細は プロンプトを再利用可能な資産にする で扱っている。
Codex subagents との思想の違い
Claude Code と Codex の subagents は似た仕組みだが、設計思想のアクセントが異なる。
| 観点 | Claude Code subagents | Codex subagents |
|---|---|---|
| 主目的 | 役割分離による精度向上 | コンテキスト汚染防止 |
| 起動方式 | Task ツール経由で親が委譲 | 明示プロンプトで起動 |
| 設定の置き場 | CLAUDE.md + agents/ ディレクトリ | AGENTS.md + agents/ TOML |
| 特徴的な運用 | 観点別レビュー、段階的パイプライン | explorer / worker の切り分け |
Codex 側は「ノイジーな中間出力を親スレッドから切り離す」ことが起点で、Claude Code 側は「専門化した責務を持たせて判断品質を上げる」方向に寄っている。どちらが優れているかではなく、最適化の焦点が異なる。
Codex subagents の詳細は Codex subagents 入門 を参照。
FAQ
Claude Code の subagents とは何ですか？
親エージェントが Task ツールを使って起動する子エージェントのこと。子は親とは独立したコンテキストで動作し、完了後に結果のみを返す。これにより、探索やレビューの中間出力が親の判断を汚染しない設計が可能になる（公式ドキュメント）。
subagents の粒度はどのくらいに設計すべきですか？
本記事で提示した4軸（タスク種別・コンテキスト汚染度・観点の独立性・統合コスト）で判断する。一般的に、read-heavy で観点が独立し、統合コストが低いタスクから始めるのが安全だ。
subagents と Agent Teams の違いは何ですか？
subagents は1セッション内で親が子を起動する「セッション内分業」。Agent Teams は複数の Claude Code インスタンスが Git worktree で並列に作業する「セッション間並列」。規模と独立性が異なる。
subagents でよくある失敗パターンは？
過剰分割（統合コスト > 分割メリット）、責務曖昧（重複と漏れが同時発生）、親への過負荷（子の出力が多すぎて親のコンテキストが肥大化）の3つが典型的だ。
Claude Code で subagents を設定するにはどうすればいいですか？
CLAUDE.md に subagent の利用方針を記述し、.claude/agents/ ディレクトリに役割別のエージェント定義ファイルを配置する。各ファイルの frontmatter で name、description、tools、skills を指定する。
まとめ ―― 明日から試す3ステップ
Claude Code の subagents で精度を出すには、「とりあえず分割」ではなく、粒度設計と責務分離が必要だ。
明日から試すなら、この3ステップで始められる。
- read-heavy タスクを1つ選ぶ: PR レビュー、コードベース探索、ドキュメントチェックなど。write-heavy な並列実行は後回しにする
- 4軸で分割判断する: タスク種別、コンテキスト汚染度、観点の独立性、統合コストを確認し、分割すべきか判定する
- subagent の出力形式を固定する: 「要約 + 根拠リンク」のフォーマットで親に返す設計にし、親のコンテキスト肥大化を防ぐ
この3ステップで小さく回し、うまくいったパターンを .claude/agents/ に定義ファイルとして残す。マルチエージェント環境の整備については マルチエージェント・デザインパターン も参照してほしい。
設計パターンは万能の正解ではない。プロジェクトの規模、チーム構成、タスクの性質で最適解は変わる。本記事の判断フレームワークを起点に、自分のプロジェクトに合った分業設計を見つけてほしい。
参考リンク
関連記事
- Skill対Subagent使い分け基準 — Subagent と Skill の責務境界、5軸の判断テンプレ、87 skill / 23 subagent を運用するリポジトリの実例パターンを整理しています。
