第7章 — サブエージェント: AI のチームビルディング

一人では足りない

ユウキのプロジェクトは成長していた。機能が増え、コードベースは1万行を超えた。

ある日、Claude Code に「この PR をレビューして」と頼んだ。返ってきたレビューは、コードスタイルの指摘ばかりだった。SQL インジェクションの脆弱性は見逃されていた。

「一人の AI に全部やらせるのが間違いなんだ」

ミサキは言った。「人間のチームだって、フロントエンドの専門家にセキュリティレビューは頼まないでしょ？ AI も同じ。専門家チームを作るの」

サブエージェントとは

サブエージェントは、メインの Claude Code セッションから独立したコンテキストで動く専門エージェントだ。

Loading diagram...

なぜ分けるのか

INFO

サブエージェントを使う3つの理由:

専門性: 特化した指示で品質が上がる
コンテキスト保護: メインの文脈が探索結果で埋まらない
並列性: 独立した作業を同時に進められる

組み込みエージェント

Claude Code には、最初から使えるエージェントタイプがいくつかある。

Explore エージェント

コードベースの探索に特化。ファイルを読み、grep し、構造を把握する。書き込み権限がない（安全）。

用途: 「このシンボルはどこで定義されている？」「関連ファイルを探して」
呼び方: Agent ツールで subagent_type="Explore" を指定

Plan エージェント

実装計画を立てる。ファイルを読んで分析するが、編集はしない。

用途: 「この機能の実装方針を設計して」「影響範囲を分析して」
呼び方: Agent ツールで subagent_type="Plan" を指定

security-auditor

セキュリティ観点でコードを監査する。

用途: 「この変更にセキュリティリスクはないか」
呼び方: Agent ツールで subagent_type="security-auditor" を指定

カスタムエージェントの設計

組み込みエージェントだけでは足りない場面がある。プロジェクト固有の専門家が必要な場合、カスタムエージェントを定義できる。

エージェント定義ファイル

.claude/agents/ に Markdown ファイルを置く。

<!-- .claude/agents/api-reviewer.md -->
---
name: api-reviewer
description: REST API の設計とセキュリティをレビューする専門エージェント
model: sonnet
tools:
  - Read
  - Grep
  - Glob
---
 
あなたは REST API 設計のエキスパートです。以下の観点でレビューします:
 
## レビュー観点
 
1. **認証・認可**: すべてのエンドポイントで適切な認証チェック
2. **入力バリデーション**: リクエストパラメータの型・範囲・形式
3. **エラーハンドリング**: 適切なHTTPステータスコード、内部情報の非露出
4. **レート制限**: DoS 対策の有無
5. **CORS**: 適切なオリジン設定
 
## 出力形式
 
各問題を以下の形式で報告:
- **[severity]** ファイル:行 — 問題の説明 → 修正提案

設計の4原則

Loading diagram...

1. 単一責務

<!-- ❌ 責務が広すぎる -->
name: full-stack-reviewer
description: フロント、バック、DB、インフラをすべてレビュー
 
<!-- ✅ 責務が明確 -->
name: api-reviewer
description: REST API の設計とセキュリティをレビュー

2. 最小権限

<!-- ❌ 不要なツールを持たせる -->
tools:
  - Read
  - Write   # レビューなのに書き込み権限？
  - Edit     # レビューなのに編集権限？
  - Bash     # レビューなのにコマンド実行権限？
 
<!-- ✅ 必要最小限 -->
tools:
  - Read
  - Grep
  - Glob

3. 明確なトリガー

description フィールドは、Claude Code がこのエージェントを「いつ使うか」を判断するための情報だ。

<!-- ❌ 曖昧 -->
description: コードをチェックする
 
<!-- ✅ 明確 -->
description: REST API の設計とセキュリティをレビューする専門エージェント。
  API ルートの変更、新規エンドポイント追加時に使用

4. 構造化された出力

## 出力形式
問題を severity 順にソートし、以下の形式で報告:
 
### Critical
- ファイル:行 — 説明
 
### Warning
- ファイル:行 — 説明
 
### Info
- ファイル:行 — 説明
 
### Summary
- Critical: N件, Warning: N件, Info: N件