Claude Codeサブエージェント実践ガイド｜設計原則・公式実装例・活用事例

要約

Claude Codeのサブエージェント機能を実践的に活用するための設計原則、公式プラグインの実装パターン、Anthropicが提唱する4つのワークフローパターン、そしてXで注目の活用事例を解説する。「全体像編」で基本を理解した読者が、実際にサブエージェントを設計・構築するための実践ガイドである。

この記事を読むことで得られるメリット

この記事を読むことで以下のことが分かる:

• サブエージェント設計で必ず守るべき4原則を理解できる
• description の書き方で自動委譲の精度を高めるコツが分かる
• Skill↔Agent連携の2パターンの使い分けが判断できるようになる
• 公式プラグイン（code-review / feature-dev / pr-review-toolkit）の実装パターンから設計知を得られる
• Anthropicの4つのワークフローパターン（Routing / Parallelization / Orchestrator-Workers / Evaluator-Optimizer）を理解できる
• Xで話題の実践事例から、自分のプロジェクトへの応用イメージが湧く

この記事を読むのにかかる時間

約20分

環境

• Claude Code v2.1+
• macOS / Linux / Windows

設計の4原則

全体像編では「最小権限やモデル使い分けはできる」というカスタマイズの可能性を紹介した。実践編ではそれを「必ず守るべき原則」として再定義する。

原則1: 単一責任

1エージェント = 1つの専門領域。

肥大化したサブエージェントは、判断精度が落ちるだけでなく、他のプロジェクトでの再利用も難しくなる。1つのエージェントがコードレビューもデバッグもテストも担当するのではなく、それぞれを専門エージェントに分割すべきである。

公式も以下の鉄則を掲げている。

"3人の集中したチームメイトが5人の散漫なチームメイトを上回ることが多い"

原則2: ツールの最小権限

必要なツールのみ tools で明示許可する。

tools フィールドを省略すると、MCPツールを含むメイン会話の全ツールを継承してしまう。これは意図しないファイル変更や外部API呼び出しのリスクを生む。

例えば、コードレビュー専用エージェントなら tools: Read, Grep, Glob, Bash のみを許可し、Write/Edit を含めないことで読み取り専用を技術的に保証できる。

原則3: description を具体的に書く

description はサブエージェントの最重要フィールドである。Claudeはこのフィールドを読んで、「このタスクをこのサブエージェントに委譲すべきか」を自動判断する。

書き方の3つのコツ

1. "Use proactively" 句を必ず入れる — 自動委譲のトリガーとなる
2. "いつ委譲すべきか" を書く — 公式定義: "When Claude should delegate to this subagent"
3. トリガー条件を具体的に — "after code changes"、"when encountering errors" など

公式サンプルの description 例

copy# Code Reviewer
"Expert code review specialist. Proactively reviews code for quality,
security, and maintainability. Use immediately after writing or
modifying code."

# Debugger
"Debugging specialist for errors, test failures, and unexpected
behavior. Use proactively when encountering any issues."

いずれも**「いつ使うべきか」が明確**に記述されている点に注目してほしい。

原則4: Git管理

.claude/agents/ ディレクトリをGitリポジトリにコミットし、チーム全体で同じサブエージェント定義を共有する。これにより、エージェントの設定がコードと同じバージョン管理下に置かれ、変更履歴の追跡やレビューが可能になる。

Skill ↔ Agent 連携の2パターン

全体像編で触れた通り、サブエージェントはメインのスキルを継承しない。使いたい場合は明示指定が必要であり、その方法には2つのパターンがある。

パターンA: context: fork（Skill → Agent 呼び出し）

スキル側に context: fork を設定し、スキルの実行自体をサブエージェントとして隔離する方法である。

copy---
name: deep-research
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Glob/Grep で探索 → 2. コード解析 → 3. 要点を要約

• SKILL.md の本文がタスクとなり、結果のみメインに返る
• agent: フィールドで実行環境・ツール・権限が決まる（Explore / Plan / general-purpose / カスタムエージェント）
• 毎回同じ手順を隔離実行する用途に最適（調査・PR要約など）

パターンB: skills: プリロード（Agent 側に埋め込み）

サブエージェントのフロントマターで skills: を指定し、起動時にスキルの内容をコンテキストに注入する方法である。

copy---
name: api-developer
description: API development specialist with conventions knowledge
tools: Read, Edit, Write, Bash, Grep, Glob
skills:
  - api-conventions
---
You are an API development specialist...

• サブエージェントの独自システムプロンプトに、スキルの専門知識を追加で注入
• 動的なタスクに対応でき、Claudeの委譲メッセージに基づいて柔軟に動作
• 再利用可能な専門エージェントを構築する用途に最適

2パターンの使い分け

判断基準: 固定タスク → A、動的タスク → B。独自の役割定義が必要 → B、既存エージェント型の流用 → A。

なお、公式は規約のみのガイドライン系スキルに context: fork を使うことを推奨していない。タスクが存在しないため空回りしてしまうためである。

それ、本当にサブエージェントが必要か？

公式は "Skills are the most flexible extension."（スキルが最も柔軟な拡張機能）と述べている。サブエージェントを作る前に、まず context: fork スキルで対応できないかを検討するとよい。

共通点（どちらでもできること）

• メインのコンテキストを汚染しない
• ドメイン特化
• 自動呼び出し・明示呼び出しの両方に対応
• ツール権限の制限

context: fork スキルが優れる点

• 複数ファイル構成が可能（example / template / scripts を分割管理）
• context: fork の付け外しだけで「ツールとして実行」⇔「知識として提供」を切り替えられる

サブエージェントにしかない機能

• permissionMode: acceptEdits / dontAsk などの権限制御
• 永続メモリ: memory: project による会話横断の知識蓄積

結論: permissionMode や永続メモリが必要でないなら、スキルで十分である。

maxTurns・ネスト禁止・アンチパターン

maxTurns — 暴走防止の必須フィールド

maxTurns はAgent定義専用のフロントマターフィールドで、サブエージェントの最大ターン数を制限する。

• デフォルトは未設定（上限なし）のため、設定しないと暴走リスクがある
• 推奨値は10〜25: 小タスクなら10前後、複雑な調査なら25程度
• Skill では使用できない（Agent定義専用）

ネスト禁止という公式制約

"Subagents cannot spawn other subagents" — サブエージェントは他のサブエージェントを生成できない。これは無限再帰を防止するための設計上の制約である。

回避策として、親Agentの tools フィールドに Agent(worker, researcher) と記述することで、委譲先のサブエージェントを制限しつつオーケストレーション構成を実現できる。

よくある3つのアンチパターン

1. ツール指定省略: tools を書かないと全ツールを継承し、意図しない操作のリスクが生まれる
2. 同一ファイル並列編集: 複数のサブエージェントが同じファイルを同時に編集すると競合が発生する
3. 小タスクへの使用: サブエージェントの起動オーバーヘッドが利点を上回り、かえって遅くなる

公式プラグインから学ぶ実践的な使い方

Anthropicが公開している公式プラグインの実装を読むことで、ドキュメントだけでは分からない**「どう組み合わせるか」**という運用知が見えてくる。

バンドルスキルのサブエージェント活用

プラグイン不要で標準搭載されているスキルの中に、内部でサブエージェントを並列起動するものがある。

公式ドキュメントのサブエージェント設定例

公式ドキュメントには、汎用的な設定例が4つ掲載されている。

特にCode ReviewerとDebuggerの違いは示唆的である。同じレビュー系でも、ツール構成を変えるだけで「読み取り専用」と「修正可能」を使い分けられることが分かる。

code-review プラグイン — モデル使い分けの実例

/code-review プラグインは、カスタムサブエージェント定義を持たず、プロンプト内でTask ツール経由でHaiku / Sonnet を動的に使い分ける設計になっている。

ステップ4の5つの並列レビューでは、以下の5観点を同時にチェックしている。

1. CLAUDE.md準拠チェック
2. バグのシャロースキャン
3. git blame/履歴を踏まえた文脈バグ検出
4. 過去PRコメントとの照合
5. コード内コメントの整合性確認

設計のポイント: 軽い処理（対象判定・スコアリング）は安価なHaiku、深い分析（コードレビュー）はSonnetというコスト最適化が実践されている。

feature-dev プラグイン — 7フェーズ × 3エージェント

feature-devプラグインは、機能開発の全工程を7フェーズに分割し、3種類のサブエージェントを適切なタイミングで起動する。

color 属性（黄/緑/赤）により、ターミナル上でどのエージェントが動いているかを視覚的に識別できる。これは複数エージェントが並列動作する場面で非常に有用な設計である。

pr-review-toolkit — モデル選択の設計哲学

pr-review-toolkitは6つの専門エージェントでPRレビューを行う。

6つのうち code-simplifier のみ Opus を明示指定している。コード簡素化は「何を残して何を削るか」という最も高度な判断を要するため、品質を優先してOpusを使っている。残り5つは inherit（呼び出し元のモデル継承）で柔軟性を残す設計である。

この設計から読み取れる公式の哲学は、**「モデルの明示指定はコスト/品質のトレードオフが明確な場合のみ行う」**ということである。

サブエージェント構築の4つの設計パターン

Anthropicの公式リサーチ「Building Effective Agents」では、4つのワークフローパターンが定義されている。サブエージェントの構築にそのまま適用できる。

パターン1: Routing（振り分け）

受け取ったタスクを見てどの専門家に任せるかを最初に判断し、あとはその専門家に丸投げする。

• 向いている場面: タスクの種類が明確に分かれている（レビュー / デバッグ / 分析 など）
• メリット: 各専門家が得意分野に集中でき、軽いタスクは軽いモデルに回してコスト最適化が可能
• 実例: 顧客問い合わせの「返品 / 技術質問 / 請求」振り分け

パターン2: Parallelization（並列化）

同時に複数の作業を走らせて時短する（Sectioning）、または同じ問題を複数人で見て多数決で品質を上げる（Voting）。

• 向いている場面: 独立した作業が複数ある / 1つの判断の信頼度を上げたい
• メリット: 大幅な時短、互いの作業が干渉しない、多視点で見落とし減
• 実例: 5人が同じコードを別観点（バグ / セキュリティ / 規約 / 履歴 / コメント）で並行チェック — まさにcode-reviewプラグインのステップ4がこのパターンである

パターン3: Orchestrator-Workers（指揮者-実行者）

リーダー役がタスクを見て仕事を切り分け、部下に指示し、結果を統合する。誰に何を任せるかはタスクを見てから動的に決まるのが特徴で、Parallelization（事前固定）との最大の違いである。

• 向いている場面: 全貌が事前に予測できない大きく曖昧なタスク
• メリット: どんな複雑さでも対応可能、役割が固定されず柔軟
• 実例: 新機能実装で「どのファイルを変更するか」がタスク次第で毎回変わるケース

Anthropicのリサーチシステム実装では、Lead Agent（Opus）+ Subagents（Sonnet）構成で単一Opusを90.2%上回るパフォーマンスを達成した実績がある。

パターン4: Evaluator-Optimizer（評価者-最適化者）

「作る人」と「チェックする人」を分けて、ダメ出しを受けながら改善する反復プロセス。

• 向いている場面: 明確な合格基準があり、反復で品質が上がる性質のタスク
• メリット: 自己評価バイアスを避け、客観的な品質向上が可能
• 実例: 翻訳のニュアンス調整、検索の精度向上、コード品質の段階的改善

Xで注目の活用事例

実際のユーザーがどのようにサブエージェントを活用しているか、Xで話題になった事例を紹介する。

仮想組織・大規模並列運用

10部門40人の仮想組織を構築した事例（55万閲覧）が大きな反響を呼んだ。サブエージェントで「仮想社員チーム」を構築し、最適な担当を自動アサインする仕組みである。その後のフォローアップで40名→16名に統合し、CLAUDE.mdも61%削減したという改善レポートも注目を集めた。

また、10個同時並行リファクタリングの事例では、依頼内容ごとに一時サブエージェントを自動作成して並行作業を実施。tmux方式からサブエージェント方式への進化として報告されている。

TDDループ・MCP統合

CARTA Engineersが公開したTDD × 6人サブエージェントチームの事例も興味深い。6エージェントに役割を完全分担し、TDD × 最大10回の自動修正ループを回す構成である。レビュー役にはCodex CLIを外注することでコンテキスト上限を突破するテクニックも紹介されている。

また、.claude/agents/ にリファクタリング専門エージェントを定義し、/refactor スラッシュコマンドとMCP（Serena）を組み合わせた統合活用例も報告されている。

テンプレート・リソース

「最初に設定すべきサブエージェント8選」テンプレートは1,622ブックマークを獲得。作業効率20倍・ミス激減・料金節約といった効果が報告されている。

everything-claude-codeリポジトリ（Anthropicハッカソン優勝者の作品）は、28エージェント + 125ワークフロー + 300以上のコンポーネントを含む包括的なテンプレート集であり、サブエージェント構築の参考になる。

まとめ

本記事では、Claude Codeサブエージェント機能の実践的な活用方法を解説した。ポイントを振り返る。

• 設計の4原則: 単一責任 / 最小権限 / description に "Use proactively" / Git管理 — これらを外すとサブエージェントは破綻する
• Skill連携の判断: 固定タスクなら context: fork、動的タスクなら skills: プリロード。そもそも permissionMode / 永続メモリが不要ならスキルで十分
• 暴走防止: maxTurns の設定は必須（推奨10〜25）。アンチパターン（ツール指定省略 / 同一ファイル並列編集 / 小タスク）を避ける
• 公式プラグインの設計知: Haiku/Sonnet/Opusのモデル使い分け、color による視覚識別、ツール構成による読み取り専用制御など
• 4つのワークフロー: Routing / Parallelization / Orchestrator-Workers / Evaluator-Optimizer — タスクの性質に応じて適切なパターンを選択する

まずは公式のCode Reviewerサブエージェントを参考に、1つ作ってみることから始めるとよい。実際に使ってみることで、設計の勘所が掴めるはずである。