重い仕事はサブエージェントへ！メイン会話を散らかさない Claude Code 活用術

どうもソリューションSecの大浦です。
今日は会社でがんがん取り込んでいるClaudeのエージェント機能を記事にしようかと思います。

Claude Code のサブエージェント入門：オーケストレーターに仕事を任せる

Claude Code を使っていると、調査ログやファイルの中身でメインの会話が埋まり、本題の文脈が押し出されてしまうことがあります。これを解決するのが「サブエージェント」です。本記事では、メインの会話（オーケストレーター）とサブエージェントの関係、作り方、運用のコツをエンジニア向けに整理します。

サブエージェントとは

サブエージェントは、特定タスク専用のAIアシスタントです。それぞれが独立したコンテキストウィンドウを持ち、専用のシステムプロンプト、許可するツール、権限を個別に設定できます。

メインの会話がオーケストレーター役となり、タスクの内容がサブエージェントの説明（description）に合致すると、そのサブエージェントへ処理を委任します。サブエージェントは自分のコンテキスト内で作業し、結果の要約だけを呼び出し元に返します。検索結果やログといった中間生成物はメイン会話に流れ込まないため、本来の文脈を圧迫しません。

主なメリットは次のとおりです。

コンテキスト保護：調査や実装の作業をメイン会話の外で行う
制約の強制：使えるツールを限定して安全に実行する
設定の再利用：ユーザー単位のサブエージェントを全プロジェクトで共有
挙動の特化：ドメイン特化のシステムプロンプトで専門化
コスト制御：軽いタスクは Haiku など高速・安価なモデルへ振り分ける

なお、サブエージェントは単一セッション内で動作します。サブエージェントがさらに別のサブエージェントを起動することはなく、オーケストレーションはメイン会話に集約されます。

作り方：`/agents` コマンド

最も手軽なのは /agents コマンドです。実行すると対話的なインターフェースが開きます。

Library タブで Create new agent を選ぶ
保存先を選ぶ（Personal なら ~/.claude/agents/ に保存され、全プロジェクトで利用可能）
Generate with Claude で、やりたいことを説明するとClaudeが識別子・説明・システムプロンプトを生成
許可するツールを選ぶ（読み取り専用レビュアーなら Read 系のみに絞る）
使用モデルを選ぶ（Sonnet など）
※ただ、これを一からやるのは面倒なので、自分はチャットから「オーケストレーターとエージェントを作成したい」、「エージェントにはフロントエンド、バックエンド、レビュワー、テスターを作って！」みたいな感じでざっくり下地を作り、〇○には□□させるという風に微調整を行うようにしています。

ファイル形式

サブエージェントの実体は、YAMLフロントマター＋Markdown本文のファイルです。本文がそのままシステムプロンプトになります。

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

フロントマターの主なフィールドは以下です。

フィールド	必須	説明
`name`	必須	小文字とハイフンによる一意の識別子（ファイル名と一致しなくてよい）
`description`	必須	どんなときにこのサブエージェントへ委任するか
`tools`	任意	使えるツール。省略すると親の全ツールを継承
`disallowedTools`	任意	拒否するツール（継承・指定リストから除外）
`model`	任意	`sonnet` / `opus` / `haiku` / `fable` / 完全なモデルID / `inherit`。既定は `inherit`
`permissionMode`	任意	`default` / `acceptEdits` / `bypassPermissions` など

ファイルの置き場所は2階層あります。プロジェクト用の .claude/agents/ はそのコードベース専用で、バージョン管理に含めてチームで共有・改善できます。ユーザー用の ~/.claude/agents/ は個人用で全プロジェクトから使えます。いずれも再帰的にスキャンされるため、サブフォルダで整理しても構いません。

なおファイルを直接編集した場合はセッションの再起動で読み込まれます。/agents インターフェースから作成した場合は再起動不要で即時反映されます。

呼び出し方：自動委任と明示指定

呼び出しには2通りあります。自動委任では、ユーザーのリクエストと各サブエージェントの description が合致した際にClaudeが自動でタスクを振り分けます。説明文が委任のトリガーになるため、「いつ使うか」を具体的に書くことが重要です。

もう一方の明示指定では、対象のサブエージェントを名前で直接呼び出します。CIやスケジュール実行など、確実に同じエージェントを動かしたい場面ではこちらが向いています。

運用のベストプラクティス

サブエージェントは単一責任で設計します。「調査と実装」を1つに詰め込まず、役割ごとに分けるほうが説明も明確になり、自動委任も安定します。

ツールは最小権限で。レビュアーや監査のような読み取り役には Read 系のみを与え、書き込みやBashは渡しません。

そして、オーケストレーターからサブエージェントへ渡る情報はプロンプト文字列だけです。サブエージェントはメイン会話の履歴を見られないため、ファイルパス・エラーメッセージ・前提条件は委任時のプロンプトに明記します。

まとめ

サブエージェントは「専門の作業者に文脈を切り分けて任せる」仕組みです。メイン会話を汚さずに調査・レビュー・実装を並行させられ、ツール制限による安全性とモデル選択によるコスト最適化も両立します。まずは /agents でレビュー用のサブエージェントを1つ作り、明示指定で呼び出すところから始めてみてください。

ではこのへんで！

参考：Create custom subagents — Claude Code Docs