Claude Code サブエージェント

🤖 Claude Code サブエージェント

～コンテキストを圧迫せずに大規模開発を効率化する方法～

📌 サブエージェントとは？

Claude Codeで大規模なプロジェクトを扱うと、次のような問題が発生します。

大量のファイルを調査する
多数のソースコードを読み込む
複雑な分析を行う

すると、Claude Codeのコンテキスト（会話履歴）がすぐにいっぱいになってしまいます。

その結果、 Auto Compact（自動圧縮）が発生し、性能低下につながることがあります。

この問題を解決するのがサブエージェント（Sub Agent）です。

メインのClaude Codeとは別のコンテキストで動作します。

🏢 会社組織で例えると

メインエージェント　：プロジェクトマネージャー

サブエージェント　：専門チーム

例えば、プロジェクトマネージャーが「この機能を調査して」と専門チームへ依頼します。

すると、専門チームは独立して作業します。

専門チームが実施

ソースコード調査
ドキュメント調査
分析
修正作業

最後に返ってくるもの

調査結果はこちらです　/ 修正完了しましただけ。

重要ポイント

メイン側は

調査過程
読み込んだファイル
分析内容

を保持しません。

つまり、

🟢 コンテキストをほとんど消費しない

ということです。

📊 メインエージェントとの違い

項目	メインエージェント	サブエージェント
コンテキスト	共有	独立
調査履歴	残る	残らない
大規模調査	苦手	得意
並列実行	×	○

🚀 サブエージェントが活躍する場面

① 大規模コード調査

例

このシステムで認証処理を探して

数百ファイルを調査する場合でも、サブエージェントならメインコンテキストを汚しません。

② テストカバレッジ向上

例

テストを追加して

複数ファイルへ独立して作業できるため、サブエージェントとの相性が良好です。

③ ドキュメント生成

例

設計書を作成して

大量のコードを読み込みながら、成果物だけを返せます。

④ 大規模リファクタリング

例

命名規則を統一して

大量ファイルを扱う場合に効果的です。

🔧 Claude Code標準のサブエージェント

Claude Codeには最初から複数のサブエージェントが組み込まれています。

Explore

用途

コード調査

特徴

高速
軽量
自動起動されやすい

Plan

用途

計画作成

利用例

Planモード実行時

General Purpose

用途

汎用作業

Claude Codeが必要に応じて自動利用します。

Claude Code Guide

用途

Claude Codeの使い方調査

例

サブエージェントの作り方は？

⚠️ サブエージェント利用時の注意点

コンテキストは共有されない

サブエージェントは、それまでの会話を知りません。

例えば前に話した仕様で修正してと言われても、サブエージェントは理解できません。

良い例

以下の仕様で修正してください

・ログイン失敗時はエラー表示
・3回失敗でロック

明確な指示を渡す必要があります。

並列編集は競合に注意

例えば

サブエージェントA

同じファイルを修正

サブエージェントB

同じファイルを修正

すると、コンフリクトが発生する可能性があります。

🛠️ オリジナルサブエージェントの作り方

配置場所

.claude/
└── agents/

例

.claude/
└── agents/
    └── code-reviewer.md

YAMLフロントマター

---
name: code-reviewer
description: コードレビューを行う専門エージェント
model: sonnet
---

name

エージェント名

name: code-reviewer

ルール

英小文字
ハイフン使用可能
重複不可

description

最重要フィールドです。

Claude Codeはこの説明を読んで「呼び出すべきか」を判断します。

悪い例　：曖昧

description: コードを見るエージェント

良い例　：具体的

description: プルリクエスト差分をレビューし、
命名規則違反・セキュリティ問題・
可読性問題を指摘する

model

利用モデルを指定します。
・Haiku
・Sonnet

・Opus
・Inherit

サブエージェント本文

例

コードレビューを実施してください。

観点

- 命名規則
- 可読性
- セキュリティ
- エラーハンドリング

以下の形式で出力してください。

## 重要
## 警告
## 提案

サブエージェント確認方法

Claude Codeで

/agents

を実行します。

登録済みエージェント一覧を確認できます。

🔥 実践活用例

コードレビュー専用エージェント

code-reviewer

担当

可読性
セキュリティ
命名規則

セキュリティレビュー専用

security-reviewer

担当

APIキー露出
認可制御
SQLインジェクション

パフォーマンスレビュー専用

performance-reviewer

担当

アルゴリズム
メモリ
キャッシュ

🚀 上級テクニック

カスタムコマンド × サブエージェント

最も実践的な使い方です。

review-code コマンド

/review-code UserService.ts

実行

↓

3つのサブエージェントを並列起動

Agent①

Security Reviewer

Agent②

Readability Reviewer

Agent③

Performance Reviewer

全員が同時にレビュー

↓

結果を統合

↓

総合レビュー完成

イメージ

review-code
      │
      ├─ Security Reviewer
      │
      ├─ Readability Reviewer
      │
      └─ Performance Reviewer
               │
               ▼
        レビュー統合
               │
               ▼
          最終レポート

⚠️ 並列実行時の注意

以下は安全です。

✅ 読み取り

✅ 分析

✅ レビュー

以下は注意

⚠️ 同一ファイル編集

⚠️ 同時リファクタリング

⚠️ 同時コード生成

🎯 サブエージェントが呼ばれない場合

方法① Proactivelyを使う

description: Use proactively when reviewing code

積極的に呼び出すよう促せます。

方法② 発動条件を書く

description: Use when reviewing pull requests

方法③ キーワードを書く

description:
Jest
Unit Test
Integration Test
Coverage

方法④ 名前を直接指定

code-reviewerを使ってレビューしてください

最も確実な方法です。

📋 まとめ

Claude Codeを本格的に活用する場合、カスタムコマンドと並んで最も効果の高い機能の一つがサブエージェントです。特に大規模プロジェクトでは、コンテキスト節約と作業分散の効果が非常に大きいため、積極的な活用を推奨します。