Claude Codeサブエージェント機能：実際に手を動かして学ぶ実践チュートリアル¶
はじめに¶
「サブエージェントの作り方は分かったけど、実際にいつ、どうやって使うの？」
この疑問を解決するため、本記事では実際のプロジェクトでサブエージェント機能を使った具体的なワークフローを、step by stepで実践していきます。
サブエージェントの動作原理¶
重要な理解：手動トリガー方式¶
サブエージェントは定期実行ではありません。以下の方式で動作します：
sequenceDiagram
participant User as 開発者
participant Main as メインClaude
participant Analysis as 分析エンジン
User->>Main: "この作業を3つの観点から構造化分析して"
Main->>Analysis: 1. セキュリティ観点での分析開始
Analysis-->>Main: セキュリティ分析結果
Main->>Analysis: 2. パフォーマンス観点での分析開始
Analysis-->>Main: パフォーマンス分析結果
Main->>Analysis: 3. コード品質観点での分析開始
Analysis-->>Main: 品質分析結果
Main->>Main: 結果統合・包括的レポート生成
Main->>User: 統合された改善提案実践チュートリアル1: プルリクエストレビュー¶
Step 1: 基本的な並列レビューを試す¶
実際に試せるコマンド:
# Claude Codeを起動した状態で、以下を実行
"このプルリクエストを3つの観点から並列でレビューして：
1. セキュリティの観点
2. パフォーマンスの観点
3. コード品質の観点"
期待される出力:
Task(Performing task: セキュリティレビュー中...)
Task(Performing task: パフォーマンス分析中...)
Task(Performing task: コード品質チェック中...)
Step 2: 動作確認方法¶
各タスクの実行中は以下が表示されます：
Task(Performing task: セキュリティ脆弱性をチェックしています...)
└── 現在 auth.js を分析中
└── XSS脆弱性の可能性を検出
└── CSRF対策の確認中
Task(Performing task: パフォーマンス分析を実行中...)
└── バンドルサイズを測定中
└── 不要な依存関係を特定中
└── 最適化の提案を準備中
Step 3: 結果の活用¶
各エージェントから以下のような具体的な結果が返ってきます：
## セキュリティ分析結果
- ❌ auth.js:42 - ユーザー入力の未サニタイズ
- ❌ api/login.js:28 - SQLインジェクション脆弱性
- ✅ HTTPS強制は適切に実装済み
## パフォーマンス分析結果
- ⚠️ bundle.js (2.3MB) - サイズが大きすぎる
- ⚠️ lodash全体をインポート - 必要な関数のみに変更推奨
- ✅ 画像最適化は適切
## コード品質分析結果
- ❌ 複雑度が高い関数が12個検出
- ❌ テストカバレッジ 45% (目標: 80%)
- ✅ ESLintルールは適切に適用済み
実践チュートリアル2: 新機能開発時の設計レビュー¶
実際のシナリオ¶
新しいユーザー認証機能を開発する際の実践例です。
Step 1: 設計段階での並列検討¶
"新しいOAuth認証機能の実装を検討しています。以下の観点から並列で分析してください：
1. セキュリティアーキテクチャの検証
2. データベース設計の妥当性確認
3. フロントエンド統合の複雑さ評価
4. テスト戦略の策定"
Step 2: 具体的な指示例¶
# より具体的に役割を指定する場合
"OAuth実装について、以下の専門エージェントで並列分析して：
エージェント1: セキュリティ専門家として
- OAuthフローの脆弱性チェック
- トークン管理のベストプラクティス確認
- PKCE実装の必要性評価
エージェント2: データベース専門家として
- ユーザーテーブル設計の妥当性
- セッション管理の最適化
- インデックス戦略の提案
エージェント3: フロントエンド専門家として
- React統合の複雑さ評価
- UX観点での改善提案
- エラーハンドリング戦略"
Step 3: 実行時の画面表示¶
🤖 3つのタスクを並列実行します...
Task(Performing task: OAuth セキュリティ分析中...)
├── PKCE フローの検証中
├── トークンライフサイクルの確認中
└── 脆弱性データベースとの照合中
Task(Performing task: データベース設計レビュー中...)
├── テーブル関係の整合性チェック中
├── パフォーマンス影響の評価中
└── スケーラビリティの検証中
Task(Performing task: フロントエンド統合分析中...)
├── React Router 統合の複雑さ評価中
├── 状態管理パターンの検討中
└── エラー画面設計の提案作成中
✅ 全タスク完了 - 統合レポートを生成中...
実践チュートリアル3: 大規模リファクタリング¶
実際に使える具体的指示¶
# レガシーコードの構造化分析
"このレガシーなJavaScriptコードベースを現代化したいです。
以下の作業を6つの観点から構造化分析してください：
1. TypeScript移行の優先度評価
2. テストコード不足箇所の特定
3. セキュリティ脆弱性の全数調査
4. パフォーマンスボトルネックの特定
5. 依存関係の最新化影響調査
6. アーキテクチャ改善提案の作成
各エージェントは独立して作業し、最終的に統合された移行計画を提示してください。"
実行中の詳細表示¶
🔄 大規模並列分析を開始...
Task(Performing task: TypeScript移行優先度評価...)
├── 📁 src/utils/ - 型エラー 23件検出
├── 📁 src/components/ - JSDoc から型定義変換可能
├── 📁 src/api/ - 外部API型定義が必要
└── 🎯 優先度: utils → components → api の順で実行推奨
Task(Performing task: テスト不足箇所特定中...)
├── 📊 現在のカバレッジ: 34% (目標: 80%)
├── 🚨 未テスト: 認証関連機能 (高リスク)
├── 🚨 未テスト: 決済処理 (高リスク)
└── 📝 優先テスト対象リストを作成中
Task(Performing task: セキュリティ監査実行中...)
├── 🔍 依存関係の既知脆弱性スキャン中
├── 🔍 ハードコードされた認証情報の検索中
├── 🔍 XSS/CSRF脆弱性の静的解析中
└── ⚠️ 高危険度の問題を3件発見
日常開発での実践的な使い方¶
1. 朝のコードレビュー¶
# 毎朝のルーティン
"昨日のコミットを3つの観点から並列レビューして：
- セキュリティチェック
- パフォーマンス影響評価
- コード品質とベストプラクティス準拠"
2. 機能実装前の事前検討¶
# 新機能開発前
"〇〇機能の実装を予定しています。以下を並列で検討してください：
- 技術的実装難易度の評価
- 既存システムへの影響分析
- 必要なテストケースの洗い出し
- セキュリティ考慮事項の整理"
3. バグ修正時の影響範囲確認¶
# バグ修正時
"このバグ修正が以下に与える影響を並列で調査してください：
- 他の機能への副作用
- パフォーマンスへの影響
- テストケースの更新要否
- ドキュメント更新の必要性"
よくあるトラブルとその解決方法¶
問題1: エージェントが期待通りに動かない¶
症状:
# 曖昧な指示の例（うまく動かない）
"コードをチェックして"
解決方法:
# 具体的で明確な指示（うまく動く）
"以下3つの観点から、src/auth.jsファイルを並列でチェックしてください：
1. セキュリティ脆弱性の検出
2. ESLintルール違反の確認
3. パフォーマンス改善点の特定"
問題2: 並列実行されているか分からない¶
確認方法: - Task(Performing task: ...) の表示を確認 - 複数のタスクが同時に表示されていれば並列実行中 - 各タスクの進行状況が個別に表示される
問題3: 結果が統合されない¶
症状:
# バラバラな結果が返ってくる
エージェント1: "セキュリティは問題なし"
エージェント2: "パフォーマンスに問題あり"
エージェント3: "コード品質は良好"
解決方法:
# 統合を明示的に指示
"結果を統合して、優先度付きのアクションプランを作成してください"
実際のプロジェクトでの導入方法¶
Phase 1: 小さく始める¶
# 最初は簡単なタスクから
"この関数を2つの観点からレビューして：
- バグの可能性
- 可読性の改善点"
Phase 2: 段階的に拡張¶
# 慣れてきたら範囲を拡大
"このモジュール全体を4つの観点から分析して：
- セキュリティ
- パフォーマンス
- 保守性
- テスタビリティ"
Phase 3: チーム全体での活用¶
# チーム標準として定着
"プルリクエスト〇〇番を標準レビュー項目で並列チェックして：
- コーディング規約準拠
- セキュリティベストプラクティス
- パフォーマンス影響
- テストカバレッジ十分性
- ドキュメント更新要否"
成功のコツ¶
1. 明確で具体的な指示¶
❌ 悪い例: "コードをチェックして" ✅ 良い例: "auth.jsを3つの観点（セキュリティ、パフォーマンス、品質）から並列分析して"
2. 適切な並列度の設定¶
- 2-3タスク: 日常的なレビュー
- 4-5タスク: 機能開発時の事前検討
- 6-8タスク: 大規模リファクタリング
- 9-10タスク: 緊急時の全面調査
3. 結果の活用方法¶
# 結果を受けて次のアクションを指示
"分析結果を受けて、最も重要な3つの改善点を実装してください。
優先度の高い順に、具体的な修正コードも提示してください。"
まとめ¶
Claude Codeサブエージェント機能は、その場その場の判断で複数の視点から並列分析するツールです。
- 定期実行ではなく手動トリガー
- 具体的で明確な指示が重要
- 日常の開発ワークフローに組み込み可能
- 段階的な導入がおすすめ
実際に手を動かして、あなたのプロジェクトで試してみてください！
次のステップ¶
- 今すぐ試す: 上記の具体例をそのまま実行
- カスタマイズ: 自分のプロジェクトに合わせて指示を調整
- チーム導入: 成功パターンをチームで共有
- 継続改善: 効果的な指示パターンを蓄積