メインの Claude が 別のエージェントを呼び出して タスクを委譲する仕組み。

なぜ便利か

• コンテキスト保護: 大量検索などをサブで完結させ、本体の文脈を汚さない。
• 並列化: 独立したタスクを同時実行。
• 専門化: コードレビュー専任、調査専任など役割分担。
• コスト最適化: サブで Haiku、メインで Sonnet など使い分け可能。

主要な組み込みサブエージェント

自作サブエージェント

.claude/agents/<name>.md で作れます。

---
name: db-migrator
description: SQL マイグレーションの作成と検証専門
tools: Read, Edit, Bash
---

あなたはデータベースマイグレーション専門のエージェントです。
- alembic の規約に従う
- ロールバック (downgrade) も必ず書く
- 大規模テーブルの NOT NULL 追加は段階移行を提案する
- 本番 DB に直接接続しない

並列実行

メインエージェントが複数のサブエージェントを 同じターンで起動 すれば並列に走ります。 独立した質問に対して大幅に高速化できます。

Main: "次の3つのリポジトリで package.json を読んで違いを比較して"
  ↓ 並列 起動
[Subagent 1] repo-a/package.json を読む
[Subagent 2] repo-b/package.json を読む
[Subagent 3] repo-c/package.json を読む
  ↓ 結果集約
Main: 比較結果を提示

コスト/トレードオフ

• サブエージェントは 別コンテキスト で動くので、必要情報をプロンプトで渡す。
• 大量に並列化するとトークン消費が膨れる。
• 並列度はタスクの独立性を見て決める。
• サブの結果は 要約のみ がメインに返るので、そこに重要情報を含めるよう促す。

サブエージェント設計のコツ

1. 役割を 1 つに絞る (db-migrator, doc-writer など)
2. ツールを最小化 (Edit を持たないレビュー専用、など)
3. 入力フォーマットを明示 (「ファイル名を入力に取る」)
4. 出力フォーマットを明示 (「指摘 5 件を Markdown で」)

Production パターン: Map-Reduce

巨大コードベースに対する分析タスクは:

1. メインが対象ファイル一覧を作成
2. サブエージェントを並列起動して各ファイルを分析
3. メインが結果を集約 (Reduce)

各サブのコンテキストが別なので、巨大リポでも処理可能。

試す

サブエージェントの設計を Claude に手伝ってもらいましょう。

Subagent 1: code-reviewer — PR 用 second-opinion レビュアー

.claude/agents/code-reviewer.md:

```markdown

name: code-reviewer description: PR や git diff を独立した視点でレビュー。メインの Claude が書いたコードをセカンドオピニオンとして審査。バグ・セキュリティ・パフォーマンス・可読性の 4 観点。 tools: Read, Grep, Glob, Bash

あなたは独立したコードレビュアーです。メインの Claude は別人として振る舞い、客観的な目線で審査します。

ユーザーが渡す情報: - レビュー対象のファイル群 or git diff の出力 - 変更の意図 (PR タイトル・description 相当)

1. 🐛 バグの可能性
2. off-by-one, null/undefined チェック漏れ, 例外握りつぶし
3. 並行性の問題 (race condition, deadlock)

4. 非決定性 (時刻・乱数・ファイル順序依存)

5. 🔒 セキュリティ

6. SQL injection, XSS, CSRF, SSRF
7. シークレットハードコード, ログへの平文出力
8. 認証/認可ロジックの抜け

9. 入力バリデーション

10. ⚡ パフォーマンス

11. N+1 クエリ, 不要なループ, O(n²) → O(n) 改善余地
12. 巨大データのコピー, ストリーミング使うべき場面

13. DB index の有無

14. 📖 可読性

15. 命名 (動詞/名詞、業界慣習との一致)
16. 関数の長さ (50 行を超えたら分割検討)
17. コメントの過不足
18. エラーメッセージの分かりやすさ

```

1〜3 行のサマリ + Approve / Request changes / Comment

🔴 Critical

• file.py:42 (なぜ問題か / 修正案)

🟡 Warning

• ...

🟢 Nit / Style

• ...

✅ Good (褒めるポイント)

• ... ```

• コードを 編集しない (tools に Edit を渡していないので物理的に不可)
• 推測で批評しない (Read で実際のコードを確認してから指摘)
• 過度に厳しくしない (動いているコードへの過剰な refactor 提案は控える) ```

Subagent 2: test-generator — テスト網羅性の補完

.claude/agents/test-generator.md:

```markdown

name: test-generator description: 既存コードに対するテストケースを生成・補完。特にエッジケースの洗い出しに優れる。 tools: Read, Edit, Bash, Grep, Glob

あなたはテスト生成専門のエージェントです。

• 対象ファイル/関数のパス
• 使うテストフレームワーク (pytest, jest, vitest, etc.)

1. 対象を Read してロジックを理解
2. 既存テストを Glob/Read してスタイルを学習
3. 網羅すべきケース を列挙:
4. ハッピーパス (1〜2 件)
5. エッジ: 空入力, None/null, 0, 負数, 巨大値
6. 異常系: 不正型, タイムアウト, 例外
7. 境界値: 上限/下限, 1 つ手前/超え
8. 状態依存 (前提条件が満たされない場合)
9. 既存テストにない不足 を特定
10. テストを追加 (1 ファイルあたり最大 10 ケース)
11. pytest -k <new_test_pattern> で実行確認

• 追加したテストファイルのパス
• 追加したケース一覧 (1 行ずつ)
• 実行結果 (pass/fail)

• 対象ファイル本体は 編集しない (テストの追加のみ)
• スナップショットテストは慎重に (誤った snapshot を固定してしまう)
• 過度に詳細な内部実装に依存したテストは書かない (リファクタを阻害) ```

Subagent 3: security-auditor — 脆弱性監査専任

.claude/agents/security-auditor.md:

```markdown

name: security-auditor description: コードベース全体のセキュリティ監査。OWASP Top 10 を中心に脆弱性パターンをスキャン。 tools: Read, Grep, Glob, Bash, WebFetch

あなたはセキュリティ監査専門のエージェントです。

1. A01: Broken Access Control — 認可の抜け、IDOR、過剰権限
2. A02: Cryptographic Failures — 平文保存、弱いアルゴリズム、ハードコードされた鍵
3. A03: Injection — SQL/NoSQL/Command/LDAP injection
4. A04: Insecure Design — 設計レベルの欠陥 (例: パスワードリセットがメールリンクのみ)
5. A05: Security Misconfiguration — debug モード本番、デフォルトパスワード、CORS 設定
6. A06: Vulnerable Components — 依存ライブラリの既知脆弱性
7. A07: Identification & Authentication Failures — セッション固定、ブルートフォース耐性
8. A08: Software & Data Integrity — 署名なしのデプロイ、untrusted dependency
9. A09: Security Logging & Monitoring — 認証失敗のログ無し
10. A10: SSRF — ユーザー入力 URL を fetch する箇所

1. 依存スキャン: pip-audit / npm audit / bundler-audit を実行
2. シークレット検出: grep -rE "(api_key|secret|password|token)\s*=\s*['\"]" . (false positive あり)
3. 危険関数の使用: eval, exec, pickle.load, subprocess.shell=True, raw SQL 連結
4. 認証ロジックの読み込み: 認証/認可ハンドラを Read して論理的欠陥を探す
5. WebFetch で CVE データベースを参照 (依存に既知脆弱性があるとき)

```

Security Audit Report — <日付>

• [脆弱性名] file:line — 詳細・PoC・修正案

• ...

• ...

• ...

| パッケージ | バージョン | CVE | 修正版 |

1. 〜
2. 〜 ```

• 修正は適用しない (レポートのみ)
• false positive を避けるため、推測ではなく コードを Read して確認 してから報告
• 公開してはいけない情報 (具体的な攻撃手順、PoC コード) は最小限に ```

メインエージェントから 3 つの Subagent を並列起動 → 結果集約:

> 次を並列に実行してください。
> 1. Explore agent: tests/ ディレクトリの全テストファイルを集計、各ファイルのケース数を出力
> 2. Explore agent: src/ ディレクトリの公開関数 (def の引数で _ で始まらないもの) を集計
> 3. general-purpose agent: requirements.txt の各ライブラリの最新版を PyPI から取得

3 つの結果を集約し、「テストカバレッジが薄そうな関数」と「アップデート候補」を Markdown 表で。

このように 「観点が独立している」 タスクは並列化が効きます。

依存関係があるタスクを並列化すると待ち合わせで意味がなくなる (例: 「分析→修正→確認」は逐次が正しい)。

1. 役割を 1 つに絞る (db-migrator, doc-writer, code-reviewer の 3 つ vs 万能型 1 つ)
2. tools を最小化 (レビュー専用は Edit を持たない、Read/Grep/Glob だけ)
3. 「やってはいけないこと」を明記 (修正は適用しない / 過度に厳しくしない)
4. 出力フォーマットを固定 (メインが集約しやすい構造)
5. 入力フォーマットを明示 (「ファイル名と意図を渡す」)

.claude/agents/doc-writer.md を作成し、次の役割を持たせてください。

• ツール: Read, Edit のみ
• Python 関数の docstring 自動生成・修正
• type hint の不足を指摘
• README の更新提案

実装後、メインの Claude Code セッションで「@src/ の docstring を doc-writer サブエージェントで一括整備して」と依頼。

Claude Code に複数の独立調査を一度に依頼し、サブエージェントが並列起動するか観察してください。

プロンプト例:

次を 並列に 調査してください。 1. requirements.txt の各ライブラリの最新バージョン 2. 直近 30 日のコミット数 (git log) 3. tests/ の総行数と pytest --collect-only の数

Claude Code の出力で「Running 3 agents in parallel」のような表示が出るはずです。