結論: Claude Code Sub-Agentsは、タスクを独立したコンテキストで処理する専門AIアシスタントです。並列実行により複雑なワークフローを劇的に高速化し、メインの会話コンテキストを汚染せずに大規模な調査・実装・レビューを完結させます。
この記事の要点:
- 要点1: Claude Code には Explore・Plan・General-purpose の3種類の組み込みSub-Agentsがあり、自動で最適なエージェントに処理を委譲する
- 要点2:
~/.claude/agents/または.claude/agents/にMarkdownファイルを置くだけでカスタムSub-Agentを作成でき、ツール制限・モデル選択・メモリが設定できる - 要点3: 独立したタスク3本を同時投入する並列パターンで作業時間を最大3分の1に短縮できる
対象読者: Claude Code を日常使いしており、さらに生産性を高めたいエンジニア・DX担当者・開発チームリード
読了後にできること: 自分のプロジェクトにカスタムSub-Agentを1本作成し、並列タスク処理を今日から実践できる
「Claude Codeって、なんで同じような指示を毎回タスクごとに書かないといけないんだろう？」
企業向けのAI研修でよく聞かれる質問です。研修先の開発チームで、あるシニアエンジニアがこう言っていました。「コードレビューのプロンプトを毎回コピペしているんですが、もっとスマートな方法ありますか？」と。
答えはシンプルで、Sub-Agentsを使えばいいんです。一度設定すれば、Claude Codeが「ああ、これはコードレビューの仕事だ」と自動で専門エージェントに委譲してくれます。毎回プロンプトを書く必要はありません。
しかもSub-Agentsは並列実行できます。「フロントエンドのコード調査」「バックエンドのAPI調査」「セキュリティチェック」を同時に走らせて、それぞれの結果をまとめて受け取る。これが当たり前にできるようになると、作業スピードが体感で2〜3倍になるんです。
この記事では、Claude Code Sub-Agentsの仕組みから実践パターンまで、コピペ可能な定義ファイルつきで全公開します。Claude Code Hooks（ID:5604）、Slash Commands（ID:5607）、MCP Server（ID:5611）、Plugin（ID:5613）、Skills（ID:5630）に続く、Claude Codeカスタム拡張シリーズの完成形です。
Sub-Agentsとは何か、なぜ必要なのか
Sub-Agentsは「独自のコンテキストウィンドウを持つ、専門化されたClaudeインスタンス」です。メインのClaude Codeセッションとは独立して動作し、タスクを処理し、結果だけを返します。
なぜこれが重要かというと、コンテキストウィンドウの問題があるからです。長いセッションでは、ファイルの読み込み結果・コード探索の痕跡・デバッグログが蓄積して、コンテキストがどんどん肥大化します。トークン消費が増え、推論の質が下がり、最終的にはコンテキスト上限に達してセッションを切り直すことになります。
Sub-Agentsはこの問題を根本から解決します。
| 問題 | Sub-Agentsなし | Sub-Agentsあり |
|---|---|---|
| ファイル探索の結果 | メインコンテキストに蓄積 | サブエージェントが処理して要約のみ返す |
| 並列タスク | 逐次実行（遅い） | 複数エージェントが同時並走（速い） |
| 専門タスクの設定 | 毎回プロンプトを書く | 定義済みエージェントに自動委譲 |
| ツール制限 | 全ツールにアクセス可能（危険） | 特定ツールのみに制限（安全） |
| コスト管理 | 全タスクが同じモデルで実行 | 簡単なタスクはHaikuで安く実行 |
Anthropicの公式ドキュメントには「サイドタスクが検索結果・ログ・ファイル内容でメインの会話を溢れさせる場合に使う」と書かれています。サブエージェントはそれを自分のコンテキストで処理して、要約だけを返す。これがSub-Agentsの本質です。
Claude Codeの全体的な活用方法については、AIエージェント導入完全ガイドも参考にしてください。
組み込みSub-Agentsの種類と動作
Claude Codeには最初から3種類の組み込みSub-Agentsが入っています。ユーザーが何もしなくても、Claudeが判断して自動的に使い分けます。
Explore：高速読み取り専用エージェント
Exploreは「コードベースの探索」に特化したエージェントです。
- モデル: Haiku（高速・低レイテンシ）
- 使えるツール: 読み取り専用ツールのみ（WriteとEditは拒否）
- 目的: ファイル探索、コード検索、コードベース分析
Claudeがコードベースを変更せずに検索・理解する必要があると判断したとき、自動でExploreに委譲します。探索結果はメインのコンテキストに入らず、Exploreが処理して要約だけが返ってきます。
Exploreを呼び出すとき、Claudeは詳細度レベルを指定できます。quick（ターゲットを絞った検索）、medium（バランス型）、very thorough（包括的分析）の3段階です。
Plan：計画モード用リサーチエージェント
Planは「プランモードでのコードベース調査」に特化したエージェントです。
- モデル: メイン会話から継承
- 使えるツール: 読み取り専用ツールのみ
- 目的: 計画立案前のコードベースリサーチ
プランモード（/planコマンド）でコードベースの理解が必要なとき、Claudeがリサーチ処理をPlanに委譲します。サブエージェントは別のサブエージェントを生成できない仕様（無限ネストの防止）なので、PlanがリサーチしてメインのClaudeが計画を立てる分業構造になっています。
General-purpose：汎用マルチステップエージェント
General-purposeは「探索と修正の両方が必要な複雑なタスク」を扱うエージェントです。
- モデル: メイン会話から継承
- 使えるツール: 全ツール
- 目的: 複雑なリサーチ、マルチステップ操作、コード修正
タスクが「探索と修正の両方」「複雑な推論での結果解釈」「複数の依存ステップ」を必要とするとき、Claudeが自動でGeneral-purposeに委譲します。
その他の組み込みエージェント
| エージェント | モデル | 自動起動タイミング |
|---|---|---|
| statusline-setup | Sonnet | /statuslineコマンド実行時 |
| claude-code-guide | Haiku | Claude Codeの機能について質問したとき |
カスタムSub-Agent作成の完全ガイド
組み込みエージェントに加えて、自分でカスタムSub-Agentsを作れます。一度作れば、Claudeが「このタスクはそのエージェントの仕事だ」と自動で判断して委譲してくれます。
Sub-Agentファイルの場所と優先順位
Sub-Agentsは優先順位順に4つの場所に置けます。
| 場所 | スコープ | 優先順位 | 作成方法 |
|---|---|---|---|
| マネージド設定 | 組織全体 | 1（最高） | 管理者がデプロイ |
--agents CLIフラグ | 現セッション | 2 | JSON指定で起動 |
.claude/agents/ | 現プロジェクト | 3 | インタラクティブ or 手動 |
~/.claude/agents/ | 全プロジェクト | 4 | インタラクティブ or 手動 |
プラグインのagents/ | プラグイン有効時 | 5（最低） | プラグインと一緒にインストール |
プロジェクトSub-Agent（.claude/agents/）は、コードベース固有のエージェントに最適です。バージョン管理にコミットすれば、チーム全員が同じエージェントを使えます。
ユーザーSub-Agent（~/.claude/agents/）は、全プロジェクトで使える個人専用のエージェントです。
Frontmatterフィールドの詳細
Sub-AgentファイルはYAML frontmatterつきのMarkdownファイルです。nameとdescriptionだけが必須で、他はオプションです。
---
name: code-reviewer
description: コードの品質・セキュリティ・ベストプラクティスをレビューする。コード変更後に自動的に使用する。
tools: Read, Glob, Grep
model: sonnet
---
あなたはシニアコードレビュアーです。コードを分析し、品質・セキュリティ・ベストプラクティスの観点から具体的で実行可能なフィードバックを提供します。
各フィールドの詳細は以下の通りです。
| フィールド | 必須 | 説明 |
|---|---|---|
name | Yes | 小文字とハイフンのみの一意識別子 |
description | Yes | Claudeがいつこのエージェントに委譲するかの説明（最重要） |
tools | No | 使えるツール。省略時は全ツールを継承 |
disallowedTools | No | 拒否するツール |
model | No | sonnet/opus/haikuまたはフルモデルID。省略時は親から継承 |
permissionMode | No | default/acceptEdits/auto/dontAsk/bypassPermissions/plan |
maxTurns | No | 最大ターン数（無制限の暴走防止） |
skills | No | 起動時にロードするスキル（親から継承しない） |
mcpServers | No | このエージェントが使えるMCPサーバー |
hooks | No | このエージェント固有のライフサイクルフック |
memory | No | 永続メモリのスコープ: user/project/local |
background | No | trueでバックグラウンドタスクとして常に実行 |
effort | No | 思考力レベル: low/medium/high/xhigh/max |
isolation | No | worktreeでgit worktreeの独立コピー上で実行 |
color | No | UIでの表示色: red/blue/green/yellow/purple/orange/pink/cyan |
/agentsコマンドで作成する（推奨）
最も簡単な方法は/agentsコマンドを使うことです。
/agents
コマンドを実行すると、タブインターフェースが開きます。Libraryタブで「Create new agent」を選び、「Personal」（~/.claude/agents/に保存）か「Project」（.claude/agents/に保存）を選択します。
「Generate with Claude」を選べば、エージェントの概要を説明するだけでClaudeが定義ファイルを生成してくれます。
コードのセキュリティを専門にチェックするエージェント。SQLインジェクション、XSS、認証漏れ、
秘密鍵のハードコードを検出して、修正提案とともに報告する。コード変更後に自動的に使用する。
Claudeがidentifier・description・system promptを生成してくれます。ツール選択（読み取り専用 or 全ツール）、モデル選択、表示色、メモリ設定を行って保存するだけです。
CLIフラグで一時的に作成する
ファイルを作らずに、セッションだけ有効なSub-AgentsをCLIフラグで定義できます。スクリプトや自動化に便利です。
claude --agents '{
"code-reviewer": {
"description": "シニアコードレビュアー。コード変更後に自動的に使用する。",
"prompt": "あなたはシニアコードレビュアーです。品質・セキュリティ・ベストプラクティスに集中してレビューします。",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "デバッグ専門家。エラーやテスト失敗時に使用する。",
"prompt": "あなたはエキスパートデバッガーです。エラーを分析し、根本原因を特定して修正を提案します。"
}
}'
Subagent Dispatch のベストプラクティス
Sub-Agentsを効果的に使うための最重要ポイントは「descriptionの書き方」です。Claudeはdescriptionを見て「このタスクはこのエージェントの仕事か」を判断します。曖昧なdescriptionだと、せっかく作ったエージェントが使われません。
description の書き方（重要）
---
name: security-reviewer
description: セキュリティの脆弱性を専門にチェックするレビュアー。SQLインジェクション・XSS・認証漏れ・
APIキーのハードコード等を検出する。コード変更後、プルリクエスト作成前に自動的に使用する。
tools: Read, Glob, Grep
model: sonnet
---
ポイントは「いつ使うか」を具体的に書くことです。「コード変更後に自動的に使用する」「プルリクエスト作成前に」「テスト失敗時に」のような起動タイミングを明示すると、Claudeが適切に判断できます。
また、descriptionは自然言語での指示を使って明示的に呼び出すこともできます。
security-reviewerエージェントを使って、このPRのコードをチェックしてください
モデルの使い分け
コスト最適化のために、タスクの複雑さに応じてモデルを使い分けます。
---
name: file-explorer
description: ファイルの検索・内容確認・コード探索。読み取りタスク全般。
tools: Read, Glob, Grep
model: haiku # 単純な読み取りはHaikuで十分
---
---
name: architecture-reviewer
description: システム設計・アーキテクチャのレビュー。複雑な設計判断や長期的な影響の分析。
tools: Read, Glob, Grep
model: opus # 深い推論が必要な設計レビューはOpusで
---
並列実行パターン（独立タスク3本同時投入）
Sub-Agentsの真価は並列実行にあります。依存関係のない複数タスクを同時に走らせることで、作業時間を大幅に短縮できます。
自然言語での並列指示
最もシンプルな並列実行は自然言語で指示するだけです。
以下の3つを並列で実行してください:
1. src/auth/ ディレクトリのAPIエンドポイントをすべてリストアップして、それぞれの目的を要約する
2. データベーススキーマを調査して、テーブル構造と関係を図示する
3. 認証フローを追跡して、ユーザーがログインしてからAPIを呼び出すまでのステップを説明する
Claudeが「これらは独立したタスクだ」と判断して、3つのサブエージェントを並列起動します。それぞれの探索結果がメインコンテキストを汚染することなく、要約だけが返ってきます。
カスタムSub-Agentsによる並列実行
ファイルに定義したカスタムSub-Agentsを複数同時に使うことも可能です。
frontend-reviewer・backend-reviewer・security-reviewerの3つを並列で使って、
今回のプルリクエストをレビューしてください。
研修先のある開発チームでこのパターンを導入したとき、コードレビューの所要時間が1時間から20分に短縮されました。3種類の観点（フロント・バック・セキュリティ）を並列でチェックできるためです。
事例区分: 想定シナリオ
以下は100社以上の研修経験をもとに構成した典型的なシナリオです。
7並列パターン（大規模機能実装）
コミュニティで実証されているパターンとして、新機能実装時に7つのタスクを並列実行する方法があります。
以下の7つを並列実行してください。それぞれ独立したサブエージェントで処理すること:
1. コンポーネントファイル (src/components/UserDashboard.tsx) を作成する
2. スタイルシート (src/styles/UserDashboard.module.css) を作成する
3. テストファイル (src/__tests__/UserDashboard.test.tsx) を作成する
4. TypeScript型定義 (src/types/UserDashboard.ts) を作成する
5. カスタムフック (src/hooks/useUserDashboard.ts) を作成する
6. APIインテグレーション (src/api/userDashboard.ts) を作成する
7. 設定ファイル (src/config/userDashboard.ts) を作成する
逐次実行なら7ステップ分の時間がかかるところを、並列で同時実行することで約1/3〜1/4の時間で完了します。ただし、同一ファイルへの同時書き込みは競合するので注意が必要です。
直列実行が必要な場合の見分け方
並列が有効なのは「タスク間に依存関係がない場合」だけです。以下のパターンでは直列実行が必要です。
| パターン | 直列が必要な理由 | 例 |
|---|---|---|
| ステップ2がステップ1の出力に依存 | 前のステップの完全な出力が必要 | テスト実行 → 失敗したテストを修正 |
| 同一ファイルへの書き込み | 並列書き込みで競合が発生 | 同じconfig.tsを複数が編集 |
| 共有状態の更新 | レースコンディションのリスク | 同じDBを複数エージェントが更新 |
| 確認が必要な重要操作 | 誤った操作の伝播を防ぐ | 本番環境のデプロイ |
判断基準はシンプルです。「タスクBを始めるためにタスクAの結果が必要か？」という問いに答えるだけです。YESなら直列、NOなら並列が正解です。
チーム共有パターン（リポジトリへのコミット）
プロジェクト固有のSub-Agentsは.claude/agents/に置いてバージョン管理にコミットすることで、チーム全員が同じエージェントを使えます。
# プロジェクト構成例
.claude/
agents/
code-reviewer.md # コードレビュー専門エージェント
security-checker.md # セキュリティチェック専門エージェント
test-generator.md # テスト自動生成エージェント
api-documenter.md # APIドキュメント生成エージェント
CLAUDE.md # プロジェクト全体のAI指示
新しいメンバーがリポジトリをクローンすると、チームで使っているSub-Agentsがすべて使えるようになります。オンボーディングの効率化にもなります。
ただし、.claude/agents/ のSub-Agentsはhooks・mcpServers・permissionModeフィールドをサポートしていないプラグイン由来のエージェントとは異なります。プロジェクト直下に置いたエージェントはこれらのフィールドが使えます。
SkillsとSub-Agentsの使い分け
Claude Codeには似た概念が複数あります。SkillsとSub-Agentsは混同されやすいので、明確に区別しておきます。
| 特徴 | Sub-Agents | Skills |
|---|---|---|
| 本質 | 独立したClaudeインスタンス | コンテキストに注入される知識・手順書 |
| 実行方法 | 別のコンテキストで独立して動作 | メインのClaudeが読み込んで使う |
| コンテキスト | 分離（メインを汚染しない） | 共有（メインコンテキストに含まれる） |
| 向いているもの | 調査・実装・レビューなどの実作業 | 手順書・ルール・ドメイン知識 |
| 保存場所 | ~/.claude/agents/ または .claude/agents/ | ~/.claude/skills/（Skillsスキル参照） |
| リポジトリ共有 | .claude/agents/ でコミット可能 | チーム共有にはPlugin経由が必要 |
判断基準は「実際に何かを実行させたいか（Sub-Agent）」「知識・ルールを教えたいか（Skill）」で分けられます。
Plugins・MCP Serverとの連携
Sub-AgentsはPlugin（Plugin開発ガイド）やMCP Server（MCP Server構築ガイド）と組み合わせることで、さらに強力なワークフローを構築できます。
MCP Serverと連携したSub-Agent
---
name: slack-notifier
description: タスク完了時にSlackに通知を送る。長時間処理が終わったときに自動的に使用する。
tools: Bash
mcpServers:
- slack
---
あなたはSlack通知の専門エージェントです。処理結果を受け取り、適切なSlackチャンネルに
サマリーを通知します。通知は簡潔に、アクションが必要な情報は太字で強調します。
Pluginを通じたSub-Agentの配布
チームやコミュニティ向けにSub-AgentsをPluginとして配布することもできます。Plugin内のagents/ディレクトリに置いたSub-Agentsは、Plugin利用者全員が使えるようになります。ただし、セキュリティ上の理由から、Plugin由来のSub-Agentsではhooks・mcpServers・permissionModeフィールドが無視されます。
# Pluginの構成例
my-team-plugin/
agents/
code-reviewer.md # チームのコードレビュー標準
test-generator.md # テスト自動生成
skills/
coding-standards.md # コーディング規約（知識）
manifest.json
実用Sub-Agent例10選
すぐに使えるカスタムSub-Agent定義ファイルを10個紹介します。それぞれ~/.claude/agents/または.claude/agents/に保存してください。
1. コードレビュアー（品質重視）
---
name: code-reviewer
description: コードの品質・可読性・ベストプラクティスをレビューする。コード変更後に自動的に使用する。
tools: Read, Glob, Grep
model: sonnet
color: blue
---
あなたはシニアソフトウェアエンジニアです。コードをレビューし、以下の観点で具体的なフィードバックを提供します:
- 可読性と命名規則
- パフォーマンスの問題
- エラーハンドリングの漏れ
- DRY原則の違反
- 型安全性
各指摘は「問題」「改善案」「理由」の3点セットで説明します。
仮定した点は必ず"仮定"と明記してください。
2. セキュリティチェッカー
---
name: security-checker
description: セキュリティの脆弱性を検出する専門エージェント。PRの前やデプロイ前に使用する。
tools: Read, Glob, Grep
model: sonnet
color: red
---
あなたはセキュリティ専門エージェントです。以下の脆弱性パターンを検出します:
- SQLインジェクション
- XSS（クロスサイトスクリプティング）
- 認証・認可の漏れ
- APIキー・秘密鍵のハードコード
- CSRF対策の欠如
- 安全でない依存パッケージ
深刻度（Critical/High/Medium/Low）をつけて報告します。
数字と固有名詞は、根拠（出典/計算式）を添えてください。
3. テスト生成エージェント
---
name: test-generator
description: 指定されたコードのユニットテストと統合テストを生成する。新規コード実装後に使用する。
tools: Read, Glob, Grep, Write, Edit
model: sonnet
color: green
---
あなたはテスト専門エンジニアです。指定されたコードを分析し、以下を生成します:
- ユニットテスト（正常系・異常系・境界値）
- 統合テスト（主要なワークフロー）
- モックとスタブの設定
80%以上のカバレッジを目標とします。テストケースには「何をテストするか」のコメントを必ず含めます。
不足している情報があれば、最初に質問してから作業を開始してください。
4. リファクタリングエージェント
---
name: refactoring-agent
description: コードのリファクタリングを専門に行う。技術的負債の解消・可読性向上・パフォーマンス改善。
tools: Read, Glob, Grep, Write, Edit, Bash
model: sonnet
color: orange
---
あなたはリファクタリング専門エンジニアです。コードを分析し、以下を実施します:
- 重複コードの除去（DRY化）
- 関数の分割（50行超の関数を適切に分割）
- 変数・関数名の改善
- デザインパターンの適用
リファクタリング前後の差分を説明します。動作が変わらないことを確認するため、テストを実行してください。
仮定した点は必ず"仮定"と明記してください。
5. コードベースリサーチャー
---
name: codebase-researcher
description: コードベースの構造・パターン・依存関係を調査する。新機能実装前のリサーチに使用する。
tools: Read, Glob, Grep
model: haiku
color: cyan
---
あなたはコードベース調査の専門エージェントです。指定された質問に答えるため:
- ファイル構造を分析する
- 関連するコードパターンを検索する
- 依存関係を追跡する
- 既存の実装パターンを特定する
調査結果は簡潔な要約と、根拠となるファイルパス・行番号を一緒に返します。
6. APIドキュメント生成エージェント
---
name: api-documenter
description: APIエンドポイントのドキュメントを自動生成する。APIコード変更後に使用する。
tools: Read, Glob, Grep, Write
model: sonnet
color: purple
---
あなたはAPIドキュメント専門エージェントです。コードを解析し、以下を含むOpenAPI形式のドキュメントを生成します:
- エンドポイントのパス・メソッド
- リクエスト・レスポンスのスキーマ
- 認証要件
- エラーレスポンスの種類
- 使用例
不足している情報があれば、最初に質問してから作業を開始してください。
7. パフォーマンス分析エージェント
---
name: performance-analyzer
description: パフォーマンスのボトルネックを特定する。遅いクエリ・非効率ループ・メモリリークを検出する。
tools: Read, Glob, Grep, Bash
model: sonnet
color: yellow
---
あなたはパフォーマンス最適化の専門エージェントです。以下を分析します:
- N+1クエリパターン
- 大きなデータセットの非効率な処理
- メモリリークの可能性
- 不要な再レンダリング（Reactの場合）
- キャッシュ機会の欠如
各問題に対して「影響度」「改善案」「改善後の期待値」を提示します。
数字と固有名詞は、根拠（出典/計算式）を添えてください。
8. データベーススキーマレビュアー
---
name: db-schema-reviewer
description: データベーススキーマの設計をレビューする。マイグレーション作成前・テーブル設計時に使用する。
tools: Read, Glob, Grep
model: sonnet
color: blue
---
あなたはデータベース設計の専門エージェントです。スキーマを分析し、以下を確認します:
- 正規化の問題（1NF/2NF/3NF）
- インデックスの最適化（不足・過剰）
- 外部キー制約の適切性
- データ型の選択ミス
- NULL許可の設計判断
改善提案は「Before（現状）」「After（改善後）」「理由」の形式で提示します。
9. 依存パッケージ監査エージェント
---
name: dependency-auditor
description: プロジェクトの依存パッケージを監査する。古いパッケージ・脆弱性・不要な依存を検出する。
tools: Read, Bash
model: haiku
color: pink
---
あなたは依存パッケージ監査の専門エージェントです。以下を確認します:
- セキュリティ脆弱性のある依存（npm audit / pip-audit等を実行）
- メジャーバージョンの更新が必要なパッケージ
- 未使用の依存パッケージ
- ライセンスの互換性問題
結果は「緊急度」別に分類して報告します。
10. コミットメッセージ生成エージェント
---
name: commit-message-writer
description: 変更内容を分析して適切なコミットメッセージを生成する。git commit実行前に使用する。
tools: Read, Bash
model: haiku
color: green
---
あなたはコミットメッセージ生成の専門エージェントです。git diffを分析し、Conventional Commits形式で
メッセージを生成します:
- feat: 新機能
- fix: バグ修正
- refactor: リファクタリング
- docs: ドキュメント
- test: テスト
- chore: その他
件名は50文字以内、本文は72文字で折り返します。「何を変えたか」より「なぜ変えたか」を重視します。
【要注意】よくある失敗パターンと回避策
失敗1：descriptionが曖昧でエージェントが使われない
❌ よくある間違い
---
name: reviewer
description: レビューします
---
⭕ 正しいアプローチ
---
name: code-reviewer
description: コードの品質・セキュリティ・ベストプラクティスをレビューする。
コード変更後、プルリクエスト作成前に自動的に使用する。
tools: Read, Glob, Grep
model: sonnet
---
なぜ重要か: ClaudeはdescriptionだけでどのSub-Agentに委譲するかを判断します。「いつ使うか」「何をするか」が明確でないと、Claudeが判断できずにエージェントが完全にスルーされます。企業研修でよく見るパターンで、「エージェント作ったのに全然使われない」という相談の9割がdescriptionの問題です。
失敗2：同じファイルを複数エージェントで並列編集する
❌ よくある間違い
以下を並列で実行してください:
1. src/config.ts のデータベース設定を更新する
2. src/config.ts のAPI設定を更新する
3. src/config.ts のキャッシュ設定を更新する
⭕ 正しいアプローチ
src/config.ts を以下の順番で更新してください:
1. データベース設定を更新する
2. API設定を更新する（データベース設定完了後）
3. キャッシュ設定を更新する（API設定完了後）
なぜ重要か: 同一ファイルへの並列書き込みは競合（コンフリクト）を起こします。最悪、ファイルが壊れます。並列実行できるのは「独立したファイルへの書き込み」だけです。同じファイルを更新する場合は直列で。
失敗3：Sub-AgentsをAgent Teamsと混同する
❌ よくある間違い
「複数のエージェントでリアルタイムに議論させたい」と思って、Sub-Agentsを使おうとする。
⭕ 正しいアプローチ
リアルタイムの協調・コミュニケーションが必要な場合はAgent Teamsを使う。Sub-Agentsは「fire-and-forget（投げっぱなし）」で結果だけが返ってくる設計です。エージェント間のリアルタイムなやり取りはできません。
| ケース | 使うべきもの |
|---|---|
| 独立したタスクを並列処理して結果を集める | Sub-Agents |
| 複数エージェントがリアルタイムに協調して問題を解く | Agent Teams |
| 専門エージェントに定型タスクを自動委譲する | Sub-Agents |
| 複数セッション間でのエージェント協調 | Agent Teams |
失敗4：過剰並列化でコストとオーバーヘッドが爆発する
❌ よくある間違い
以下の10個のファイルをそれぞれ別のエージェントで並列解析してください:
（ファイル1〜10を列挙）
⭕ 正しいアプローチ
関連するファイルをグループ化して、3〜5つのエージェントで処理する。不必要に多くのエージェントを起動すると、コーディネーションのオーバーヘッドとトークンコストが爆発します。Claude Codeは最大7つのエージェントを同時実行できますが、常に最大数が最適とは限りません。
経験則: 独立したドメイン（フロント・バック・DB・セキュリティ等）ごとに1エージェントが適切です。個々のファイルごとにエージェントを立てるのは過剰です。
永続メモリでエージェントを賢くする
Sub-Agentsにmemoryフィールドを設定すると、セッション間で学習を蓄積できます。
---
name: codebase-expert
description: このプロジェクトのコードベース専門家。アーキテクチャ・パターン・慣習を熟知している。
tools: Read, Glob, Grep
model: sonnet
memory: project # プロジェクトレベルのメモリ
color: blue
---
あなたはこのプロジェクトの専門エージェントです。セッションをまたいで以下を学習・記憶します:
- プロジェクト固有のアーキテクチャパターン
- チームのコーディング慣習
- 過去に発見した問題と解決策
- テクニカルデッドの箇所
新しい発見を見つけたら、必ずメモリに記録してください。
メモリスコープは3種類あります。
user:~/.claude/agent-memory/に保存。全プロジェクト共通project:.claude/agent-memory/に保存。プロジェクト固有local: ローカルマシンのみ（gitignoreに追加推奨）
Worktreeによる安全な並列実行
isolation: worktreeを設定すると、Sub-Agentがgit worktreeの独立したコピー上で動作します。実験的な変更や並列でのコード変更が安全になります。
---
name: experimental-refactorer
description: リファクタリング案を安全に試す。本番コードを変更せずに実験的な改修を行う。
tools: Read, Glob, Grep, Write, Edit, Bash
model: sonnet
isolation: worktree # 独立したworktreeで実行
color: orange
---
あなたは実験的リファクタリングの専門エージェントです。指定されたコードの改修案を
独立したworktreeで実施します。変更後はテストを実行して品質を確認します。
問題があれば報告し、ユーザーが取り込むかどうかを判断できるようにします。
変更がなければworktreeは自動でクリーンアップされます。
参考・出典
- Create custom subagents — Claude Code Docs — Anthropic（参照日: 2026-05-06）
- How and when to use subagents in Claude Code — Anthropic Claude Blog（参照日: 2026-05-06）
- Subagents in the SDK — Claude API Docs — Anthropic（参照日: 2026-05-06）
- Multi-agent parallel coding with Claude Code Subagents — Medium（参照日: 2026-05-06）
- I ignored Claude Code’s subagents until I realized what I was missing — XDA Developers（参照日: 2026-05-06）
まとめ：今日から始める3つのアクション
- 今日やること:
~/.claude/agents/ディレクトリを作成して、コードレビュー専用エージェント（上の例1番）を1つ配置し、「code-reviewerエージェントを使ってこのファイルをレビューして」と呼んでみる - 今週中: プロジェクトの
.claude/agents/にチーム共有のSub-Agentを3本作成して、バージョン管理にコミットする。description・tools・modelを最適化して、自動委譲が機能するか確認する - 今月中: 自分のワークフローを分析して「毎回手動でやっている繰り返しタスク」をSub-Agentsに委譲する。並列パターン（3本同時投入）を試して、作業時間の変化を測定する
あわせて読みたい:
- Claude Code Hooks完全ガイド2026 — PreToolUse/PostToolUseでSub-Agentと組み合わせた自動化
- Claude Skills エンタープライズ完全ガイド2026 — Sub-Agentsと併用する知識管理
- Claude Code完全ガイド2026 — Hooks/Slash Command/MCP/Plugin/Skillsとの全体像
次回予告: 次の記事では「Claude Code Agent Teams完全ガイド」をテーマに、複数セッション間でリアルタイム協調するエージェントチームの構築方法をお届けします。
著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。早稲田大学法学部在学中に生成AIの可能性に魅了され、X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援を展開。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。
ご質問・ご相談はお問い合わせフォームからお気軽にどうぞ。
