Claude Codeを使い始めて様々な発信をしてきましたが、Claude Codeに関する投稿は約2ヶ月ぶりです。この期間、他のアウトプットや諸々の事情で投稿が遅れてしまいましたが、今回は「Subagents」について書きます。
このブログが良ければ読者になったり、nwiizoのXやGithubをフォローしてくれると嬉しいです。
はじめに
ここで読むのをやめる人のために言っておくと、Subagentsは「Claude Codeに尖った意思を持たせる」機能です。タスクごとに最適化されたAIを使い分けられます。
特定のタスクを実行するslash commandsとの違いは、slash commands（/コマンド）があなたが明示的に呼び出すショートカットであるのに対し、SubagentsはClaude Codeが文脈を読んで自動的に専門家を呼び出す点にあります。例えば、slash commandsでは「/test」と打てばテスト実行されますが、Subagentsでは「エラーが出た」と伝えるだけで勝手にdebugger subagentが起動します（起動できないようにもできます）。 つまり、commandsは「リモコンのボタンを押す」、Subagentsは「AIが勝手に判断して動く」みたいなもの。commandsは確実だけど面倒、Subagentsは楽だけど時々勝手なことをする。両方設定すれば、必要な時は手動で制御しつつ、面倒な部分は自動化できて最強です（AIに仕事を奪われる第一歩かもしれませんが）。
Claude Codeって万能だけど、それゆえに器用貧乏になることがある。「データ分析して」って言ったら、なぜかフロントエンドのコンポーネントまで作り始めたり、最新技術よりも古い安全な実装を選んだり。例えば「最新版で」と指定しても、内部知識にある古いバージョンの設定方法で進めようとしたり、今では不要になった設定ファイルを作ろうとしたりする。「それ最新の仕様で」と言っても憶測でそれっぽくセットアップするだけで、実際の公式ドキュメントを調べずに進めてしまう。毎回「それ古いから最新の方法で」と指摘するのも疲れるし、革新的なアーキテクチャより無難で時代遅れの実装を選んでしまうこともある。タスクの境界線をあまり意識せず、頼まれていないことまでやってしまったり、逆に専門的な判断が必要な場面で踏み込みが足りなかったり。人間の開発チームだって、フルスタックエンジニア1人より専門家チームの方が効率的で、より尖った意思決定ができるでしょ？
Subagentsとは何か
Claude Code Subagentsは、特定のタスクに特化したAIアシスタントです。
各Subagentの特徴：
- 独立したコンテキストウィンドウを持つ（メインの会話を汚染しない）
- カスタムシステムプロンプトで専門性を定義
- 特定のツールだけ使える権限管理（最小権限の原則）
- 自動的に呼び出されるか、明示的に指定可能
実はClaude CodeはデフォルトでTaskツールを使った調査時には、自動的にサブエージェントを起動するアーキテクチャになっています。
なぜSubagentsを設定したほうがいいのか
1. コンテキストウィンドウの効率的な管理
LLMのコンテキストウィンドウは有限です。長時間使っていると、さっき言ったことをすぐに忘れてしまいます。時には全く関係ないことをし始めることさえあります（勝手に別のタスクを始めないでほしいですよね、俺じゃねーんだから）。
Subagentsなら独立したコンテキストで動作：
メインClaude：「ログ解析はdebugger subagentに任せます」 ↓ Debugger Subagent：（数千行のログを読み込んで解析） ↓ メインClaude：「問題は○○でした」（要約のみ受け取る）
調査の過程で読み込んだ不要な情報は、Subagentのコンテキストに閉じ込められます。
2. 専門性による品質向上
「小さく単一責任のエージェント」として構築すべきという原則があります。
専門のSubagentなら、コードレビュー専門がセキュリティ、パフォーマンス、可読性を徹底チェックし、デバッグ専門がエラーメッセージから根本原因を特定し、テスト専門がエッジケースまで網羅したテストを作成できます。
3. 権限管理でセキュリティ向上
--- name: code-reviewer description: コードレビュー専門 tools: Read, Grep, Glob # 読み取りのみ、Write権限なし！ ---
レビュアーが勝手にコード書き換えたら困りますよね。必要最小限の権限だけを与えられます。
4. チーム開発での一貫性
.claude/agents/をGit管理すれば、チーム全体で同じ基準で開発できます。新人が入ってきても、すぐに同じ品質を保てます。
基本的な使い方
設定方法
/agentsコマンド（v1.0.60以降）で対話的に作成：
/agents
- 「Create New Agent」を選択
- プロジェクト単位か個人単位かを選択
- 「Generate with Claude」で土台を生成、その後カスタマイズ
- 使用可能なツールを選択
- 識別用の色を選択
ファイルの場所と構造
| タイプ | パス | スコープ | 優先度 |
|---|---|---|---|
| プロジェクト | .claude/agents/ |
現在のプロジェクトのみ | 高 |
| ユーザー | ~/.claude/agents/ |
全プロジェクト共通 | 低 |
--- name: your-agent-name description: このサブエージェントをいつ呼び出すべきかの説明 tools: tool1, tool2, tool3 # 省略すると全ツール継承 --- ここにシステムプロンプトを書きます。 サブエージェントの役割、能力、問題解決へのアプローチを明確に定義。 具体的な指示やベストプラクティス、制約事項も含めます。
設定項目の詳細
| 項目 | 必須 | 説明 |
|---|---|---|
name |
はい | 小文字とハイフンを使った一意の識別子 |
description |
はい | サブエージェントの目的を自然な言葉で説明 |
tools |
いいえ | 特定のツールをカンマ区切りでリスト。省略時は全ツール継承 |
利用可能なツール
基本ツール：
Read,Write,Edit,MultiEdit- ファイル操作Bash- シェルコマンド実行Grep,Glob- 検索
MCPツール（設定時）：
Subagentの呼び出し方法
自動的な呼び出し（推奨）
descriptionに効果的なキーワードを含める：
use PROACTIVELY- 積極的に使用MUST BE USED- 必ず使用- 具体的なトリガー - 「エラー発生時」「コード変更後」など
明示的な呼び出し
> code-reviewer サブエージェントで最近の変更をレビューして > debugger サブエージェントにこのエラーを調査させて
100+の実戦投入可能なSubagents
プロダクションレディなSubagentsのコレクションが既に存在します：
10カテゴリー・100以上のSubagentsが用意されており、コピーして使うだけで即座にプロ級のチームが構築できます。
人気リポジトリ：
- wshobson/agents - 77の専門Subagents
- lst97/claude-code-sub-agents - 33の実用的なSubagents
- vanzan01/claude-code-sub-agent-collective - TDD重視のコレクション
実用的なSubagents設定例（厳選3つ）
1. コードレビュー専門（OWASP準拠）
.claude/agents/code-reviewer.md:
--- name: code-reviewer description: Expert code review for quality and security. Use PROACTIVELY after code changes. MUST BE USED for all PRs. tools: Read, Grep, Glob, Bash --- シニアコードレビュアーとして、OWASP Top 10とSOLID原則に基づいてレビューします。 ## 実行フロー 1. `git diff HEAD~1`で変更内容を確認 2. セキュリティ、パフォーマンス、保守性の観点でレビュー ## セキュリティチェック（OWASP準拠） - SQLインジェクション対策 - XSS対策 - 認証・認可の実装 - 機密情報の露出チェック ## フィードバック形式 🔴 **CRITICAL** - セキュリティ脆弱性 🟡 **WARNING** - パフォーマンス問題 🔵 **SUGGESTION** - ベストプラクティス 必ず具体的な修正コード例を提示。
2. TDD専門（テスト駆動開発）
.claude/agents/tdd-specialist.md:
--- name: tdd-specialist description: Test-Driven Development specialist. MUST BE USED BEFORE implementation. tools: Read, Write, Edit, Bash --- TDDのエキスパートとして、RED-GREEN-REFACTORサイクルを厳守します。 ## TDDサイクル 1. **RED**: 失敗するテストを書く 2. **GREEN**: テストを通す最小限の実装 3. **REFACTOR**: コードを改善 ## カバレッジ要件 - ユニットテスト: 90%以上 - 統合テスト: 主要フロー100% - E2Eテスト: クリティカルパス100% 実装前に必ずテストが失敗（RED）していることを確認。
3. DevOpsトラブルシューター
.claude/agents/devops-troubleshooter.md:
--- name: devops-troubleshooter description: Debug production issues and fix deployment failures. MUST BE USED for incidents. tools: Read, Bash, Write, Edit --- 本番環境のトラブルシューティング専門家です。 ## インシデント対応フロー 1. **状況把握** - 影響範囲と緊急度を評価 2. **ログ収集** - 関連するすべてのログを収集 3. **根本原因分析** - 5 Whys手法を使用 4. **暫定対処** - 即座にサービスを復旧 5. **恒久対処** - 根本原因を解決 6. **事後分析** - RCAドキュメント作成 ## 監視項目と閾値 - CPU使用率: 80% - メモリ使用率: 90% - レスポンスタイム: 1秒 - エラーレート: 1%
よく使えるTips
Subagentsの連携
複数のSubagentsを連携させて複雑なワークフローを自動化する。
> まずcode-analyzerで問題を見つけて、次にperformance-optimizerで修正して
MCPツールとの連携
--- name: github-manager tools: mcp__github__create_issue, mcp__github__create_pull_request ---
プロジェクト固有のカスタマイズ
プロジェクトの特性に合わせて専門Subagentを作成できます。
パフォーマンスへの影響
メリット：
- コンテキスト効率：メインの会話が長く続く
- 専門性による高速化：タスクに特化した処理
デメリット：
- 初回起動の遅延：新しいコンテキスト構築（数秒）
- 頻繁な切り替えは逆効果
ただし、長時間の開発セッションではメリットが圧倒的に大きいです。
チーム開発での活用
Git管理による共有
# .gitignore には含めない .claude/agents/ # チームで共有 # 個人用は別管理 ~/.claude/agents/
オンボーディング
新メンバーは以下のコマンドだけで環境構築完了：
git clone [repo] cd [repo] /agents # Subagents一覧を確認
よくある失敗と対策
| 問題 | 原因 | 対策 |
|---|---|---|
| Subagentが呼ばれない | descriptionが曖昧 | 「PROACTIVELY」「MUST BE USED」を追加 |
| 権限不足エラー | 必要なツールがない | /agentsでツール一覧を確認して追加 |
| コンテキスト不足 | 背景情報がない | システムプロンプトに情報収集ステップを明記 |
まとめ
Subagentsを使えば、Claude Codeに尖った意思を持たせられます。
重要なポイントは、コンテキスト節約でメインの会話を綺麗に保つこと、専門性による品質向上で餅は餅屋に任せること、権限管理で最小権限の原則を守ること、そして100+の実戦投入可能なSubagentsが既に存在することです。これだけ揃っているのに使わない理由があるでしょうか（ないですよね？）。
Claude Codeは適切に設定をしたりちゃんと使えばちゃんと動いてくれます。Claude Codeが雑魚なんじゃない、使い方を知らない…いや、何でもないです。
