Claudeの返答が長すぎる？Subagentであなた専用のAIチームを作ろう

深夜2時、私は画面を見つめながら、Claude がまたしても3000行もの返答を返してきたのを見ていました。コードにセキュリティ上の問題がないかチェックしてほしかっただけなのに、リファクタリングの提案、パフォーマンス最適化、テストケースまで全部書いてきたのです。
正直、「コードレビューだけに集中して、余計なことはしないでくれ」と思いました。
その後、Subagent こそがこの問題を解決するための機能だと気づきました。

1/3

Haiku コスト

Sonnet と比較して

3 種

呼び出し方法

自動トリガー、@-mention、Task

並列

マルチタスク実行

効率倍増

数据来源: 実際の使用データ

そもそも Subagent とは？

簡単に言えば、Subagent はあなたが Claude にカスタマイズした専用アシスタントです。各アシスタントは独自のタスク範囲、ツール権限を持ち、使用するモデルさえ変えることができます。
これらはプロジェクトの .claude/agents/ ディレクトリに存在し、各ファイルが1つのアシスタントに対応します。ファイル構造はシンプルで、上部は YAML 設定、下部は Markdown で書かれた詳細なプロンプトです。

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

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

通常の Claude との対話と比較して、Subagent には3つの明確な違いがあります：

専門性——規定された仕事だけを行い、脱線しません。コードレビューを頼めばレビューだけを行い、ついでにリファクタリングしたりしません。
制限——ツール権限はあなたが与えたものに限られ、許可していないツールは使えません。読み取り専用のレビューアシスタントは、ファイルを勝手に書き換えることができません。
再利用性——設定ファイルはプロジェクト内に置かれ、チームメンバー全員が使用できます。新人が入っても、@code-reviewer ですぐに作業を開始できます。

なぜ Subagent が必要なのか？

正直なところ、最初は過剰だと思いました。「直接 Claude と話せば済む話ではないか？」と。
しかし、しばらく使ってみると、確かに便利だと気づきました。

専門性

Claude 自体が多才すぎるため、コードについて質問すると、ついでにベストプラクティスを語ったり、フレームワークを推奨したり、ドキュメントを書いてくれたりします。これらは時には役立ちますが、多くの場合はノイズです。
Subagent は単一のタスクに集中させることができます。コードレビュー専門のアシスタントはリファクタリング案を出しませんし、テスト作成専門のアシスタントはアーキテクチャ設計に口を出しません。

コスト最適化

これは多くの人が気づいていないかもしれませんが、すべてのタスクに最も高価なモデルを使う必要はありません。
検索、フォーマット変換、簡単な分析なら Haiku で十分で、コストはおよそ Sonnet の 1/3 です。チームで使えば、1ヶ月でかなりの節約になります。

並列処理

これこそ私が最高だと思う点です。
複数のタスクを同時に開始し、並列で実行できます。例えば機能を書き終えた後、同時に1つのアシスタントに単体テストを実行させ、1つにコードレビューさせ、1つにドキュメントを書かせることができます。実際に体験すると、効率の向上は明らかです。

再利用性

作成した設定ファイルは Git リポジトリにコミットされ、チームメンバー全員が利用できます。プロジェクトで蓄積された経験が、実行可能な設定に変わります。

"Subagent の核心的な価値は専門性と再利用性です。一人の万能選手を専門家チームに変え、各専門家が得意分野だけを担当するようにします。"
— Claude Code ベストプラクティス

YAML 設定の詳細

では、具体的に設定ファイルをどう書くのでしょうか？
完全な Subagent 設定にはいくつかのフィールドがありますが、必須なのは2つだけです：

---
name: blog-writer          # 必須：アシスタントの一意の識別子
description: ブログの初稿を作成する専門家  # 必須：短い説明、自動トリガーに影響
tools: [Read, Write, Grep]  # オプション：ツール権限、デフォルトはすべて
model: sonnet              # オプション：モデル選択、デフォルトはメイン対話を継承
---

# プロンプトはYAMLの下に書く
あなたはプロフェッショナルなブログライターです...

name——アシスタントの ID で、呼び出す際に識別するために使用します。code-reviewer、test-writer のように、一目でわかる名前が良いでしょう。
description——これが非常に重要です。Claude はこの説明に基づいて、いつこのアシスタントを自動的にトリガーするかを判断します。「様々なタスクを処理する汎用アシスタント」と書くと、基本的には自動トリガーされなくなります。

悪い書き方：

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つの呼び出し方法

設定ができたら、どう呼び出しますか？ 3つの方法があります：

自動トリガー

description を十分に明確に書いていれば、Claude はいつ呼び出すべきか自動的に判断します。例えば「コードレビューに関するすべてのリクエストを処理する」と書いてあれば、「この PR をレビューして」と言うだけで自動的にトリガーされます。

@-mention

最も直接的な方法で、@agent-name と入力するだけです：

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

Task ツール

プログラム的な呼び出しで、より複雑なシナリオに適しています：

Task(subagent_type="code-reviewer", prompt="src/ディレクトリ配下の全ファイルを審査")

方法	構文	適用シーン	特徴
自動トリガー	明示的な呼び出し不要	明確なキーワード	便利だが誤爆の可能性あり
Task ツール	`Task(subagent_type="name")`	プログラム的呼び出し	正確な制御
@-mention	`@agent-name`	対話的使用	直感的だが名前を覚える必要あり

私は個人的に @-mention を最もよく使います。シンプルで直接的だからです。自動トリガーは時々誤判断することがありますし、Task ツールは複雑なワークフローでしか使いません。

Multi-Agent 協調

ここまで話したのは単一のアシスタントの使い方です。Subagent の真の力は、複数のアシスタントが協力することにあります。

順次モード

私が最もよく使うのは 順次モード で、特にコンテンツ制作系のワークフローに適しています：

ユーザーがテーマを入力
    |
@blog-planner 調査・構成案作成
    | 計画ドキュメントを出力
@blog-writer 構成案を読み取り・初稿作成
    | 初稿を出力
@blog-editor 初稿を読み取り・推敲して公開
    | 最終稿を出力

各アシスタントは1つの工程だけを担当し、前の出力が次の入力になります。明確で制御しやすく、デバッグも容易です。

並列モード

並列モードはさらに爽快です。機能を書き終えた後、同時に開始します：

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

3つのタスクが並列で走り、互いに干渉しません。以前は直列で30分かかっていたことが、10分で終わります。

HITL モード（Human In The Loop）

もう一つのモードは、人工的な確認が必要なシーンに適しています：

@planner 案を生成
    |
ユーザーが確認または修正
    |
@executor 案を実行

このモードの利点は、重要な決定ポイントを人がコントロールできるため、完全に制御不能になることがない点です。

7つの作成テクニック

数ヶ月 Subagent を使ってきて、設定をより使いやすくする7つのテクニックをまとめました：

テクニック1：description は正確に

description は自動トリガーの正確性に直接影響します。

曖昧すぎる——ほとんど自動トリガーされません：

description: 汎用的なアシスタント

正確な記述——責任範囲を明確にする：

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

テクニック2：プロンプトは具体的に

「あなたはコードレビューの専門家です」と言うだけでなく、具体的にどうレビューするかを伝えます。

大雑把：

あなたはコードレビューの専門家で、ユーザーのコードレビューを手伝います。

具体的な指示：

あなたは Python コードセキュリティレビューの専門家です。
## レビュー重点
1. SQL インジェクションリスク - すべてのデータベース操作をチェック
2. XSS 脆弱性 - ユーザー入力の処理をチェック
3. 機密情報の漏洩 - ログとエラー処理をチェック
## 出力フォーマット
各問題は以下の形式で報告すること：
- ファイル：xxx
- 行番号：xxx
- リスクレベル：高/中/低
- 問題の記述：xxx
- 修正提案：xxx

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

前述の通り、必要な権限だけを与えます。権限を減らすことはアシスタントを馬鹿にすることではなく、できることを制限するだけです。

テクニック4：モデルを適切に選ぶ

簡単なタスクには Haiku、複雑なタスクには Sonnet を使います。具体的には：

Haiku 向き：検索まとめ、フォーマット変換、簡単な分析、データ整理
Sonnet 向き：複雑なロジック、クリエイティブコンテンツ、コード生成、推論分析

テクニック5：テストを十分に行う

設定を書いた後、いくつかの呼び出し方法を試してください。自動トリガーは使いやすいか？ @-mention は正常か？境界ケースはどう処理されるか？

テクニック6：ドキュメントを明確に

プロンプト自体がドキュメントです。明確に書いてあれば、チームメンバーは一目でこのアシスタントが何をするもので、どう使うかがわかります。

テクニック7：頻繁に改善する

一度で完璧に書こうと思わないでください。まずは使えるバージョンを書き、実際にしばらく使って、フィードバックに基づいて徐々に調整してください。

よくある間違い回避ガイド

テクニックを話したところで、私が踏んだ落とし穴についてもお話しします：

穴1：description が曖昧すぎる

「汎用アシスタント」のような説明を書くと、Claude はいつ呼び出すべきかわかりません。具体的に何を担当するか書いてください。

悪い例：

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

改善例：

description: ユーザーが「テスト」、「単体テスト」に言及した際、自動的にテストケースを生成する

穴2：ツール権限が多すぎる

手っ取り早く全権限を与えた結果、アシスタントが望まないことをしてしまいます。特に Write 権限は、与える前によく考えてください。

悪い例：

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

改善例：

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

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

Subagent のプロンプトもトークンとして計算されます。数千文字のプロンプトを書くと、呼び出しのたびにそれらのトークンを消費します。簡潔に保ち、必要な情報だけを書いてください。

穴4：model 設定忘れ

model を設定しないと、デフォルトでメイン対話のモデル（通常は Sonnet）を継承します。簡単なタスクでお金を無駄にします。

忘れがち：

name: text-extractor
tools: [Read]

忘れずに設定：

name: text-extractor
tools: [Read]
model: haiku

穴5：循環呼び出し

Agent A が Agent B を呼び、Agent B がまた Agent A を呼ぶ。この無限ループは、タイムアウトするか強制停止するまで走り続けます。
正解：A -> B -> C
間違い：A -> B -> A

穴6：エラー処理がない

Subagent も失敗します。ワークフローにエラー処理ロジックを加え、失敗したらすぐに発見できるようにしてください。

穴7：設定のバージョン管理なし

設定ファイルは Git にコミットしてください。設定を変えて問題が起きた時、前のバージョンに戻せます。

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

理論をたくさん話しましたが、実際の例を見てみましょう。
私が個人的に使っているブログ執筆システムは、3つの Subagent で構成されています：

システムアーキテクチャ

ユーザーがテーマを提供
    |
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つの Claude で天下を取る」やり方をしているなら、Subagent を試すことを本当にお勧めします。30分かけていくつか設定を書くだけで、無数の「Claude がまた脱線した」という瞬間を節約できます。

核心となる原則は以下の通りです：

1つの agent は1つのことだけをする
必要なツール権限だけを与える
簡単なタスクには Haiku を使う
プロンプトは具体的かつ明確にする
複数 agent の連携はドキュメントで受け渡す

問題にぶつかっても慌てないでください。大抵は設定の書き間違いです。この記事の7つのテクニックと7つの間違いと照らし合わせれば、基本的には解決できます。

最後に一言：完璧な設定を求めすぎず、まずは使ってみて、徐々に改善していってください。

あなた専用の AI チームが早く結成できることを祈っています！

FAQ

Subagent と通常の Claude 対話の違いは何ですか？

Subagent には3つの明確な違いがあります：

1) 専門性：
• 規定された仕事だけを行い、脱線しない

2) 制限性：
• ツール権限をあなたが制御する

3) 再利用性：
• 設定ファイルはチームで共有可能
• プロジェクトの .claude/agents/ ディレクトリに配置

Subagent を呼び出すには？

3つの呼び出し方法があります：

1) 自動トリガー：
• Claude が description に基づいて自動判断

2) @-mention：
• @agent-name で直接呼び出し

3) Task ツール：
• プログラム的呼び出し Task(subagent_type='name')

Haiku と Sonnet モデルの違いは何ですか？

Haiku：
• 高速かつ安価、コストは Sonnet の約 1/3
• 検索まとめ、フォーマット変換、簡単な分析などのタスクに適している

Sonnet：
• 品質の高さ
• 複雑なロジック、クリエイティブコンテンツ、コード生成など深い推論が必要なタスクに適している

ツール権限はどう設定すべきですか？

原則として必要な権限のみを与えます。

一般的な組み合わせ：
• 読み取り専用分析は [Read, Grep, Glob]
• 検索・調査は [Read, WebSearch, WebFetch]
• コンテンツ編集は [Read, Edit]
• コンテンツ作成は [Read, Write, Edit]

誤操作を防ぐため、全権限を与えるのは避けます。

複数の Subagent を連携させるには？

主に3つのモードがあります：

1) 順次モード：
• パイプライン式処理
• 前の出力が次の入力になる

2) 並列モード：
• 複数のタスクを同時実行
• 互いに干渉しない

3) HITL モード：
• 重要な決定ポイントで人工確認を行う

実際の使用ではシーンに応じて柔軟に組み合わせます。

6 min read · 公開日: 2025年11月22日 · 更新日: 2026年1月22日

Easton

AI・インテリジェンス