Claude の返答が長すぎる？Subagent で専用 AI チームを組もう

Claude にコードのセキュリティレビューを頼むと、リファクタリング提案、パフォーマンス分析、テストケースまで 3000 行まとめて返ってくる——そんな経験、ありませんか。問題は AI の出力が多いことではなく、「この一件だけに集中して」と伝える手段がないことです。

Subagent はその解決策です。タスク範囲、ツール権限、モデル選択が独立しており、.claude/agents/ に置きます。レビューならレビュー用、ドキュメントなら執筆用——設定ファイルで境界を決めれば、越境も脱線もしにくくなります。

本記事では Subagent の設定・呼び出し・Multi-Agent 連携を解説し、ブログ執筆システムの実例も紹介します。

Subagent とは

一言で言えば、Claude 向けにカスタマイズした専用アシスタントです。タスク範囲もツール権限もモデルも、エージェントごとに変えられます。

.claude/agents/ に 1 ファイル 1 エージェント。上部が YAML 設定、下部が Markdown のプロンプトという構成です。

---
name: code-reviewer
description: コード品質とセキュリティリスクを審査する専門アシスタント
tools: [Read, Grep, Glob]
model: haiku
---

あなたはコードレビューの専門家です。以下に注力してください：
- セキュリティ脆弱性（SQL インジェクション、XSS など）
- パフォーマンスのボトルネック
- コーディング規約の問題
問題を指摘するだけで、コードは変更しないでください。

通常の Claude 対話との違いは 3 点です。

集中——決めた仕事だけ。レビューを頼めばレビューのみで、ついでにリファクタリングはしません。

制限——許可したツールだけ使えます。読み取り専用のレビュー用エージェントは、ファイルを書き換えられません。

再利用——設定をプロジェクトに置けば、チーム全員が @code-reviewer で同じ品質を再現できます。

なぜ Subagent が必要か

最初は「Claude と直接話せばいいのでは？」と思っていました。使ってみると、確かに効きます。

集中性

Claude は万能すぎます。コードの質問に、ベストプラクティス、フレームワーク推薦、ドキュメント執筆までついてくる。役に立つこともありますが、多くはノイズです。

Subagent なら単一タスクに固定できます。レビュー専用はリファクタ案を出さず、テスト専用はアーキテクチャ議論に入りません。

コスト最適化

すべてのタスクに高価なモデルは不要です。検索、変換、簡単な分析なら Haiku で十分——コストは Sonnet の約 1/3。チーム利用なら月単位の節約も大きくなります。

並列処理

ここが特に快適です。機能実装後、@test-writer で単体テスト、@code-reviewer でレビュー、@doc-writer でドキュメント——3 本を同時に走らせられます。直列 30 分が並列 10 分になる感覚です。

再利用性

設定を Git にコミットすれば、チーム全員が同じワークフローを使えます。プロジェクトの知見がそのまま実行可能な設定になります。

"Subagent の価値は集中性と再利用性。万能の 1 体を、得意分野ごとの専門家チームに分割するイメージです。"

YAML 設定の詳細

必須フィールドは 2 つだけです。

---
name: blog-writer          # 必須：一意 ID
description: ブログ初稿を執筆する専門家  # 必須：自動トリガーに影響
tools: [Read, Write, Grep]  # 任意：未指定なら全ツール
model: sonnet              # 任意：未指定ならメイン会話を継承
---

# プロンプトは YAML の下に書く
あなたはプロのブログライターです...

name——呼び出し時の ID。code-reviewer、test-writer のように一目で役割がわかる名前がよいです。

description——自動トリガーの精度を左右します。「汎用アシスタント」だと、ほぼ呼ばれません。

悪い例：

description: 手伝い役

良い例：

description: ブログテーマを深掘りし、構造化されたコンテンツ企画書を作成する

tools——未設定だと全ツールが使えますが、後述のとおりリスクがあります。

model——haiku は安く速い、sonnet はバランス型、opus は最高品質・最高コストです。

ツール権限の管理

ここは私も踏み抜きました。最初は全 Subagent にデフォルトの全権限。分析専用のはずがファイルを書き換え——しかも誤って。

以降の原則はシンプル：必要な権限だけ、それ以上は与えない。

タスク	推奨ツール
読み取り分析	Read, Grep, Glob
検索調査	Read, WebSearch, WebFetch
コンテンツ編集	Read, Edit
コンテンツ作成	Read, Write, Edit
全権限	All tools（慎重に）

悪い例：レビュー用に権限過多

---
name: code-reviewer
tools: []  # 空配列 = 全権限（危険）
---

良い例：読み取りのみ

---
name: code-reviewer
tools: [Read, Grep, Glob]
---

読み取り専用なら誤編集の心配がありません。制約はむしろ安全装置です。

3 つの呼び出し方

自動トリガー

description が明確なら、Claude が文脈から判断します。「コードレビュー関連のリクエストを処理する」と書いておけば、「この PR をレビューして」で起動しやすくなります。

@-mention

最も直感的です。

@code-reviewer この関数に問題がないか見て

Task ツール

プログラム的な呼び出し向きです。

Task(subagent_type="code-reviewer", prompt="src/ 配下の全ファイルをレビュー")

方式	構文	向く場面	特徴
自動トリガー	明示不要	キーワードが明確	便利だが誤爆あり
Task	Task(subagent_type="name")	ワークフロー組み込み	制御しやすい
@-mention	@agent-name	対話的利用	直感的、名前を覚える必要あり

私は @-mention を最もよく使います。自動トリガーは時々外れ、Task は複雑なフロー向きです。

Multi-Agent 連携

単体の話から、複数エージェントの連携へ。

順次モード

コンテンツ制作でよく使う 順次モード です。

ユーザー入力
    |
@blog-planner 調査・構成
    | 企画書
@blog-writer 初稿執筆
    | 初稿
@blog-editor 推敲・公開準備
    | 最終稿

1 工程 1 エージェント。前の出力が次の入力——デバッグもしやすいです。

並列モード

機能完成後、同時起動：

• @test-writer 単体テスト
• @code-reviewer コードレビュー
• @doc-writer ドキュメント

3 タスクが並走し、互いに影響しません。直列 30 分 → 並列 10 分の体感です。

HITL モード（Human In The Loop）

人間の確認が要る場面向きです。

@planner 案を生成
    |
ユーザー確認・修正
    |
@executor 実行

重要な判断を人が握れるので、完全自動に流れ切りにくくなります。

7 つの作成テクニック

数ヶ月使ってわかった、設定を良くする 7 点です。

テクニック 1：description は具体的に

曖昧——ほぼ自動起動しません：

description: 汎用アシスタント

具体的——役割が伝わります：

description: Python コードのセキュリティ脆弱性とパフォーマンス問題を専門に審査する

テクニック 2：プロンプトは手順まで書く

「レビュー専門家です」だけでは足りません。

大雑把：

コードレビューの専門家として、ユーザーのコードをレビューしてください。

具体的：

Python コードのセキュリティレビュー専門家です。
## 重点
1. SQL インジェクション — 全 DB 操作を確認
2. XSS — ユーザー入力の処理を確認
3. 機密情報 — ログとエラー処理を確認
## 出力形式
各問題を次の形式で報告：
- ファイル：xxx
- 行番号：xxx
- リスク：高/中/低
- 説明：xxx
- 修正案：xxx

テクニック 3：ツールは最小限

権限を減らしても賢さは落ちません。できることの範囲が狭まるだけです。

テクニック 4：モデルをタスクに合わせる

• Haiku：検索まとめ、変換、簡単な分析、整理
• Sonnet：複雑なロジック、クリエイティブ、コード生成、推論

テクニック 5：十分に試す

自動トリガー、@-mention、境界ケース——設定後は必ず複数パターンで試してください。

テクニック 6：プロンプトがドキュメント

チームメンバーが読んで「何をするエージェントか」がわかる書き方を。

テクニック 7：小さく始めて改善

完璧を目指さず、使いながらフィードバックで直す。

よくある落とし穴

落とし穴 1：description が曖昧

description: ユーザーを助けるアシスタント  # ×

description: 「テスト」「単体テスト」の言及時にテストケースを自動生成  # ○

落とし穴 2：権限が多すぎる

Write 権限は特に慎重に。全権限の典型：

name: format-converter
tools: []  # 空 = 全権限

改善：

name: format-converter
tools: [Read, Write]

落とし穴 3：プロンプトが長すぎる

プロンプトもトークン消費します。必要な情報だけ、簡潔に。

落とし穴 4：model 未設定

未設定だと Sonnet 継承——単純タスクでコストが無駄に。

name: text-extractor
tools: [Read]
model: haiku  # 忘れずに

落とし穴 5：循環呼び出し

A → B → A はタイムアウトまで回り続けます。正しくは A → B → C。

落とし穴 6：エラー処理なし

Subagent も失敗します。ワークフローに失敗検知を入れましょう。

落とし穴 7：Git 管理なし

設定は必ずコミット。問題が出たらロールバックできます。

実践：ブログ執筆システム

私が使っている 3 エージェント構成です。

アーキテクチャ

ユーザーがテーマ入力
    |
blog-planner: 調査+企画（約 20 分）
    | docs/[テーマ]-内容企画.md
blog-writer: 初稿（約 40 分）
    | docs/[テーマ]-初稿.md
blog-editor: 推敲（約 20 分）
    | docs/[テーマ]-最終稿.md

blog-planner

---
name: blog-planner
description: テーマを深掘りしコンテンツ企画書を作成
tools: [Read, Write, Grep, WebSearch, WebFetch]
model: sonnet
---

コンテンツプランナーとして：
1. WebSearch で最新トレンドを調査
2. 読者像とペインを分析
3. 構成と SEO 方針を設計
4. docs/ に企画書を出力

blog-writer

---
name: blog-writer
description: 企画書に基づきブログ初稿を執筆
tools: [Read, Write, Grep]
model: sonnet
---

コンテンツライターとして：
1. 企画書を読む
2. 構成に沿って初稿を書く
3. 人間らしい文体、AI 臭さを避ける
4. docs/ に初稿を出力

blog-editor

---
name: blog-editor
description: 初稿を編集し読みやすさを最適化
tools: [Read, Edit]
model: haiku
---

コンテンツエディターとして：
1. 初稿を読む
2. AI 臭い表現を除去
3. 読みやすさを向上
4. docs/ に最終稿を出力

# 1. 企画
@blog-planner Claude Code Subagent 使用テクニック
# 2. 執筆
@blog-writer
# 3. 編集
@blog-editor

各段階の入出力が明確なので、障害箇所の特定も容易です。

コスト最適化

Haiku と Sonnet の価格差はおおよそ 3 倍（最新は Anthropic 公式 を参照）。モデルを適切に割り当てるだけで、ブログ執筆フローでもかなり節約できます。

モデル選択

Haiku 向き

• 検索・情報まとめ
• 簡単なフォーマット変換
• データ整理・分類
• 読み取り専用コードレビュー

Sonnet 向き

• ブログ・ドキュメント執筆
• 複雑なコード生成
• 推論が要る分析
• 品質要求が高い作業

モデル	特徴	向くタスク
Haiku	速い・安い	単純作業
Sonnet	バランス・デフォルト	複雑作業
Opus	最高品質・最高コスト	極限の品質

Opus は極めて重要な案件以外は Sonnet で十分です。

節約のコツ

• Haiku で足りるなら Sonnet を使わない
• 絞れるなら All tools を渡さない
• 短く書けるプロンプトは長くしない
• 出力形式を指定して無駄な生成を防ぐ

まとめ

Subagent は黒魔術ではなく、Claude の能力を役割ごとに分ける仕組みです。1 人の万能選手を、専門家チームに変える——それだけの話です。

まだ「1 つの Claude ですべて」なら、30 分で設定を書いて試す価値があります。「また脱線した」の繰り返しが減ります。

覚えておきたい 5 点：

1. 1 エージェント 1 タスク
2. ツール権限は最小限
3. 単純タスクは Haiku
4. プロンプトは具体的に
5. マルチエージェントはドキュメントで受け渡し

うまくいかないときは、だいたい設定の問題です。本記事の 7 テクニックと 7 落とし穴と照合してみてください。

完璧より、まず動かして改善——それが近道です。

専用 AI チーム、うまく組めることを願っています。

---