Claude Code を対話で使い慣れた会社が次にぶつかるのが、「1つの会話に調査もファイル編集も点検も詰め込むと、途中から精度が落ちる」という壁です。長いログを読ませた後に報告書を書かせると、前半の内容を引きずった文章が返ってきたり、点検役が自分の書いた文章に甘くなったりします。
この記事では、Claude Code の公式ドキュメント（2026年10月時点）だけを出典に、サブエージェントが何を分離し何を共有するのか、定義ファイルの書き方と置き場、権限がどう引き継がれるのか、並列と入れ子の上限、記録の残し方を整理します。そのうえで、業務自動化でよく使う「調べる・書く・点検する」の3役に分ける雛形と、任せすぎたときの失敗例をまとめました。読者は、社内の業務改善・情報システム・Web の担当者を想定しています。
結論 — 先に要点だけ
- サブエージェントは「別の文脈・別の道具・別の権限」で動く補助役。 メインの会話履歴は見えず、戻ってくるのは最終報告だけです。長い出力をメインから外す目的で使います
- 定義は Markdown ファイル1枚。
.claude/agents/に置けばプロジェクトで共有でき、nameとdescriptionが必須、toolsとmodelで道具とモデルを絞ります - 権限は親より強くならない。 メインが緩いモードならサブエージェントもそのモードで動き、メインが厳しいモードなら定義側の
permissionModeが使われます（bypassPermissionsの宣言は無視） - 上限は既定で同時 20・入れ子 3層。 利用枠はメインと共有なので、単純作業は小さいモデルに寄せ、
/usageの内訳でサブエージェントの割合を見ます - 記録は自動で残るが、既定では 30日で消える。 監査に使うなら
SubagentStopフックで最終報告を自社のログに書き出す仕組みを足します
何が分かれて、何が共有されるのか
サブエージェントは、専用のシステムプロンプト・道具の範囲・権限を持ち、独自のコンテキストウィンドウで動く補助役です。Claude は依頼の内容がサブエージェントの description に合うと判断すると、そのサブエージェントに仕事を渡し、結果だけを受け取ります。
| 項目 | サブエージェント側 | メインの会話との関係 |
|---|---|---|
| コンテキストウィンドウ | 起動ごとに新しく作られる | メインの会話履歴は見えない |
| 最初に入る情報 | 自分のシステムプロンプト・依頼文・CLAUDE.md・git の状態・事前読み込みのスキル | メインの自動メモリや出力スタイルは届かない |
| 途中の道具の出力 | サブエージェントの文脈に残る | メインには戻らない |
| 最終報告 | 1回だけ返す | メインの文脈に入る |
| 利用枠（トークン） | 自分の要求ぶんを消費する | メインと同じ利用枠を消費する |
※ 出典: Claude Code Docs — Custom subagents（取得 2026-10）
この分離が効くのは、テストの実行・ドキュメントの取得・ログの処理のように出力が長い作業です。公式の費用のページも、こうした作業をサブエージェントに任せると「長い出力はサブエージェントの文脈に留まり、要約だけがメインに戻る」と説明しています。ただし、サブエージェントの要求もメインと同じ利用枠を消費するので、「分ければ安くなる」わけではありません。
※ 出典: Claude Code Docs — Manage costs effectively（取得 2026-10）
最初から入っているサブエージェント
定義ファイルを書かなくても、Claude Code には組み込みのサブエージェントがあります。業務で定義を作る前に、どれが勝手に動きうるかを把握しておくと、「誰も頼んでいないのに別の作業者が動いた」という戸惑いを避けられます。
| 名前 | 道具 | 役割 |
|---|---|---|
| Explore | 読み取り専用（Write・Edit は拒否） | コードやファイルの高速な検索 |
| Plan | 読み取り専用（Write・Edit は拒否） | プランモード中の調査 |
| general-purpose | サブエージェントが使える全道具 | 調査と実行の両方が要る多段の作業 |
| claude | サブエージェントが使える全道具 | どれにも当てはまらない作業の受け皿 |
| statusline-setup | — | ステータスラインの設定 |
| claude-code-guide | — | Claude Code の機能に関する質問 |
※ 出典: Claude Code Docs — Custom subagents（取得 2026-10）
Explore と Plan は CLAUDE.md と git の状態を読みません。それ以外のサブエージェントは CLAUDE.md を読みます。組み込みを止めたいときは、設定の permissions.deny に Agent(Explore) のように書けば特定の種類だけを止められ、Agent と書けば委任そのものを止められます。
役割を3つに分ける — 調べる・書く・点検する
業務自動化で最初に効くのは、1つの仕事を「調べる」「書く」「点検する」の3役に分け、それぞれに違う道具を渡す設計です。点検役に書き換えの道具を渡さないことで、「点検しながら直してしまい、何を直したか分からない」状態を防げます。
| 役割 | 渡す道具 | 渡さない道具 | モデルの考え方 |
|---|---|---|---|
| 調べる（researcher） | Read・Grep・Glob | Edit・Write・Bash | 読むだけなので小さいモデルで足りることが多い |
| 書く（writer） | Read・Edit・Write | Bash（必要なら許可リスト付きで） | メインと同じモデルを継承（inherit） |
| 点検する（checker） | Read・Grep・Glob・Bash | Edit・Write | 書く役と別のモデルにすると「自分に甘い」を避けやすい |
定義ファイルの例です。.claude/agents/checker.md のように置きます。
---
name: checker
description: 月次レポートの下書きを点検する。数値の出典・計算・表記ゆれを確認し、修正はせず指摘だけを返す。下書きが書き上がったら使う。
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 30
---
あなたは点検担当です。ファイルを書き換えてはいけません。
1. 下書きの数値が元データと一致するか、元ファイルを読んで確かめる
2. 合計・割合の計算をやり直す
3. 指摘は「場所・何が違うか・根拠」の3点で箇条書きにする
修正案は書いてよいが、ファイルには適用しないこと。
本文がそのままシステムプロンプトになります。Claude Code 本体のシステムプロンプトは渡されず、「自分のプロンプトと基本的な環境情報」だけで動くので、守らせたい手順は本文に書き切る必要があります。
description は Claude が「いつこのサブエージェントに渡すか」を決める材料です。公式は「短く、1つのサブエージェントを指し示す書き方」を勧めていて、定義全体の description の合計が 15,000 トークンを超えると起動時に警告が出ます。「下書きが書き上がったら使う」のように、使う場面を書き添えると振り分けが安定します。
※ 出典: Claude Code Docs — Custom subagents（取得 2026-10）
呼び出し方は4つあります。依頼内容と description から Claude が自動で選ぶ、「checker サブエージェントで点検して」のように自然文で指名する、@agent-checker の形で指名する、claude --agent checker でセッション全体をそのサブエージェントとして動かす、です。
社内でこの3役の分け方を自分たちで組む場合の進め方は、企業向けの有料の実務書にもまとめています。
定義ファイルの置き場と優先順位
同じ name の定義が複数あるときは、上の段が勝ちます。会社で統一したい定義は管理設定、チームで共有したい定義はプロジェクトの .claude/agents/、個人の道具は ~/.claude/agents/ に置くのが基本です。
| 優先 | 置き場 | 届く範囲 |
|---|---|---|
| 1 | 管理設定（managed settings） | 組織全体 |
| 2 | --agents フラグ（JSON） | そのセッションだけ |
| 3 | .claude/agents/ | そのプロジェクト |
| 4 | ~/.claude/agents/ | その人の全プロジェクト |
| 5 | プラグインの agents/ | プラグインが有効な場所 |
※ 出典: Claude Code Docs — Custom subagents（取得 2026-10）
プロジェクトと個人のフォルダは下位フォルダまで再帰的に読まれ、識別はフォルダ名ではなく name で行われます。ファイルの編集は数秒で反映されますが、agents フォルダを新しく作ったときは再起動が要ります。name が無い、description が無い、YAML が壊れている定義は黙って飛ばされるので、読み込まれない定義は --debug で理由を確かめます。
frontmatter に書ける主な項目は次のとおりです。
| 項目 | 必須 | 用途 |
|---|---|---|
name | 必須 | 識別名。: は使えない（プラグイン用に予約） |
description | 必須 | いつ委任するかの判断材料 |
tools | 任意 | 許可する道具の一覧。省略すると使える道具をすべて継承 |
disallowedTools | 任意 | 拒否する道具。tools より先に適用される |
model | 任意 | sonnet・opus・haiku・inherit またはモデル ID |
permissionMode | 任意 | default・acceptEdits・dontAsk・plan など |
maxTurns | 任意 | ターン数の上限。超えると途中の結果が「部分的」として返る |
memory | 任意 | user・project・local のいずれかで永続メモリを有効化 |
isolation | 任意 | worktree で一時的な git ワークツリーの中で動かす |
background | 任意 | true でバックグラウンド実行 |
※ 出典: Claude Code Docs — Custom subagents（取得 2026-10）
モデルの決まり方には順番があります。Claude が呼び出し時に渡す指定、定義ファイルの model、環境変数 CLAUDE_CODE_SUBAGENT_MODEL、メインの会話のモデル、の順です。全社で「サブエージェントは必ずこのモデル」と固定したいときは、CLAUDE_CODE_SUBAGENT_MODEL に加えて CLAUDE_CODE_SUBAGENT_MODEL_FORCE を 1 にすると、定義側の指定を無視して1つのモデルに揃えられます。
権限はどう引き継がれるか — 親のモードが勝つ場面
サブエージェントの権限で最も誤解されやすいのが、「定義ファイルの permissionMode が常に効く」という思い込みです。実際は、メインの会話のモードによって扱いが変わります。
| メインの会話のモード | サブエージェントの動き |
|---|---|
bypassPermissions・acceptEdits・auto | メインと同じモードで動く。定義の permissionMode は無視 |
default・dontAsk・plan | 定義の permissionMode が使われる。ただし bypassPermissions の宣言は無視され、メインのモードのまま |
※ 出典: Claude Code Docs — Custom subagents（取得 2026-10）
つまり、サブエージェントに親より強い権限を持たせることはできず、逆に親が緩いと定義で絞ったつもりのサブエージェントも緩くなります。無人実行で --dangerously-skip-permissions を使っている環境では、点検役の「書き換え禁止」が permissionMode では守れないので、tools で Edit と Write を外す形で守る必要があります。
もう1つの落とし穴は disallowedTools の書き方です。disallowedTools: Bash(git push *) と書くと、git push だけでなく Bash という道具そのものが外れます。特定のコマンドだけを止めたいときは、設定の permissions.deny に Bash(git push *) の規則を足します。
道具の一覧に書いても必ず外される道具もあります。利用者に質問する AskUserQuestion、プランモードに入る EnterPlanMode、予約実行の ScheduleWakeup などです。サブエージェントは「人に聞けない」前提で動くので、判断が要る作業は渡さず、判断材料を集めるところまでを渡す設計にします。
任せすぎの失敗パターン 5つ
- 点検役に Edit を渡す。 「指摘だけ」と本文に書いても、道具があれば直してしまうことがあります。点検役は
toolsから Edit・Write を外し、指摘を受けてメインか書く役が直す流れにします - 1つのサブエージェントに全部を任せる。
general-purposeに「調べて書いて点検して」と渡すと、分けた意味が無くなります。役割ごとに定義を分け、descriptionに使う場面を書きます - メインの会話で決めたことが伝わっている前提で依頼する。 サブエージェントはメインの履歴を見ません。依頼文に、対象ファイル・期間・出力の形式を毎回書きます。依頼文だけが判断材料です
maxTurnsを付けずに長い作業を渡す。 止まらない作業は利用枠を消費し続けます。上限を付け、「部分的」と印の付いた結果が戻ったら再開するか人が見るかを決めます- 組み込みのサブエージェントが CLAUDE.md を読んでいる前提で頼る。 Explore と Plan は CLAUDE.md を読みません。社内ルールを守らせたい調査は、CLAUDE.md を読む自作の調べる役に渡します
並列・入れ子の上限と、モデルの使い分け
サブエージェントはさらにサブエージェントを呼べます。既定ではメインの会話から数えて 3層までで、上限に達すると Agent の道具が外されます。環境変数 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で変えられ、1 にすると入れ子を禁止できます。同時に動かせる数は既定で 20 までで、超えると「Concurrent subagent limit reached」で起動に失敗します。こちらは CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で変えられます。
※ 出典: Claude Code Docs — Custom subagents（取得 2026-10）
業務で使う最初の段階では、入れ子を禁止して平らな構成にしておくほうが、どのサブエージェントが何をしたかを追いやすくなります。並列も、点検役が書く役の結果を待つ流れなら、同時に動かす必要はありません。
費用の面では、公式の費用のページが「単純なサブエージェントの作業には定義で model: haiku を指定する」と勧めています。モデルごとの定価（2026年10月時点）は次のとおりです。
| モデル | 入力（1M トークンあたり） | 出力（1M トークンあたり） |
|---|---|---|
| Claude Haiku 5.5（10万トークンまでのプロンプト） | $0.10 | $0.50 |
| Claude Sonnet 5.5 | $2 | $10 |
| Claude Opus 5.5 | $4 | $20 |
※ 出典: Claude Platform Docs — Pricing（取得 2026-10）
Haiku 5.5 は 10万トークンを超えるプロンプトでは別の高い単価になるので、「小さいモデルに長いログを丸ごと渡す」構成は注意が要ります。調べる役には対象を絞った依頼を渡し、要約だけを返させる設計が費用面でも合理的です。
実際の消費は /usage で確かめます。Pro・Max・Team・Enterprise の各プランでは、最近の利用のうちスキル・サブエージェント・プラグイン・MCP サーバーごとの割合（帰属の内訳）が表示されます。企業全体の参考値として、公式は Claude Code の費用を「1人あたり1日およそ $13、月 $150〜250、利用者の 90% は1日 $30 未満」と示しています。
※ 出典: Claude Code Docs — Manage costs effectively（取得 2026-10）
記録を残す — 記録ファイルとフック
メインの会話に戻るのは最終報告だけですが、サブエージェントごとの記録はファイルとして残ります。置き場は ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl で、cleanupPeriodDays の設定に従って削除されます（既定では 30日）。
※ 出典: Claude Code Docs — Custom subagents（取得 2026-10）
30日より長く残したい、または自社のログ基盤に送りたい場合は、フックを使います。SubagentStop フックは、サブエージェントが応答を終えたときに動き、入力として agent_id・agent_type・サブエージェント自身の記録ファイルの場所 agent_transcript_path・最終報告のテキスト last_assistant_message を受け取ります。最終報告を読むのに記録ファイルを解析する必要はなく、last_assistant_message をそのままログに書けます。
SubagentStart フックは起動時に動き、サブエージェントの起動を止めることはできませんが、additionalContext で文脈を追加できます。「このプロジェクトでは個人情報を含むファイルを開かない」のような注意書きを、定義ファイルとは別に全サブエージェントへ配る用途に向きます。
| フック | 止められるか | 向く用途 |
|---|---|---|
SubagentStart | 止められない | 起動時に注意書きを追加する |
SubagentStop | 止められる（終了コード 2 または decision: "block"） | 最終報告をログに残す・未完なら続けさせる |
PreToolUse（定義ファイル内） | 止められる（終了コード 2） | 特定のコマンドを実行前に検査する |
※ 出典: Claude Code Docs — Hooks reference（取得 2026-10）
定義ファイルの中に書いた hooks は、そのサブエージェントが動いている間だけ有効です。公式の例では、Bash を渡しつつ PreToolUse フックで SQL の書き込み命令を検出し、終了コード 2 で止める「読み取り専用のデータベース担当」が示されています。本文の「書き換えない」という指示を、仕組みで裏打ちする形です。
注意点として、SubagentStop はプロンプト候補の生成など Claude Code 内部の処理でも発生し、そのときの agent_type は空文字になります。マッチャーを省略したフックはこれらにも反応するので、ログに残すときは agent_type が空の行を除外します。
導入前セルフチェックリスト（10項目）
印刷して、最初のサブエージェントを配る前に確認してください。
- 分けたい仕事を「調べる」「書く」「点検する」のどれかに割り当てたか
- 点検役の
toolsから Edit と Write を外したか - 各定義の
descriptionに「いつ使うか」の一文を書いたか - 依頼文に対象ファイル・期間・出力形式を書く運用にしたか（メインの履歴は見えない）
- メインの会話のモードを確認し、
bypassPermissionsのときはpermissionModeが無視されると理解したか - 特定コマンドの禁止は
disallowedToolsではなくpermissions.denyに書いたか maxTurnsを付け、「部分的」な結果が戻ったときの扱いを決めたか- 単純作業の定義に小さいモデルを指定し、
/usageの内訳を見る担当を決めたか - 入れ子の深さと同時実行数の上限を、最初は小さく設定したか
- 30日で消える記録に頼らず、
SubagentStopフックで最終報告を残す仕組みを用意したか
公式ドキュメント・リソース集
- Custom subagents — 定義ファイルの項目・置き場・権限・上限・記録の正本
- Hooks reference —
SubagentStart・SubagentStopの入力と終了コードの扱い - Manage costs effectively —
/usageの帰属内訳・サブエージェントのモデル選び - Pricing — モデルごとの定価と長いプロンプトの単価
よくある質問
Q. サブエージェントを使うと、Claude Code の利用料は増えますか？
増えます。公式ドキュメントは、サブエージェントの要求がメインの会話と同じ利用枠を消費すると明記しています。増える代わりに、ログやテスト結果のような長い出力をメインの文脈から外せるので、メイン側の肥大化を抑えられます。単純な作業には定義ファイルで小さいモデルを指定し、/usage の内訳でサブエージェントの割合を確かめる運用が基本です。
Q. サブエージェントにだけ強い権限を与えて、メインは安全なままにできますか？
逆です。メインの会話が default・dontAsk・plan のときは、サブエージェントの定義にある permissionMode が使われますが、bypassPermissions を宣言しても無視されます。メインが bypassPermissions・acceptEdits・auto のときは、サブエージェント側の指定に関係なくメインのモードで動きます。親より強い権限は作れません。
Q. サブエージェントが何をしたか、後から確認できますか？
できます。メインの会話には最終報告しか戻りませんが、サブエージェントごとの記録が ~/.claude/projects 配下の subagents フォルダに保存されます。保存期間は cleanupPeriodDays の設定に従い、既定では 30日で削除されます。SubagentStop フックで最終報告のテキストを受け取り、自社のログに残す方法もあります。
Q. サブエージェントはさらにサブエージェントを呼べますか？
呼べます。既定ではメインの会話から数えて 3層まで入れ子にでき、環境変数 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で変えられます。1 にすると入れ子を禁止できます。同時に動かせる数も既定で 20 までと決まっていて、超えると起動に失敗します。業務で使うなら、最初は入れ子なしで組むほうが記録を追いやすくなります。
次の一歩
まず、点検役を1つだけ作ってください。読み取りの道具だけを渡し、いま人が目で確認している下書き（月次の集計・報告書・公開前の記事など）を点検させ、指摘の精度を1週間見ます。点検役が信頼できると分かってから、調べる役と書く役を足すと、どの段で精度が落ちたかを切り分けられます。
どの業務から分けるべきか、社内の権限やログの要件にどう合わせるかを相談したい場合は、お問い合わせから現在の状況をお知らせください。契約前提ではありません。Claude 導入支援の全体像はClaude 導入支援ハブに、既にある Claude Code の運用（CLAUDE.md・hooks・permissions）が安全かを確かめる無料の診断はハーネス健全度診断にまとめています。
更新履歴
- 2026-10-09: 初版公開
関連ページ
- Claude Code を決まった時刻に動かす【2026年9月】— ヘッドレスモードの定期実行と、無人で許す操作の決め方
- Claude Code で作った自動化が止まっていないか確かめる【2026年10月】— 実行ログ・失敗の通知・やり直しの最小セット
- Claude Code の法人導入ガイド【2026年9月】— 管理者が先に決める設定配布・権限・利用上限・監査
- ハーネスエンジニアリング実践ガイド — Claude Code を「育てる」ための 5 つの型とテンプレ
- Claude の「ハーネス」とは何か — エージェントハーネスの正体と、2026 年のみんなの作り方・使い方
- Claude 導入支援ハブ