Claude Codeを育てる - Part 5：Subagent実装編

Part 4（拡張編）で Skills と Subagents の使い分け（コンセプト）を扱った。 Subagent は概念は分かっても「どう実装するか」で詰まることが多い。今回はそこに踏み込む。

ただし答える前に、立場をはっきりさせておきたい。

■ 複数エージェントを「対等に」扱う構成には反対

最近、AI界隈ではこういう発信が流行っている。

• エージェント同士で会話させる
• 役割を分けて並列実行する
• 人間の組織みたいに動かす

別の記事（「AIエージェントを『組織化』するのはまだ早い」）でも書いたが、この構成には反対。

理由：

• コミュニケーションコストが急速に膨らむ（トークン = コスト）
• 合議は精度を落とす（LLMは多数派・自信のあるほうに引っ張られる）
• 判断の追跡が困難になる（ブラックボックス化、デバッグ地獄）

■ 一方、階層的な Subagent は「あり」

対等な合議は反対だが、メインエージェントが Subagent を呼び出す階層構造は別の話。

• メインエージェント（1）
• Subagent（複数、メインから呼ばれるだけ）
• 人間（最終判断）

この構造なら：

• Subagent 同士が会話しないので往復コストが膨らまない
• 採用するかは人間＋メインエージェントが決める（合議による精度低下が起きない）
• 命令系統が明確（追跡できる）

つまり「対等にしない」「会話させない」「最終判断は人間」という制約のもとで使う。 Part 4（拡張編）で書いた発想と同じ。

■ Subagent の使いどころ（おさらい）

向いているケース：

• メインのロールと違う立場で動かしたい（例：レビュアー）
• 大量のファイル読み込みでメインの context を汚したくない
• 並列で複数の調査をしたい
• メインに見せたくない試行錯誤をやらせたい

避けたいケース：

• 結果のすり合わせが多い（Skill で十分）
• メインの context が必要な判断
• 1ターンで終わる単純な処理

■ Step 1：ディレクトリを作る

project-root/
  .claude/
    agents/
      code-reviewer.md
      security-reviewer.md
      research-explorer.md

.claude/agents/ に1ファイル＝1つのSubagent。 ファイル名（拡張子除く）と frontmatter の name を揃えておくと管理が楽（厳密には必須ではないが、揃えないと「どのファイルがどの Subagent か」が分からなくなる）。

※ frontmatter とは、Markdown ファイルの冒頭に --- で囲んで書く YAML メタデータブロックのこと。Subagent の場合、ここに name / description / tools / model などの設定を書く。実物は次の Step 2 で出てくる。

■ Step 2：Subagent ファイルを書く

.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: コードレビューを責務分離・KISS/SOLID・セキュリティ・
  エラーハンドリング・テスト容易性の観点で実施する。
  メインエージェントが「レビューを依頼」する時に呼び出される。
  最終的な採用判断はメインエージェント＋人間が行う。
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Code Reviewer

あなたはコードレビュー専任のエージェントです。
メインエージェントから依頼されたコード/差分をレビューし、
指摘事項をリストで返してください。

## レビュー観点

- 責務分離（1ファイル/1関数の責任が肥大化していないか）
- KISS / SOLID（過剰抽象化・複雑な継承）
- セキュリティ（入力検証、認可、シークレット混入）
- エラーハンドリング（握り潰し、再raise、エラー型）
- テスト容易性（依存注入、副作用の局所化）

## 出力フォーマット

| ID | Severity (high/medium/low) | Category | Problem | Required Action | Verification |

## 制約

- 最終的な採用/不採用の判断はしない（メインに渡すだけ）
- ファイル編集はしない（読み込みと指摘のみ）
- 独自の判断で他のSubagentを呼ばない

ポイント：

• frontmatter の description を具体的に書く（Part 4 と同じ）
• tools でツールを絞る：レビュアーに Edit/Write は不要、Read/Grep だけで十分
• model を選ぶ：軽い調査は haiku、複雑なレビューは sonnet、設計提案は opus
• 本文（システムプロンプト）で「何をしないか」を明記する：上下関係を保つための文書化

■ Step 3：メインエージェントから呼び出す

メインエージェントは Agent ツール（旧 Task ツール、v2.1.63 でリネーム）経由で Subagent を呼ぶ。

自動呼び出し（description がトリガー）：

ユーザー: src/auth/login.ts をレビューして
メイン: code-reviewer Subagent を起動 → 指摘リストを取得 →
  ユーザーに提示 → 「採用しますか？」と確認

明示呼び出し：

ユーザー: code-reviewer に src/auth/login.ts を見せて

注意：呼び出すのはメインエージェントの判断で行う。 Subagent から別の Subagent を呼ばせない（階層を崩さない）。

■ Step 4：上下関係の制約を CLAUDE.md で明文化する

メインエージェント側の CLAUDE.md に書く：

# Subagent 利用ルール

- Subagent はメインエージェントから一方向に呼び出す
- Subagent 同士を直接会話させない
- Subagent の結果を採用するかはメインエージェント＋ユーザーが判断
- Subagent に最終判断や本番デプロイ等の重い操作をさせない

これは Part 3（説得編）の延長。 「対等にしない」を仕組みで明文化する。

書かないと、Claude が「組織化された複数エージェント」のパターンを学習しているので、勝手に Subagent 同士を協調させようとすることがある。

■ Step 5：動作確認（再現テスト）

1. Subagent ファイルを配置
2. 簡単なタスクをメインから依頼
3. 期待通り Subagent が呼ばれるか確認
4. 別セッションでも呼び出せるか確認（Part 6 で扱う再現テストと同じ考え方）

呼び出されない場合の典型的な原因：

• description が曖昧 → 「いつ発動するか」を書き足す
• name とファイル名が一致していない → 揃える
• tools 設定で必要なツールが落ちている → 追加

■ 最初に作ると効く Subagent

• code-reviewer — レビュアー視点を分離（最終判断はしない）
• security-reviewer — セキュリティ観点だけ厳しく評価
• research-explorer — 大量ファイル読み込みでメインの context を汚さない調査専任
• doc-writer — ドキュメントテンプレートに沿った文書生成

逆に作らないほうがいいもの：

• ❌ decision-maker — 最終判断する Subagent。人間とメインの役割を奪う
• ❌ planner + implementer + reviewer の3点セットを対等に並べる → 結局合議になる
• ❌ manager — 他の Subagent を統括する Subagent。階層が深くなり追跡不能

■ アンチパターン

実装で詰まる代表例：

• ❌ Subagent から別の Subagent を呼ばせる → 階層が崩れて追跡不能
• ❌ Subagent に書き込み権限（Edit/Write）を渡す → 影響範囲が読めない
• ❌ description を曖昧にする → 自動呼び出しされない or 誤呼び出し
• ❌ メインの context をまったく渡さずに丸投げする → 文脈を持たず的外れな結果
• ❌ Subagent の結果を無条件にメインが採用する → 合議に近づく。必ずメインが評価する
• ❌ 同じ役割の Subagent を複数並べて多数決させる → これは「対等な合議」と同じ失敗モード

■ 今回のまとめ

複数エージェントを対等に扱う構成には反対。 だが、階層的な Subagent はあり。

実装の鍵：

• .claude/agents/<name>.md に定義
• frontmatter で description tools model を絞る
• 本文（システムプロンプト）で「何をしないか」を明記
• メインから一方向に呼び出す。Subagent 間の会話は禁止
• 最終判断は人間＋メインエージェント

この制約のもとで Subagent を使うと、メインの context を汚さず、合議による精度低下も避けられる。

これがシリーズで一貫して言ってきた「上下関係を明確にする」の実装側。

次回 Part 6 はシリーズ最終回 — 運用編。仕組みを使い続けるための改善ループとアンチパターンを扱う。