Claude Code に "チーム作業" をさせる ー サブエージェントで大規模タスクを分割処理する

Claude Code に "チーム作業" をさせる ー サブエージェントで大規模タスクを分割処理する

Claude Code で長時間の作業を続けていると、「最初に調べた内容を途中から参照できなくなった」「コンテキストが埋まって動きがおかしくなった」といった経験をしたことはないでしょうか。

セッションが長くなるほど、会話履歴やツール呼び出しの結果がコンテキストウィンドウを圧迫していきます。その結果、Claude が序盤の重要な情報を十分に活用できなくなるという問題が起きやすくなります。

この問題を解消する仕組みが、サブエージェントです。サブエージェントは、メインの会話とは切り離された独立したコンテキストウィンドウを持つ専門的な AI アシスタントです。大量のファイル読み込みや調査処理をサブエージェントに任せることで、メインの会話を整理した状態に保ちながら複雑なタスクを進められます。

この記事では、Claude Code のサブエージェント機能の仕組みから、コンテキストを引き継ぐかどうかの2つの起動パターン、組み込みサブエージェントの活用方法、そして自分のワークフローに合わせたカスタムサブエージェントの作成方法までを解説します。

サブエージェントとは何か

サブエージェントは、メインエージェントとは独立したコンテキストウィンドウで動作する AI インスタンスです。メインの会話がサブエージェントにタスクを委譲すると、サブエージェントは独自のコンテキストで処理を行い、結果だけをメインの会話に返します。

たとえば、コードベース全体を探索してどのファイルが認証処理を担当しているかを調べるタスクをサブエージェントに任せると、数十のファイルを読み込んで検索した結果はすべてサブエージェントのコンテキスト内に留まります。メインの会話には調査結果のサマリーだけが返ってくるため、メインのコンテキストウィンドウを圧迫しません。

公式ドキュメント によると、サブエージェントには次のような利点があります。

• コンテキストの保全 ー 探索や実装処理をメインの会話から切り離すことで、コンテキストウィンドウを効率的に使える
• ツールアクセスの制限 ー サブエージェントごとに使用可能なツールを制限することでリスクをコントロールできる
• 設定の再利用 ー ユーザーレベルのサブエージェントとして登録すれば、すべてのプロジェクトで使い回せる
• 特定ドメインへの特化 ー 専用のシステムプロンプトを持たせることで、特定領域のタスク精度を高められる
• コスト最適化 ー 探索タスクを Haiku のような軽量モデルにルーティングすることでコストを抑えられる

重要な点として、サブエージェント自身がさらに別のサブエージェントを生成することはできません。ネストした委譲が必要な場合は、Skills の活用や、メインの会話からサブエージェントを順番に呼び出す設計を検討してください。

組み込みサブエージェントの使い方

Claude Code には、最初から利用できる組み込みのサブエージェントが複数あります。普段の会話の中で Claude が自動的に判断して使い分けているため、特別な設定なしにその恩恵を受けられます。

Explore ー コードベース探索の専門エージェント

Explore は、コードベースを検索・分析するために最適化された読み取り専用のサブエージェントです。Haiku モデルで動作するため高速で低コストです。

Claude がファイルを検索したり、シンボルを grep したり、コードの定義を探す際には変更を加えることなく Explore に委譲します。具体的に呼び出す場合は、次のような自然な言い方で依頼できます。

explore this codebase and find all files related to authentication

Claude は Explore に対して、調査の深さ（quick / medium / very thorough）を指定して委譲します。軽い確認なら quick、バランスの取れた探索なら medium、包括的な分析なら very thorough が使われます。

Plan ー 計画モード時のリサーチエージェント

Plan は、/plan コマンドで計画モードに入った際に Claude が利用する調査エージェントです。計画を立てる前に必要なコンテキストを収集する役割を担っており、読み取り専用のツールのみを使います。

サブエージェントはさらに別のサブエージェントを生成できないため、計画モード中に別の調査が必要になっても無限ループにはなりません。Plan サブエージェントがその調査を担当することで、この制約に対応しています。

General-purpose ー 複合タスク向けの汎用エージェント

ファイルの探索と変更の両方が必要なタスク、複雑な推論が求められるタスク、複数のステップが連鎖するタスクは、Claude が general-purpose サブエージェントに委譲します。全ツールへのアクセス権を持ち、複雑な作業を一手に引き受けます。

コンテキストを引き継ぐかどうか ー 2つの起動パターン

サブエージェントには、起動時にコンテキストを引き継ぐかどうかで2つのパターンがあります。通常のサブエージェントはコンテキストをリセットした状態で起動しますが、フォークと呼ばれるパターンではメイン会話のコンテキストをそのまま引き継いで起動します。

通常サブエージェント ー フレッシュなコンテキストで起動する

通常のサブエージェントは、それぞれ独立した新しいコンテキストウィンドウで起動します。メインの会話履歴は引き継がれず、親からサブエージェントへの唯一の通信経路は委譲時のプロンプト文字列です。タスクに必要なファイルパスやエラーメッセージ、判断の背景はすべてこのプロンプトに含める必要があります。

起動時のコンテキストに含まれるのは、サブエージェント自身のシステムプロンプト、委譲タスクのプロンプト、CLAUDE.md とメモリ、Git のステータス、そして skills フィールドで指定したスキルのコンテンツです。Explore と Plan については、処理を軽く保つために CLAUDE.md と Git ステータスは渡されません。

コンテキストが完全にリセットされるため、大量のファイル読み込みや調査をしてもメインのコンテキストを圧迫しないという利点があります。一方、メインの会話で積み上げてきた背景情報を改めて説明する必要があります。

フォーク ー 会話履歴を丸ごと引き継いで起動する

フォークは、その時点までのメイン会話の履歴をすべて引き継いで起動するサブエージェントです。システムプロンプト・ツール・モデルもメインセッションと同一です。サブエージェント自身のツール呼び出し結果はフォーク内に留まり、メインの会話には最終的な結果だけが返ってきます。

「サブエージェントに任せたいが、これまでの文脈を一から説明し直すのは手間」という場面に向いています。また、フォークはメインセッションのプロンプトキャッシュを共有するため、通常サブエージェントより起動コストが安い点もメリットです。

フォークはまだ実験的な機能であり、Claude Code v2.1.117 以降かつ CLAUDE_CODE_FORK_SUBAGENT=1 の環境変数設定が必要です。有効化すると、/fork コマンドで手動起動できます。なお、フォーク自身がさらにフォークを生成することはできません。

/fork draft unit tests for the parser changes so far

このように入力すると、現在の会話内容を把握した状態でテストの下書きを作るフォークがバックグラウンドで起動し、メインの会話はそのまま続けられます。フォークが完了すると結果がメインの会話にメッセージとして届きます。

2つのパターンの比較

比較項目	通常サブエージェント	フォーク
起動時のコンテキスト	フレッシュ（タスクプロンプト + システムプロンプト + CLAUDE.md + Git ステータス + スキル）	メインの会話履歴をすべて引き継ぐ
システムプロンプト・ツール	サブエージェント定義ファイルの内容	メインセッションと同じ
モデル	サブエージェント定義の model フィールド	メインセッションと同じ
プロンプトキャッシュ	独立したキャッシュ	メインセッションと共有（コスト削減）
権限プロンプト	バックグラウンド時は自動拒否	ターミナルにそのまま表示
向いているケース	大量の調査・ファイル操作の分離	文脈の説明が不要な派生タスク

フォークモードが有効になると、Claude が通常であれば general-purpose サブエージェントを使う場面でフォークを使うようになります。また、すべてのサブエージェントがバックグラウンドで起動するようになるため、挙動が変わる点には注意が必要です。

カスタムサブエージェントを作成する

組み込みサブエージェントだけでなく、自分のワークフローに特化したカスタムサブエージェントを作成できます。たとえば、コードレビュー専用のエージェントや、特定のデータベース操作専用のエージェントを作っておくと、繰り返しのタスクを効率化できます。

/agents コマンドによる作成手順

最も手軽な方法は、/agents コマンドを使う対話的な作成フローです。

Claude Code のセッション内で /agents と入力すると、サブエージェントを管理するインターフェイスが開きます。Running タブではアクティブなサブエージェントを確認でき、Library タブでは新しいサブエージェントの作成や既存のものの編集が行えます。

新規作成の流れは次のとおりです。Library タブで Create new agent を選択し、Personal（ユーザーレベル、全プロジェクトで利用可能）または Project（プロジェクトレベル）を選びます。その後 Generate with Claude を選択し、作りたいサブエージェントを説明すると、Claude がサブエージェントの名前・説明・システムプロンプトを生成してくれます。

ツールの設定では、読み取りのみでよいレビュー系サブエージェントなら Read-only tools だけを選択します。モデルは Sonnet や Haiku など、タスクの複雑さとコストのバランスを考えて選びます。最後にメモリスコープを設定し、保存すれば即座に利用可能になります。

Markdown ファイルによる手動作成

より細かく設定したい場合は、Markdown ファイルを直接書く方法を使います。ファイルの先頭に YAML フロントマターで設定を記述し、その後ろに本文としてシステムプロンプトを書きます。なお、ファイルをディスクに直接追加・編集した場合はセッションを再起動しないと反映されません。/agents コマンド経由で作成した場合は再起動不要で即時有効になる点と異なります。

配置場所によってスコープが変わります。~/.claude/agents/ に置くとすべてのプロジェクトで使えるユーザーレベルのサブエージェント、.claude/agents/ に置くとそのプロジェクト専用になります。プロジェクトレベルの場合は Git にコミットするとチームで共有できます。

コードレビュー用のサブエージェントを例に、ファイルの構成を見てみましょう。

---
name: code-reviewer
description: コードレビュー専門エージェント。コード変更後に自動で呼び出す。
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたはシニアコードレビュアーです。

呼び出された際は以下の手順で進めてください。
1. git diff で最近の変更を確認する
2. 変更されたファイルに集中してレビューする

レビュー項目としては、コードの読みやすさ、命名の適切さ、重複の有無、
エラーハンドリング、セキュリティ上の問題（APIキーや機密情報の露出など）、
テストカバレッジを確認します。

フィードバックは優先度別（Critical / Warning / Suggestion）に整理して出力してください。

フロントマターの主要フィールド

YAML フロントマターで設定できる主な項目を把握しておきましょう。

フィールド	説明
name	一意の識別子。小文字英数字とハイフンで記述（必須）
description	Claude がこのサブエージェントをいつ使うかを決める説明（必須）
tools	使用可能なツールのリスト。省略すると全ツールを継承
disallowedTools	禁止するツールを指定。tools を省略した全ツール継承の状態でも単独で使用可能
model	使用するモデル。エイリアス（sonnet / opus / haiku）、フルモデルID（claude-opus-4-7 等）、または inherit
maxTurns	サブエージェントが実行できる最大ターン数
permissionMode	権限の扱い方。default / acceptEdits / bypassPermissions / plan
memory	永続メモリのスコープ。user / project / local
isolation	worktree を指定すると独立した Git ワークツリーで実行
color	タスクリストでの表示色

description フィールドは特に重要です。Claude はこの説明を読んで、どのサブエージェントにタスクを委譲するかを判断します。「コード変更後に積極的に使用すること」のように具体的なタイミングを書いておくと、自動委譲がより確実に機能します。

memory フィールドでセッション間の知識を蓄積する

サブエージェントのコンテキストはセッションをまたいで引き継がれませんが、memory フィールドを設定することで学習内容を永続的に保存できます。

メモリを有効にすると、サブエージェントのシステムプロンプトに永続メモリディレクトリへの読み書き方法が自動で追加されます。また、そのディレクトリ内の MEMORY.md の先頭 200 行または 25KB が毎回のコンテキストに含まれるようになります。

注意が必要な点として、memory を設定すると tools フィールドで Read / Write / Edit を除外していても、これらのツールが自動的に有効化されます。メモリファイルの管理に必要なためです。ツール制限を厳密に設計している場合は、この挙動を踏まえた設計が必要です。

スコープは 3 種類あります。

スコープ	保存場所	適した用途
user	~/.claude/agent-memory/<エージェント名>/	複数プロジェクトをまたいで知識を共有したい場合
project	.claude/agent-memory/<エージェント名>/	プロジェクト固有の知識を Git で共有したい場合
local	.claude/agent-memory-local/<エージェント名>/	プロジェクト固有だが Git にコミットしたくない場合

たとえばコードレビューエージェントに memory: project を設定しておくと、レビューのたびにプロジェクト特有のコーディングパターンや繰り返し発見される問題点を MEMORY.md に記録していきます。次回のレビュー時にはその知識を踏まえた指摘ができるようになります。

活用のコツとして、タスク開始時に「メモリを確認してから作業を始めて」と指示したり、タスク完了後に「今回学んだことをメモリに保存して」と指示する習慣をつけると、サブエージェントの質が継続的に向上します。

まとめ

サブエージェントは、Claude Code での長時間・大規模な作業の課題をうまく解決してくれる機能です。コンテキストの保全、ツールアクセスの制限、タスクの専門化、そしてコスト最適化といった面で効果を発揮します。

まずは Explore サブエージェントが自動的にコードベースの探索を担当してくれることを意識するだけでも、日常的な Claude Code の使い方が変わってくるでしょう。「これまでの文脈を踏まえた上でサイドタスクをさせたい」という場面ではフォークが選択肢になります。フォークはまだ実験的機能ですが、会話履歴を引き継いでくれるため、文脈の説明を省けるのが魅力です。繰り返し行うタスクが出てきたら、カスタムサブエージェントの作成も検討してみてください。/agents コマンドから Claude に説明を入力するだけで設定ファイルを自動生成してくれるため、初めての方でも始めやすい設計になっています。

サブエージェントを育てながら使い続けることで、プロジェクト固有の知識が蓄積され、チーム全体の開発効率を継続的に改善していける点も大きな魅力です。

この記事がどなたかのお役に立てれば幸いです。

◆　塩野　正人
◆　マネージドサービス部　所属
◆　X（Twitter）：@shioccii
◆　過去記事はこちら

前職ではオンプレミスで仮想化基盤の構築や運用に従事。現在は運用部隊でNew Relicを使ってサービス改善に奮闘中。New Relic User Group運営。