Claude Code のサブエージェント機能を改めて確認してみた

AI事業本部/西日本開発チームの片桐です。
先日、 Claude Code の初回セットアップについて紹介しました。

今回はステップアップとして、サブエージェントについてまとめていきます。

この記事について

[対象読者]

• Claude Code の基本機能を復習したい方
• Claude Code で効率よく作業をしたい方

🪧 実装手順のみを確認したい方は 「ここから」 進んでください。

サブエージェントのメリットから使い所を見極める

まずは、公式ドキュメントのメリットを元に、サブエージェントが必要とされる場面を考えていきます。

コンテキストを保持することで、探索と実装をメインの会話から分離します

コンテキスト(過去の会話履歴など)を引き継ぎつつも、処理を分離できるため、コンテキストウィンドウの汚染を抑制できます。

使い所: 調査・実装・レビューなど、工程ごとにエージェントを分けたいとき

制約を強制することで、サブエージェントが使用できるツールを制限します

エージェント単位で、動作を制限することができます。
例えば、調査エージェントは編集操作をさせない。特定のエージェントだけMCP接続を許可するなど。

使い所: 誤操作や意図しない変更を防ぎたいとき、権限を厳密に分けたいとき

設定を再利用することで、ユーザーレベルのサブエージェントをプロジェクト全体で再利用します

サブエージェントはユーザー単位で作成することで複数のプロジェクトをまたいで利用でき、またプロジェクト単位での作成も可能です。
用途に応じて使い分けることができます。

使い所: 複数プロジェクトで同じ役割のエージェントを使いまわしたいとき

動作を特化させることで、特定のドメイン向けの焦点を絞ったシステムプロンプトを使用します

何でもできる汎用アシスタントではなく、「あなたはAWSの請求に関する事実確認の専門家です」のように、特定のタスク(ドメイン)に特化した専用の指示を与えることができます。

使い所: 特定の技術領域や業務ルールに沿った、精度の高い回答が必要なとき

コストを制御することで、 Haiku のような高速で安価なモデルにタスクをルーティングします

サブエージェントはモデルを個別に指定できるため、用途に応じて使い分けることができます。
例えば、調査タスクには低コストな Haiku を、仕様設計には高性能な Opus を割り当てるといった柔軟な調整が可能です。

使い所: タスクの重要度や複雑さに応じて、コストを最適化したいとき

Skillsとの違い

サブエージェントのメリットを見ていくと、「 Skills で同じことができるのでは？」と感じる方もいるかもしれません。
ここで２つの違いを整理してみます。

簡単にまとめると下記のようなものだと考えます。

Skills は Claude Code にできることを増やす
サブエージェント は Claude Code の中に専門家を作る

標準で用意されているエージェント

Claude Code には標準で5つのエージェントが用意されています。
※うち2つは Claude Code のセットアップに使用するエージェントのため、ここでは解説を省きます。

• Explore
  コードベースの検索や分析に最適化されたエージェントです。
  Haiku モデルを利用するため、高速かつ低コストでファイル検索やコード検索を行います。

• Plan
  プランモード中に使用されるエージェントです。
  メインの会話と同じモデルを利用し、読み取り専用の権限が付与されているため、
  意図しない変更を防ぎながら計画を立てられるよう制御されています。

• General-purpose
  探索と実行が必要な複雑なタスク向けのエージェントです。
  メインの会話と同じモデルを利用し、読み取りだけでなくファイルの編集など
  実行操作も安全に行えるよう設定されています。

調査をメインで行う場合は Explore 、調査しながら実装もする場合は General-purpose を利用すると良いです。

サブエージェント作成

サブエージェントの作成には、 /agents コマンドを使用する場合と、手動で Markdownファイルを作成する方法があります。

/agents を用いると、 Claude Code を用いて効率的に作成できるため、今回はこちらで進めます。

1. Claude Codeを起動

任意の場所で、Claude Code を起動してください。

claude

2. サブエージェント作成コマンドの実行

下記コマンドを実行することで、サブエージェントの作成を開始できます。

/agents

上記コマンド実行後、 Create new agent を選択してください。

3. サブエージェントの利用範囲の設定

サブエージェントを利用することができる範囲を設定します。
Personal を設定すると、すべてのプロジェクトから利用可能になります。
Project の設定では、そのプロジェクト内のみで利用可能です。

4. プロンプト生成方法を選択

サブエージェントのプロンプトの作成を手動もしくは Claude から選択できます。
今回は Claude を利用します。

5. 作成するサブエージェントの説明を入力

次は、作成するサブエージェントについての説明を入力します。
この説明を元に、 Claude がプロンプトを生成するので、具体的に入力しましょう。

今回はコードレビューエージェントを作成するための説明を入力しました。

あなたはコードレビューの専門家です。
開発者がコードの変更をレビューしたい場合に使用します。
`git diff` または指定されたファイルを分析し、以下の観点でフィードバックを提供してください。

- コードの品質・可読性
- バグや考慮漏れの可能性
- セキュリティ上の懸念点
- パフォーマンスの問題
- ベストプラクティスや設計パターンへの準拠

指摘箇所は具体的な行番号を添えて、建設的なフィードバックを提供してください。

6. 利用ツールの設定

プロンプト生成が完了したら、次はツールの利用設定です。

該当のツールにカーソルを移動して、 Enterキー で選択を切り替えることができます。

各項目の詳細

• All tools: すべてのツール
• Read-only: 読み取りツール
• Edit tools: 編集関連ツール
• Execution tools: 実行関連ツール
• MCP tools: MCP関連ツール
• Other tools: その他のツール

今回はコードレビューだけなので、 Read-only tools を選択します。

7. 利用モデルの選択

次は、サブエージェントが利用するモデルを選択します。

• Sonnet: バランスのとれたモデル
• Opus: 複雑な推論タスクに適したモデル
• Haiku: シンプルなタスクには効果的なモデル
• Inherit from parent: メインの会話と同じモデルを利用

コストを抑えるために、今回は Haiku を利用します。

8. 背景色の選択

サブエージェント利用時の背景色を設定できます。
※ 背景色が変わるのはサブエージェントを実行した際の、サブエージェント名の背景のみです。

9. メモリ設定

サブエージェント用のメモリ(記憶領域)の保存場所を選択します。

• User Scope: 全プロジェクト共通
• None: メモリ保存なし
• Project Scope: プロジェクトごとに保存
• Local Scope: ローカル環境に保存

今回は保存無しにしています。

  Configure agent memory

    1. User scope (~/.claude/agent-memory/) (Recommended)
  ❯ 2. None (no persistent memory)
    3. Project scope (.claude/agent-memory/)
    4. Local scope (.claude/agent-memory-local/)

   ↑↓ to navigate · Enter to select · Esc to go back

下記の用途でサブエージェントを活用したい場合は、メモリの設定をおすすめします。

• 過去のレビュー履歴を参照して一貫性を保ちたい
• プロジェクト固有のルールを蓄積していきたい

10. 設定の確認

最後に、設定の確認を行います。
編集が必要な場合は eキー で編集することができます。
作成後でも編集することは可能です。

  Confirm and save

  Name: code-reviewer
  Location: /Users/katagiri.tsubasa/.claude/agents/code-reviewer.md
  Tools: Glob, Grep, Read, WebFetch, and WebSearch
  Model: Haiku
  Memory: None

  Description (tells Claude when to use this agent):

    Use this agent when a developer wants to review code changes. Trigger this agent after writing a significant
    chunk of code, before submitting a pull request, or when reviewing specific files for quality assurance.

    Examples:
    <example>
    Context:…

  System prompt:

    あなたはコードレビューの専門家です。10年以上の開発経験を持ち、コード品質・セキュリティ・パフォーマンス・設計パタ
    ーンに精通したシニアエンジニアとして、建設的かつ実践的なフィードバックを提供します。

    ## レビュー対象の取得
    - ユーザーが `git diff…

  Press s or Enter to save, e to save and edit

   s/Enter to save · e to edit in your editor · Esc to cancel

11. 作成したサブエージェントの確認

作成完了後は /agents でサブエージェントを確認、編集することができます。

  Agents
  6 agents

  Created agent: code-reviewer and opened in editor. If you made edits, restart to load the latest version.

    Create new agent

    User agents
  ❯ code-reviewer · haiku

    Built-in agents (always available)
    claude-code-guide · haiku
    Explore · haiku
    general-purpose · inherit
    Plan · inherit
    statusline-setup · sonnet

  Press ↑↓ to navigate · Enter to select · Esc to go back

あとは、サブエージェント名を含めて Claude Code に指示を出すだけで、利用することができます。

プロンプト例

実際にサンプルで作成した Python プログラムをレビューしてもらいました。

❯ code-reviewer @user_manager.py のコードレビューをしてください。
  ⎿  Read user_manager.py (41 lines)

⏺ code-reviewer(user_manager.py の包括的コードレビュー実施)
  ⎿  Done (1 tool use · 9.5k tokens · 21s)
  (ctrl+o to expand)

⏺ 詳細なコードレビューが完了しました。

  📋 レビュー結果のハイライト

  🔴 Critical（即座対応が必要）

  1. ハードコードされたパスワード - セキュリティリスク
  2. ファイルハンドルのリーク - with文が必要
  3. キー存在確認なし - KeyError対策が必要

  🟡 Warning（次段階）

  - 入力値の検証がない
  - パストラバーサル攻撃への対策がない
  - 内部状態の直接公開

  🟢 Suggestion（品質向上）

  - 型ヒントの追加
  - ドキュメント文字列の充実

  ---
  ❓ 次のステップについて

  このコードは教育的な「アンチパターン集」という意図でしょうか？それとも本番コードとして使用する予定ですか？

  意図に応じて修正計画を調整したいので、教えていただけますか？

  - 教育用途: そのままでも良い（「何が問題か」を示す教材）
  - 本番用途: Critical項目から順に修正をお進めします

しっかりと意図した部分を的確にレビューしてくれました。

おわりに

本記事では、 Claude Code の標準エージェントから、カスタムサブエージェントの作成方法までご紹介しました。
AI駆動開発を効率よく行うためには、サブエージェントは非常に有効な手段です。
ワークフローに合わせて、カスタマイズして活用していきましょう。

参考資料

• Claude Code 公式ドキュメント - サブエージェント