MENU
  1. ホーム
  2. Claude Code
  3. Claude Code Explore/Plan/general-purposeの役割比較

Claude Code Explore/Plan/general-purposeの役割比較

Claude Code
Claude Code Explore/Plan/general-purposeの役割比較 | mohablog

Claude Codeのサブエージェントは3種が標準で用意されています。Explore・Plan・general-purposeで、それぞれモデルとツール権限が違います。どれが自動で呼ばれているか把握しないと、Haikuで済む探索にSonnetを使ってしまったり、Plan Modeなのに書き換えが走るのではと不安になったりします。

このページは公式ドキュメント “Built-in subagents” セクション(Claude Code 2.1系)の挙動を、手元のセッションログと照合しながら整理したメモです。

目次

Built-in subagentsの3種が並ぶ理由

3つに分かれている狙い

サブエージェントは独立したコンテキストウィンドウを持つ別セッションで動きます。親会話に戻ってくるのは要約だけ。これで親コンテキストを汚さずに済みます。3種に分けてあるのは、読むだけで安く速い / plan mode 中の読み取り専用 / 書き換えまで含む万能型という用途差を、Claude側が自動で選び分けるためです。

公式の “Built-in subagents” 節には次の一文があります。

Each inherits the parent conversation’s permissions with additional tool restrictions.

親会話の権限を引き継いだ上で、ツール側を絞って渡している構造です。general-purposeだけは絞りが入らず、Edit/Write/Bashまで触れます。

共通する仕組みと決定的な違い

3種すべてに共通するのは、独立コンテキストと結果は要約だけ親に返るの2点。違いはこの並びになります。

  • Explore: 使用モデルがHaiku固定。Sonnet/Opus会話の中でもHaikuで走る
  • Plan: plan mode の最中だけ呼ばれる。通常モードでは出てこない
  • general-purpose: 全ツール許可。書き換えや実行を含むタスクで自動委譲される

Exploreで該当ファイルだけ洗い出し、結果をプロンプトに貼ってgeneral-purposeに「このファイル群を書き換えて」と渡すリレー構成も組めます。

Explore: Haikuで動く読み取り専用エージェント

thoroughness は quick / medium / very thorough の3段

ExploreにはClaudeがthoroughnessを一緒に渡します。3段階あって、それぞれ探索の深さが変わります。

{
  "description": "Locate auth helpers",
  "subagent_type": "Explore",
  "prompt": "Find files defining JWT helpers...",
  "thoroughness": "quick"
}

呼び出し後、親に戻ってくるのはファイルパスと該当行の要約だけです。

Explore result:
- src/auth/jwt.ts:12  signToken()
- src/auth/jwt.ts:48  verifyToken()
- tests/auth/jwt.spec.ts:5  fixtures only

quickは1点ピンポイント、mediumは中程度の網羅、very thoroughは命名揺れまで含めた網羅探索になります。「とりあえずgrep」レベルならquick、設計レビュー前の網羅調査ならvery thoroughと使い分けます。

CLAUDE.mdをスキップする副作用

これは公式 “Built-in subagents” 節に明記されています。

Explore and Plan skip your CLAUDE.md files and the parent session’s git status to keep research fast and inexpensive.

プロジェクト固有のルール(例: 「テストはintegrationディレクトリにある」)はExploreには届きません。探索結果が想定とズレるときは、CLAUDE.md依存の指示を出していないか疑います。

Plan: plan mode の中だけ走る調査専用

Exploreとは別物が必要な理由

Plan Modeでは書き換えが禁止されます。そこでClaudeがコードベースを理解するために投入されるのがPlanサブエージェント。Exploreではダメなのか?と疑問が湧きますが、公式の説明はこうです。

This prevents infinite nesting (subagents cannot spawn other subagents) while still gathering necessary context.

サブエージェントは他のサブエージェントを呼べない仕様。plan mode中の親はそれ自体がエージェント的に動いていて、Exploreを呼ぼうとすると入れ子になってしまう。だからplan mode専用の調査担当としてPlanが用意されています。

Plan で起こりがちな勘違い

Plan Modeに入ったから安全、ではありません。Planサブエージェントが探索した結果に基づいて、親が計画を提示するだけ。承認後にplan modeを抜けると、書き換えはgeneral-purposeや親本体が担当します。

Plan Modeの全体的な使い方はClaude Code Plan Modeの使い方—auto-acceptへの切替判断で別途整理しています。

general-purpose: 書き換えまで任せる万能型

All tools が許される

general-purposeはRead / Write / Edit / Bash / Grep / Globを含む全ツールを持ちます。モデルは親会話と同じ。Sonnet会話で呼ばれればSonnet、Opus会話で呼ばれればOpusで動きます。

典型的な委譲先はこんなタスクです。

  • 調査と実装を一気に走らせるリファクタ作業
  • テストを書いて落ちたら直す、までを1つの会話で済ませたい場合
  • 複数ファイルにまたがる小さな整理(rename, import整列など)

コストとリスクの天秤

general-purposeはコンテキストが独立しているので、調査ログが親に混ざりません。代わりにEdit/Writeの実行履歴も親には要約しか戻らないので、何が変わったかを後追いするにはgit diffを見にいく必要があります。

並列でgeneral-purposeを連発するとAPI使用量が跳ねるので、並列度の見積もりはClaude Codeのサブエージェント並列実行—コスト管理と設計のハマりどころを参考にしてください。

3種を1枚にまとめる

表で済ませます。

項目ExplorePlangeneral-purpose
モデルHaiku 固定親会話と同じ親会話と同じ
ツール読み取り専用読み取り専用全ツール
呼ばれる場面通常モードの探索plan mode 中だけ調査+書き換え
CLAUDE.md読まない読まない読む
git status渡さない渡さない渡す
thoroughness指定あり (3段)なしなし

CLAUDE.mdとgit statusの行は実害が出やすい場所です。CLAUDE.mdで「テストは tests/integration/ 配下」と指示していても、ExploreはCLAUDE.mdを読まないため、tests/ 直下を探して「該当ファイルが見つかりません」と返してくることがあります。

Agentツールで明示的に subagent_type を呼ぶ

subagent_type の正確な名前

Agentツール呼び出しでsubagent_typeを指定すると、自動委譲ではなく明示的に種類を選べます。受け付ける値は次の3つです。

{
  "description": "List all migration files",
  "subagent_type": "Explore",
  "prompt": "Find every file under db/migrations/..."
}

実行結果は親会話に文字列で戻ります。

Agent result (Explore):
Found 18 migration files in db/migrations/
Latest: 0042_add_user_index.sql (2026-04-30)

2.1.122以降では値の照合が大文字小文字・区切り文字を無視するようになりました。”general-purpose” と “General Purpose” は同じものとして解決されます。

自動委譲と明示呼び出しの境目

明示呼び出しが効くのは、同じ種類のリサーチを何度も繰り返すケース。コードレビュー用のチェックリスト走査を毎回Exploreに振りたいなら、最初からsubagent_type: "Explore"で呼ぶ方が安定します。

逆に、調査と書き換えのどちらが必要か事前に決まらないタスクは、自動委譲に任せた方が早い。Claudeがgeneral-purpose相当か単発のExploreかを判断して投げます。

実運用でハマりやすいところ

CLAUDE.md と git status が届かない

Explore/Planを使った調査で「ファイルパスが微妙にずれる」「廃止されたディレクトリを探す」現象が出ることがあります。原因の半分くらいはCLAUDE.mdの規約が届いていないこと。プロジェクトの命名規則をCLAUDE.mdで指示している場合、Exploreにはそれが見えないと意識した方がいいです。

どうしても規約を踏ませたい探索なら、明示プロンプトで規約を渡し直すか、最初からgeneral-purposeに任せます。

サブエージェントは他のサブエージェントを呼べない

これは設計上のハードリミット。general-purposeの中で「ここはExploreに振りたい」と思ってもネストはできません。回避策はこの2つ。

  • 親会話側で、まずExploreを呼んで結果を集めてからgeneral-purposeに渡す
  • Agent Teams(別セッションで動かす機能)を使って、独立セッション同士で連携させる

Agent Teamsは並列セッションを束ねる別レイヤなので、subagent_typeとは別物として扱う必要があります。

statusline-setup と claude-code-guide

3種以外にも内蔵エージェントがあります。/statusline実行時に呼ばれるstatusline-setup(Sonnet)、Claude Code自体の使い方を聞いたときに呼ばれるclaude-code-guide(Haiku)の2つ。これらは内部用で普段は意識不要ですが、ログに別エージェント名が出ても驚かないように。

カスタム定義は CLAUDE.md を読む

3種で足りないケースは~/.claude/agents/に独自定義を置きます。フロントマターでname / description / tools / modelを書くだけ。

---
name: db-migrator
description: "DBマイグレーション専用。schema/配下のみ書き換え可"
tools: ["Read", "Write", "Edit", "Bash"]
model: sonnet
---

スキーマ変更時は db/migrations/ に新規ファイルを作成し、
ダウンマイグレーションも必ず用意する。

このファイルをdb-migrator.mdとして保存すれば、subagent_type: "db-migrator"で呼べます。

$ ls ~/.claude/agents/
db-migrator.md
code-reviewer.md

カスタム側はCLAUDE.md を読み込む挙動になっているので、プロジェクト規約を踏ませたい用途には built-in 3種よりこちらが向きます。

まとめ

  • Explore は Haiku 固定で読み取り専用。CLAUDE.md と git status を読まない
  • Plan は plan mode 中だけ走る調査担当。Exploreとはネスト防止のため別系統
  • general-purpose は全ツール許可で親モデルと同じ。書き換えを含む複合タスク向け
  • Agentツールでsubagent_typeを明示すれば自動委譲を上書きできる
  • サブエージェントは入れ子にできないので、リレー構成は親会話側で組む

3種の境目を覚えておくと、CLAUDE.md依存の調査はExploreから外し、plan modeでは書き換えが絶対走らないと割り切り、書き換えを含むタスクだけgeneral-purposeに渡す、と振り分けが機械的に決まります。”Built-in subagents” の節と/agentsコマンドで定義済みエージェントを並べたとき、その分類が頭に入っていると迷いません。

Claude Code
Claude Code 自動化 設計パターン
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！
目次