Claude Code サブエージェント & MCP 実装実践ガイド：コード例とハンズオン【2025年8月版】¶
はじめに¶
Claude Code の革新的なサブエージェント機能と MCP (Model Context Protocol) 統合により、従来の単一 AI アシスタントから専門特化した複数エージェントによる分業体制へと開発環境が大きく進化しています。
本記事では、朝記事「AI エージェント開発革命：Claude Code & GitHub Copilot 最新アップデート完全ガイド」で紹介した概要をもとに、実際の実装コードと具体的なユースケースを通じて、実践的な導入方法を詳細に解説します。
この記事のポイント¶
専門特化エージェント体制
データベース、フロントエンド、API設計など分野別の専門エージェントを構築
外部ツール自動連携
GitHub、Jira、Slack、Database等への MCP による自動アクセス・操作
マルチエージェント協調
タスクに応じた最適エージェントの自動選択と連携実行
カスタムワークフロー自動化
プロジェクト固有の開発フローを完全自動化
Part 1: サブエージェント実装実践¶
1.1 基本的なカスタムエージェント作成¶
まず、専門特化エージェントの基本構造を実装します。
<!-- .claude/agents/database-specialist.md -->
# データベース設計専門エージェント
## 専門分野
- データベース設計・最適化
- ERD設計とスキーマ設計
- インデックス戦略とクエリ最適化
- データマイグレーション
## 使用モデル設定
```json
{
"model": "claude-3.5-sonnet",
"temperature": 0.1,
"max_tokens": 4000
}
コンテキスト¶
あなたはデータベース設計の専門家です。以下の原則に従って作業してください：
- 正規化原則の厳格な適用
- パフォーマンスを考慮したインデックス設計
- スケーラビリティを意識したアーキテクチャ
- セキュリティベストプラクティスの遵守
実行例テンプレート¶
- ERD生成: PlantUML/Mermaid形式で出力
- DDL生成: PostgreSQL/MySQL両対応
- パフォーマンス分析: 実行計画とボトルネック特定
```markdown <!-- .claude/agents/frontend-specialist.md --> # フロントエンド開発専門エージェント ## 専門分野 - React/TypeScript開発 - 状態管理（Redux Toolkit、Zustand） - コンポーネント設計パターン - パフォーマンス最適化 ## 使用モデル設定 ```json { "model": "gpt-4o", "temperature": 0.2, "max_tokens": 6000 }
コンテキスト¶
あなたはモダンフロントエンド開発の専門家です。以下を重視してください：
- TypeScript型安全性の確保
- Reactベストプラクティスの適用
- アクセシビリティ（a11y）対応
- バンドルサイズ最適化
コーディング規約¶
- 関数コンポーネント + Hooks使用
- カスタムHooksによるロジック分離
- Storybook対応のコンポーネント設計
- Jest + Testing Library による単体テスト
### 1.2 高度なエージェント設定 より具体的な実装例として、API開発専門エージェントを作成します。 ```markdown <!-- .claude/agents/api-specialist.md --> # REST API・GraphQL開発専門エージェント ## 専門分野と実装方針 ### REST API設計 - OpenAPI 3.0準拠の仕様書作成 - RESTful設計原則の厳格な適用 - エラーハンドリング標準化 - レート制限・認証機構実装 ### GraphQL開発 - スキーマファーストアプローチ - DataLoader によるN+1問題対策 - サブスクリプション実装 - 型安全なResolver設計 ## 使用技術スタック ```json { "backend": { "framework": "Express.js / Fastify", "orm": "Prisma / TypeORM", "validation": "Joi / Zod", "documentation": "Swagger / GraphQL Playground" }, "testing": { "unit": "Jest", "integration": "Supertest", "e2e": "Playwright" } }
実装テンプレート生成機能¶
エージェント呼び出し時に以下を自動生成：
- API仕様書 (OpenAPI YAML)
- 型定義ファイル (TypeScript interfaces)
- バリデーションスキーマ (Zod/Joi)
- テストケース骨格 (Jest test suites)
- ドキュメント (README + API docs)
セキュリティチェックリスト¶
- 入力値検証の実装
- SQLインジェクション対策
- XSS対策実装
- CORS設定確認
- レート制限設定
- JWT トークン検証
- 機密情報のログ出力防止
### 1.3 エージェント呼び出しと協調例 実際のプロジェクトでエージェント間の協調を実現する方法： ```bash # Claude Code でのエージェント呼び出し例 # 1. データベース設計フェーズ /agent database-specialist "ユーザー管理システムのERD設計とPostgreSQL DDL生成" # 2. API設計フェーズ /agent api-specialist "ユーザー管理APIのOpenAPI仕様書とExpressルート実装" # 3. フロントエンド実装フェーズ /agent frontend-specialist "ユーザー管理画面のReactコンポーネント実装（TypeScript + Material-UI）"
Part 2: MCP 統合実装実践¶
2.1 基本的なMCPサーバー設定¶
Claude Code に外部サービスを統合するMCP設定を実装します。
<!-- ~/.claude/mcp_settings.json -->
{
"mcpServers": {
"github": {
"command": "node",
"args": ["/usr/local/lib/node_modules/@github/mcp-server/dist/index.js"],
"env": {
"GITHUB_TOKEN": "${{ secrets.GITHUB_TOKEN }}"
}
},
"jira": {
"command": "python",
"args": ["-m", "mcp_jira.server"],
"env": {
"JIRA_URL": "https://company.atlassian.net",
"JIRA_TOKEN": "${{ secrets.JIRA_API_TOKEN }}",
"JIRA_EMAIL": "${{ secrets.JIRA_EMAIL }}"
}
},
"database": {
"command": "python",
"args": ["-m", "mcp_postgres"],
"env": {
"DATABASE_URL": "${{ secrets.DATABASE_URL }}"
}
},
"slack": {
"command": "node",
"args": ["./custom-mcp-servers/slack-server.js"],
"env": {
"SLACK_BOT_TOKEN": "${{ secrets.SLACK_BOT_TOKEN }}",
"SLACK_SIGNING_SECRET": "${{ secrets.SLACK_SIGNING_SECRET }}"
}
}
}
}
2.2 カスタムMCPサーバー実装¶
実際のプロジェクトニーズに合わせたカスタムMCPサーバーを実装します。
// custom-mcp-servers/project-manager-server.js
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
CallToolRequestSchema,
ErrorCode,
ListToolsRequestSchema,
McpError,
} from '@modelcontextprotocol/sdk/types.js';
const server = new Server(
{
name: 'project-manager',
version: '0.1.0',
},
{
capabilities: {
tools: {},
},
}
);
// プロジェクト管理ツール定義
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: 'create_epic',
description: 'Jira エピック作成とGitHub Project連携',
inputSchema: {
type: 'object',
properties: {
title: { type: 'string', description: 'エピックタイトル' },
description: { type: 'string', description: '詳細説明' },
components: {
type: 'array',
items: { type: 'string' },
description: '関連コンポーネント'
},
priority: {
type: 'string',
enum: ['high', 'medium', 'low'],
description: '優先度'
}
},
required: ['title', 'description']
}
},
{
name: 'sync_development_status',
description: 'GitHub PR状況とJiraチケットの自動同期',
inputSchema: {
type: 'object',
properties: {
repository: { type: 'string', description: 'GitHubリポジトリ名' },
epic_key: { type: 'string', description: 'JiraエピックキーX' }
},
required: ['repository', 'epic_key']
}
},
{
name: 'generate_release_notes',
description: '自動リリースノート生成（GitHub + Jira統合）',
inputSchema: {
type: 'object',
properties: {
version: { type: 'string', description: 'リリースバージョン' },
from_tag: { type: 'string', description: '比較開始タグ' },
to_tag: { type: 'string', description: '比較終了タグ' }
},
required: ['version']
}
}
]
};
});
// ツール実行ハンドラー
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
switch (name) {
case 'create_epic':
return await createEpicWithGitHubIntegration(args);
case 'sync_development_status':
return await syncDevelopmentStatus(args);
case 'generate_release_notes':
return await generateReleaseNotes(args);
default:
throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
}
});
// 実装関数
async function createEpicWithGitHubIntegration({ title, description, components, priority }) {
try {
// 1. Jira エピック作成
const jiraResponse = await fetch(`${process.env.JIRA_URL}/rest/api/2/issue`, {
method: 'POST',
headers: {
'Authorization': `Basic ${Buffer.from(`${process.env.JIRA_EMAIL}:${process.env.JIRA_TOKEN}`).toString('base64')}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
fields: {
project: { key: 'PROJ' },
summary: title,
description: description,
issuetype: { name: 'Epic' },
priority: { name: priority || 'medium' },
components: components?.map(name => ({ name })) || []
}
})
});
const jiraEpic = await jiraResponse.json();
const epicKey = jiraEpic.key;
// 2. GitHub Project への Epic 追加
const githubResponse = await fetch('https://api.github.com/graphql', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.GITHUB_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
query: `
mutation CreateProjectItem($projectId: ID!, $contentId: ID!) {
addProjectV2ItemById(input: {projectId: $projectId, contentId: $contentId}) {
item {
id
}
}
}
`,
variables: {
projectId: process.env.GITHUB_PROJECT_ID,
contentId: jiraEpic.id
}
})
});
return {
content: [
{
type: 'text',
text: JSON.stringify({
success: true,
jira_epic: {
key: epicKey,
url: `${process.env.JIRA_URL}/browse/${epicKey}`
},
github_project: {
item_id: (await githubResponse.json()).data.addProjectV2ItemById.item.id
}
}, null, 2)
}
]
};
} catch (error) {
throw new McpError(ErrorCode.InternalError, `Epic creation failed: ${error.message}`);
}
}
async function syncDevelopmentStatus({ repository, epic_key }) {
// GitHub PRとJiraチケットの同期ロジック実装
const pullRequests = await fetchPullRequests(repository);
const jiraTickets = await fetchJiraTickets(epic_key);
const syncResults = await Promise.all([
updateJiraFromGitHub(pullRequests, jiraTickets),
updateGitHubFromJira(jiraTickets, pullRequests)
]);
return {
content: [{
type: 'text',
text: JSON.stringify({ sync_results: syncResults }, null, 2)
}]
};
}
// サーバー起動
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
}
main().catch((error) => {
console.error('Server error:', error);
process.exit(1);
});
2.3 Docker化されたMCPサーバー構築¶
本格的な運用を想定したDocker化MCPサーバーを構築します。
# custom-mcp-servers/Dockerfile
FROM node:18-alpine
WORKDIR /app
# 依存関係インストール
COPY package*.json ./
RUN npm ci --only=production
# アプリケーションコード
COPY src/ ./src/
COPY config/ ./config/
# セキュリティ設定
RUN addgroup -g 1001 -S nodejs
RUN adduser -S nodejs -u 1001
USER nodejs
# ヘルスチェック設定
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD node healthcheck.js
EXPOSE 3000
CMD ["node", "src/server.js"]
# docker-compose.mcp.yml
version: '3.8'
services:
mcp-project-manager:
build: ./custom-mcp-servers
environment:
- JIRA_URL=${JIRA_URL}
- JIRA_TOKEN=${JIRA_TOKEN}
- JIRA_EMAIL=${JIRA_EMAIL}
- GITHUB_TOKEN=${GITHUB_TOKEN}
- GITHUB_PROJECT_ID=${GITHUB_PROJECT_ID}
- DATABASE_URL=${DATABASE_URL}
volumes:
- ./config:/app/config:ro
- ./logs:/app/logs
networks:
- mcp-network
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 10s
retries: 3
mcp-database-manager:
image: postgres:15
environment:
POSTGRES_DB: mcp_development
POSTGRES_USER: mcp_user
POSTGRES_PASSWORD: ${MCP_DB_PASSWORD}
volumes:
- mcp_postgres_data:/var/lib/postgresql/data
- ./db/migrations:/docker-entrypoint-initdb.d
networks:
- mcp-network
restart: unless-stopped
networks:
mcp-network:
driver: bridge
volumes:
mcp_postgres_data:
Part 3: 実践的なユースケース実装¶
3.1 自動化ワークフロー実装例¶
完全なプロジェクト開始から本番デプロイまでの自動化を実装します。
# カスタムスラッシュコマンド実装
# .claude/commands/project-init.md
# 新規プロジェクト完全自動化コマンド
以下の手順で新規プロジェクトを完全自動化で立ち上げます：
## 1. プロジェクト企画段階
/agent project-manager "新規プロジェクト企画: ${PROJECT_NAME}"
- Jira エピック作成
- GitHub リポジトリ作成
- プロジェクト構造初期化
## 2. データベース設計
/agent database-specialist "プロジェクト要件に基づくデータベース設計"
- ERD設計
- DDL生成
- マイグレーションファイル作成
## 3. API設計・実装
/agent api-specialist "${PROJECT_NAME} REST API設計と実装"
- OpenAPI仕様書作成
- Express.js ルート実装
- バリデーション設定
## 4. フロントエンド実装
/agent frontend-specialist "${PROJECT_NAME} UI/UXコンポーネント実装"
- React コンポーネント作成
- 状態管理実装
- レスポンシブデザイン適用
## 5. インフラ・デプロイ設定
/agent devops-specialist "CI/CD パイプライン構築"
- Docker 化
- GitHub Actions 設定
- 本番環境デプロイ自動化
変数設定:
- PROJECT_NAME: プロジェクト名
- DATABASE_TYPE: PostgreSQL/MySQL
- FRONTEND_FRAMEWORK: React/Vue/Angular
- DEPLOYMENT_TARGET: AWS/GCP/Azure
3.2 品質保証自動化¶
開発品質を自動的に担保するエージェント協調システム：
<!-- .claude/agents/qa-specialist.md -->
# 品質保証専門エージェント
## 責任範囲
- コード品質チェック
- セキュリティ脆弱性検査
- パフォーマンス測定
- 自動テスト生成・実行
## 実行チェックリスト
### コード品質
- [ ] ESLint/Prettier フォーマット確認
- [ ] TypeScript 型エラーゼロ
- [ ] コードカバレッジ80%以上
- [ ] 循環的複雑度チェック
### セキュリティ
- [ ] npm audit / yarn audit 実行
- [ ] OWASP 脆弱性チェック
- [ ] 機密情報ハードコード検査
- [ ] CORS/CSRF 対策確認
### パフォーマンス
- [ ] バンドルサイズ分析
- [ ] Lighthouse スコア90以上
- [ ] メモリリーク検査
- [ ] N+1 クエリ検出
## 自動実行コマンド例
```bash
# 全品質チェック実行
/agent qa-specialist "プロジェクト全体の品質監査実行"
# 特定機能の品質チェック
/agent qa-specialist "ユーザー認証機能のセキュリティ監査"
### 3.3 リアルタイム監視・アラート連携
本番環境でのリアルタイム監視とSlack連携自動化：
```javascript
// custom-mcp-servers/monitoring-server.js
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
const server = new Server({
name: 'monitoring-server',
version: '0.1.0',
}, {
capabilities: { tools: {} }
});
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: 'setup_monitoring',
description: 'アプリケーション監視とアラート設定',
inputSchema: {
type: 'object',
properties: {
application_name: { type: 'string' },
environments: {
type: 'array',
items: { type: 'string' }
},
alert_channels: {
type: 'object',
properties: {
slack_channel: { type: 'string' },
email_list: {
type: 'array',
items: { type: 'string' }
}
}
},
thresholds: {
type: 'object',
properties: {
response_time_ms: { type: 'number' },
error_rate_percent: { type: 'number' },
cpu_usage_percent: { type: 'number' },
memory_usage_percent: { type: 'number' }
}
}
},
required: ['application_name', 'environments']
}
},
{
name: 'incident_response',
description: '障害対応自動化（調査・復旧・報告）',
inputSchema: {
type: 'object',
properties: {
incident_type: {
type: 'string',
enum: ['performance', 'error', 'downtime', 'security']
},
severity: {
type: 'string',
enum: ['critical', 'high', 'medium', 'low']
},
auto_recovery: { type: 'boolean' }
},
required: ['incident_type', 'severity']
}
}
]
};
});
// 監視設定実装
async function setupMonitoring(args) {
const {
application_name,
environments,
alert_channels,
thresholds
} = args;
// 1. Prometheus/Grafana設定生成
const prometheusConfig = generatePrometheusConfig(application_name, environments);
// 2. Grafanaダッシュボード作成
const grafanaDashboard = await createGrafanaDashboard(application_name, thresholds);
// 3. AlertManager ルール設定
const alertRules = generateAlertRules(thresholds, alert_channels);
// 4. Slack WebHook 設定
await setupSlackIntegration(alert_channels.slack_channel);
return {
content: [{
type: 'text',
text: JSON.stringify({
monitoring_setup: {
prometheus_config: prometheusConfig,
grafana_dashboard_url: grafanaDashboard.url,
alert_rules_count: alertRules.length,
slack_integration: 'configured'
}
}, null, 2)
}]
};
}
// 障害対応自動化
async function incidentResponse({ incident_type, severity, auto_recovery }) {
const response = {
incident_id: `INC-${Date.now()}`,
timestamp: new Date().toISOString(),
actions_taken: []
};
// 1. 自動調査実行
const investigationResults = await runAutomatedInvestigation(incident_type);
response.actions_taken.push('Automated investigation completed');
// 2. 重要度に応じた自動復旧
if (auto_recovery && ['critical', 'high'].includes(severity)) {
const recoveryResult = await attemptAutoRecovery(incident_type, investigationResults);
response.actions_taken.push(`Auto recovery: ${recoveryResult.status}`);
}
// 3. ステークホルダー通知
await notifyStakeholders(severity, response);
response.actions_taken.push('Stakeholders notified');
// 4. インシデントレポート生成
const report = await generateIncidentReport(response, investigationResults);
response.actions_taken.push('Incident report generated');
return {
content: [{
type: 'text',
text: JSON.stringify(response, null, 2)
}]
};
}
Part 4: パフォーマンス最適化とベストプラクティス¶
4.1 エージェント性能チューニング¶
{
"agent_performance_optimization": {
"model_selection_strategy": {
"data_analysis_tasks": "claude-3.5-sonnet",
"code_generation": "gpt-4o",
"creative_writing": "claude-3-opus",
"quick_responses": "claude-3-haiku"
},
"context_management": {
"max_context_window": 32000,
"context_pruning_strategy": "relevance_based",
"memory_optimization": true
},
"parallel_execution": {
"max_concurrent_agents": 3,
"task_distribution": "load_balanced",
"resource_monitoring": true
}
}
}
4.2 セキュリティ強化設定¶
# .claude/security/mcp-security.yaml
mcp_security_policy:
authentication:
required: true
methods:
- api_key
- oauth2
- mutual_tls
authorization:
rbac_enabled: true
permissions:
- read:repository
- write:issues
- admin:projects
data_protection:
encryption_at_rest: true
encryption_in_transit: true
pii_detection: true
sensitive_data_masking: true
audit_logging:
enabled: true
log_level: "info"
retention_days: 90
destinations:
- file: "/var/log/claude-code/audit.log"
- syslog: "rsyslog://log-server:514"
4.3 運用監視ダッシュボード¶
# monitoring/claude-code-metrics.py
import prometheus_client
from prometheus_client import Counter, Histogram, Gauge
import time
# メトリクス定義
agent_requests_total = Counter(
'claude_code_agent_requests_total',
'Total agent requests',
['agent_name', 'status']
)
agent_response_time = Histogram(
'claude_code_agent_response_seconds',
'Agent response time',
['agent_name']
)
active_agents = Gauge(
'claude_code_active_agents',
'Number of active agents'
)
mcp_connections = Gauge(
'claude_code_mcp_connections',
'Number of active MCP connections'
)
def monitor_agent_performance(agent_name, func):
"""エージェント性能監視デコレータ"""
def wrapper(*args, **kwargs):
start_time = time.time()
try:
result = func(*args, **kwargs)
agent_requests_total.labels(
agent_name=agent_name,
status='success'
).inc()
return result
except Exception as e:
agent_requests_total.labels(
agent_name=agent_name,
status='error'
).inc()
raise
finally:
response_time = time.time() - start_time
agent_response_time.labels(agent_name=agent_name).observe(response_time)
return wrapper
# Grafana ダッシュボード設定例
GRAFANA_DASHBOARD = {
"dashboard": {
"title": "Claude Code Agent Monitoring",
"panels": [
{
"title": "Agent Request Rate",
"type": "graph",
"targets": [
{
"expr": "rate(claude_code_agent_requests_total[5m])",
"legendFormat": "{{agent_name}} - {{status}}"
}
]
},
{
"title": "Agent Response Time",
"type": "graph",
"targets": [
{
"expr": "histogram_quantile(0.95, claude_code_agent_response_seconds)",
"legendFormat": "95th percentile"
}
]
}
]
}
}
まとめ¶
Claude Code のサブエージェント機能と MCP 統合により、従来の「単一AIアシスタント」から「専門特化エージェント群による分業体制」への移行が現実的になりました。
主要な実装ポイント¶
- 専門特化エージェント: 明確な責任分離と最適なモデル選択
- MCP統合: 外部ツールとのシームレスな連携自動化
- ワークフロー自動化: プロジェクト全体の開発フローを完全自動化
- 品質・セキュリティ: 自動監視とインシデント対応の仕組み化
導入効果と期待値¶
実装により期待される効果：
- 開発効率: 60-80%の作業時間短縮
- 品質向上: 自動テスト・監視による品質安定化
- 運用負荷軽減: インシデント対応の自動化
- 知識継承: エージェントによる組織知の蓄積
適切な設計と段階的導入により、AI エージェント駆動の開発体制を成功させることができます。