Claude Code エージェントのアーキテクチャ
Claude Codeは単なるコーディングアシスタントではなく、汎用的なエージェントフレームワークである。本記事では、Claude Codeの4つの主要コンポーネント（Subagent, Skills, Task, MCP）について、それぞれの役割、関係性、実践的な使い方を解説する。
目次
- 全体像：4つのコンポーネントの関係
- Task：サブエージェント呼び出しのメカニズム
- Subagent：独立したコンテキストを持つ専門エージェント
- Skills：オンデマンドで読み込まれる専門知識
- MCP：外部システムとの接続プロトコル
- 実践的な組み合わせパターン
- ベストプラクティスと注意点
全体像：4つのコンポーネントの関係
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code メインエージェント │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Skills │ │ Task │ │ MCP │ │
│ │(専門知識) │ │(委譲ツール)│ │(外部接続) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ │ ┌─────▼─────┐ │ │
│ │ │ Subagent │◄────────┘ │
│ └────────►│(専門エージェント)│ │
│ │ 独自コンテキスト│ │
│ └───────────┘ │
└─────────────────────────────────────────────────────────────────┘
| コンポーネント | 役割 | 特徴 |
|---|---|---|
| Task | サブエージェントを起動するツール | メインエージェントのみが使用可能 |
| Subagent | 独立して作業する専門エージェント | 独自のコンテキストウィンドウ、結果を返却 |
| Skills | 専門知識・ワークフローの定義 | オンデマンド読み込み、再利用可能 |
| MCP | 外部システムへの接続層 | GitHub, Slack, DB等へのブリッジ |
Task：サブエージェント呼び出しのメカニズム
Taskとは
TaskはClaude Codeがサブエージェントを呼び出すために使用する内部ツールです。「電話をかける」行為に相当し、サブエージェントは「電話を受ける専門家」に相当します。
動作の仕組み
[メインエージェント] ──(Taskツール)──> [サブエージェント]
│
▼
[独立して作業]
│
▼
[結果をメインに返却]
Taskの呼び出し方
サブエージェントは以下の方法で呼び出されます：
- 自動呼び出し：タスクの説明がサブエージェントの
descriptionにマッチした場合 - 明示的呼び出し：「code-reviewerサブエージェントを使って」と指示
# 明示的な呼び出し例
> code-reviewerサブエージェントを使って、この変更をレビューして
# 複数サブエージェントの並列呼び出し
> 複数のサブエージェントを使って、各マイクロサービスのログを分析して
重要な制約
- サブエージェントはTaskを使用できない：無限ネストを防止するため、サブエージェントからさらにサブエージェントを呼び出すことは不可
- 深さは1レベルのみ：メイン → サブの構造のみ許可
- 幅は制限なし：複数のサブエージェントを並列で呼び出し可能
Subagent：独立したコンテキストを持つ専門エージェント
Subagentとは
サブエージェントは、独自のコンテキストウィンドウを持ち、特定のタスクに特化した専門エージェントである。メインエージェントから委譲されたタスクを独立して実行し、結果のみを返却する。
サブエージェントの利点
- コンテキスト分離：メインの会話を汚染しない
- 並列実行：複数タスクを同時に処理
- 専門化：特定ドメインに最適化された指示
- ツール制限：必要最小限のツールアクセス
サブエージェントの定義
.claude/agents/（プロジェクト）または~/.claude/agents/（グローバル）にMarkdownファイルとして配置：
---
name: code-reviewer
description: コード品質、セキュリティ、ベストプラクティスのレビュー。
コード変更後に自動的に使用。
tools: Read, Grep, Glob
model: sonnet
---
You are a senior code reviewer with 15+ years of experience.
## Responsibilities
- Analyze code for security vulnerabilities
- Check adherence to coding standards
- Identify potential performance issues
- Suggest improvements and optimizations
## Review Checklist
1. Security: Check for SQL injection, XSS, CSRF
2. Performance: Identify N+1 queries, inefficient algorithms
3. Style: Verify consistent naming, proper commenting
4. Testing: Ensure adequate test coverage
ツールアクセスの設定
# 役割別の推奨ツール設定
Read-onlyエージェント: Read, Grep, Glob
リサーチエージェント: Read, Grep, Glob, WebFetch, WebSearch
コードライター: Read, Write, Edit, Bash, Glob, Grep
ドキュメントエージェント: Read, Write, Edit, Glob, Grep, WebFetch, WebSearch
組み込みサブエージェント
Claude Codeには以下の組み込みサブエージェントがあります：
- Plan subagent：プランモードでコードベースを探索
- Explore subagent：高速・軽量な読み取り専用エージェント
結果の返却
サブエージェントは独立して作業し、結果のみをメインに返却します：
[メイン] → [検索サブエージェント×3（並列）]
│
├─ サブ1: 認証関連ファイルを検索 → 関連ファイルリスト
├─ サブ2: テストパターンを検索 → テスト構造の要約
└─ サブ3: 設定ファイルを検索 → 設定の概要
│
▼
[メインが結果を統合して回答]
フルコンテキストではなくサマリーのみを返すことで、メインのコンテキストをクリーンに保ちます。
非同期実行
サブエージェントはバックグラウンドで実行可能です：
# Ctrl + B でバックグラウンドに送る
# 完了後に結果が返ってくる
Skills：オンデマンドで読み込まれる専門知識
Skillsとは
Skillsは、指示・スクリプト・リソースをまとめたフォルダで、Claudeが動的に読み込んで特定のタスクでのパフォーマンスを向上させます。「新人メンバーに渡すオンボーディングガイド」のようなものです。
Skillsの特徴
- 再利用可能：どのClaudeインスタンスでも使用可能
- ポータブル：Claude Code、Claude.ai、APIで共通
- オンデマンド読み込み：必要なときだけコンテキストに追加
段階的開示（Progressive Disclosure）
Skillsは効率的なコンテキスト管理のため、段階的に読み込まれる：
1. 起動時：name と description のみ読み込み（~100トークン）
↓
2. タスクマッチ時：SKILL.md の本文を読み込み
↓
3. 必要に応じて：補足ファイル（スクリプト、テンプレート等）を読み込み
Skillの定義
---
name: pdf-processing
description: PDFファイルからテキストやテーブルを抽出、フォーム入力、
ドキュメントのマージ。PDFファイルやフォーム、
ドキュメント抽出に関する作業時に使用。
---
# PDF Processing Skill
## Instructions
1. Use pypdf for text extraction
2. Use pdfplumber for table extraction
3. Use fillpdf for form filling
## Best Practices
- Always validate PDF structure before processing
- Handle encrypted PDFs gracefully
- Preserve original formatting when possible
## Examples
[具体的な使用例]
descriptionの重要性
Skillが適切に呼び出されるかはdescriptionの書き方に依存します：
# ❌ 悪い例（曖昧すぎる）
description: Helps with documents
# ✅ 良い例（具体的なアクションとキーワード）
description: Extract text and tables from PDF files, fill forms,
merge documents. Use when working with PDF files or
when the user mentions PDFs, forms, or document extraction.
プリビルトSkills
Anthropicが提供する組み込みSkills：
- PowerPoint (pptx)
- Excel (xlsx)
- Word (docx)
SubagentからのSkills呼び出し
サブエージェントもSkillsを参照できます：
[code-reviewサブエージェント]
│
├─ 独自のコンテキストウィンドウ
├─ 指定されたツール
└─ Skillsを参照可能
├─ Python best practices Skill
├─ Security review Skill
└─ etc.
MCP：外部システムとの接続プロトコル
MCPとは
MCP（Model Context Protocol）は、AIアプリケーションと外部ツール・データソースを接続する標準プロトコルです。USB-Cのような「ユニバーサルアダプター」として機能します。
MCPのアーキテクチャ
┌─────────────────────────────────────────┐
│ Claude Code / Apps │
│ │
│ ┌───────────────────────────────────┐ │
│ │ MCP Client │ │
│ └──────────┬──────────┬─────────────┘ │
│ │ │ │
└─────────────┼──────────┼────────────────┘
│ │
┌──────▼────┐ ┌──▼────────┐
│MCP Server │ │MCP Server │
│ (GitHub) │ │(Postgres) │
└───────────┘ └───────────┘
MCPサーバーの設定
// .mcp.json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp@latest"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "your-token"
}
}
}
}
MCPの主な用途
- 外部サービス連携：GitHub, Slack, Asana, Google Drive等
- データベースアクセス：PostgreSQL, MySQL等
- ブラウザ自動化：Playwright
- ファイルシステム操作：ローカルファイルへのアクセス
MCPの注意点
❌ 重いMCP使用（20kトークン以上はコンテキストを圧迫）
❌ ツールの無制限継承（意図的にホワイトリストを作成）
実践的な組み合わせパターン
パターン1：基本的なワークフロー
[ユーザー] → 「競合分析レポートを作成して」
[メインエージェント]
│
├─ MCP接続：Google Driveで競合ブリーフを検索、GitHubデータを取得
│
├─ Skills適用：competitive-analysis Skillが分析フレームワークを提供
│
└─ Subagent実行（並列）
├─ market-researcher：業界データを収集
└─ technical-analyst：技術実装をレビュー
│
▼
[結果を統合してレポート生成]
パターン2：マイクロサービス開発
# 複数リポジトリを参照
claude --add-dir ../user-service --add-dir ../auth-service --add-dir ../common-lib
[メインエージェント]
│
├─→ [Explorerサブエージェント]
│ - ../user-service を探索
│ - ../auth-service を探索
│ → 関連ファイルのマップを返す
│
├─→ [Architectサブエージェント]
│ → API契約・スキーマ設計を返す
│
├─→ [Implementerサブエージェント] (並列)
│ ├─ user-service側の実装
│ └─ auth-service側の実装
│
└─→ [Test-automatorサブエージェント]
→ 統合テストを生成
パターン3：Hooksによるチェーン化
サブエージェントのネストはできませんが、Hooksを使って順次チェーン化できます：
pm-spec → (ファイル出力) → architect-review → (ファイル出力) → implementer-tester
│ │ │
▼ ▼ ▼
仕様作成 アーキテクチャ検証 実装・テスト
READY_FOR_ARCH READY_FOR_BUILD DONE
パターン4：Git Worktreeによる並列開発
# 並列作業用のworktreeを作成
git worktree add ../project-feature-a -b feature-a
git worktree add ../project-feature-b -b feature-b
# 別々のターミナルでClaude Codeを起動
cd ../project-feature-a && claude
cd ../project-feature-b && claude
ベストプラクティスと注意点
推奨パターン
| パターン | 説明 |
|---|---|
| サブエージェント委譲 | Task(…)クローンパターンから始める |
| Git worktrees | 独立した機能の並列開発 |
| マルチClaude検証 | 書き込み/レビュー用に別コンテキスト |
| Skillsにユーティリティスクリプト | 即使用可能なツールを添付 |
| 生きたドキュメント | 実装中に計画を更新 |
避けるべきパターン
| パターン | 理由 |
|---|---|
| 複雑なマルチエージェントシステム | デバッグが悪夢になる |
| 重いMCP使用（>20kトークン） | コンテキストを圧迫 |
| 曖昧な指示 | 曖昧な結果につながる |
| 計画をスキップ | いきなりコードを書かない |
| コンテキストを限界まで埋める | 品質が劣化する |
コンテキスト管理の重要性
# コンテキストの確認
/context
# コンテキストのクリア
/clear
# コンパクト化
/compact
トークンコストの考慮
- サブエージェントは約20kトークンのオーバーヘッドがある
- 小さなタスクはメインスレッドで処理した方が効率的
- 並列実行は最大10同時（バッチ処理）
まとめ：いつ何を使うか
| 状況 | 推奨コンポーネント |
|---|---|
| 外部サービスとの連携が必要 | MCP |
| 並列処理・コンテキスト分離が必要 | Subagent (Taskで呼び出し) |
| 再利用可能な専門知識が必要 | Skills |
| 特定ワークフローを手動トリガー | Slash Commands |
| 自動的なルール適用 | Hooks |
アーキテクチャの進化
以前：Claude ←→ MCP（外部ツール直接呼び出し）
現在：Claude ←→ Subagent ←→ MCP（サブエージェントがMCPを使う）
Claude ←→ Skills（専門知識をオンデマンド読み込み）
MCPは「外部接続の標準プロトコル」として残りつつ、Task/Subagent + Skillsがワークフローの主軸になっています。MCPを直接メインコンテキストで使うより、サブエージェントに閉じ込めてコンテキスト汚染を防ぐパターンが推奨されます。