Claude Code のサブエージェントを使ってみたいが、結局どの仕事を切り出すべきか分からない。並列で投げれば速くなると思ったのに、戻ってきた要約が薄い。レビュー役を分けたらかえってログが増えて読みにくい。この記事は、そういう段階に入った人向けです。
すでに Claude Code を触っている人ほど、次の壁に当たります。
- 調査ログが main 会話を埋めて、実装時に文脈が濁る
- 小さい修正までサブエージェントに投げて、逆に遅くなる
- reviewer や debugger を作ったが、権限が強すぎて境界が曖昧
- チームで共有したいのに、どこまで project 管理に載せるべきか決めきれない
この記事では、Claude Code サブエージェントを「便利機能」ではなく運用境界として使う方法に絞って解説します。Claude Code 全体の導入順を先に整理したいなら Claude Code の使い方 実践ガイド、CLAUDE.md 側の設計を詰めたいなら CLAUDE.md の書き方 設計パターン集、組織ルールと権限境界を先に決めたいなら AIコーディングツールの社内ガイドライン を先に読む方が順番としては正しいです。
先に結論: サブエージェントは「速くする道具」ではなく「main 会話を汚さない道具」
Claude Code の公式ドキュメントでは、subagents は「大量の検索結果やログ、使い捨てのファイル内容を main 会話に持ち込まないための独立コンテキスト」として説明されています。ここを外すと、運用はかなり崩れます。
私の理解では、サブエージェントの価値は主に4つです。
- コンテキスト分離: 調査や検証のノイズを main 会話に残さない
- 役割分担: reviewer、debugger、researcher のように期待動作を固定する
- 権限制御: 読み取り専用、特定ツール限定、isolated worktree など境界を切る
- コスト制御: 調査タスクだけ Haiku に寄せる、といったモデル分離ができる
逆に言うと、次の用途には向きません。
- 仕様相談をしながら少しずつ方向修正したい作業
- 実装、テスト、再修正を同じ文脈で何度も往復する作業
- 1ファイルだけの軽微な変更
- 途中経過を細かく人間が見ながら進める作業
「main 会話でやるか、subagent に切るか」の基準が曖昧なまま数だけ増やすと、AI ワークフローはだいたい失敗します。概念整理から入りたい場合は、より上位の設計論として マルチエージェントオーケストレーション 4パターン解説 も補助線になります。
まず main 会話とサブエージェントの境界を決める
Claude Code の docs でも、subagent は「self-contained で summary を返せる仕事」に向く一方、強い共有文脈や頻繁な往復が必要な作業は main conversation の方が向くと整理されています。実務では、この線引きが最重要です。
main 会話でやるべき仕事
- 要件がまだ固まっていない
- 実装しながら方針を変える
- 変更規模が小さい
- 途中の試行錯誤そのものを会話に残したい
たとえば「このコンポーネントだけ 2 箇所修正して、終わったら build を流す」のような仕事は main 会話の方が速いです。サブエージェントを起こすコストの方が高くつきます。
サブエージェントに切るべき仕事
- 調査結果の生ログを main 会話に残したくない
- reviewer のように期待動作を固定したい
- 特定ツールだけ許可したい
- 独立タスクを並列で投げたい
- 危険な変更を isolated worktree に閉じ込めたい
私が現場で一番効いたのは、調査役と実装役を分ける運用です。main 会話でいきなり広い調査をさせると、会話履歴がすぐ汚れます。そこで researcher に「認証周りだけ調べて、関係ファイルと論点だけ返して」と投げると、main 側には要点だけが残ります。これだけで実装時の精度がかなり安定しました。
最初に作るべきサブエージェントは 3 つだけ
/agents 画面を開くと色々作りたくなりますが、最初から増やしすぎない方がよいです。私なら、初期構成は次の3つに絞ります。
1. researcher
用途:
- ファイル探索
- 根拠集め
- 差分の影響範囲調査
設定方針:
- Read / Grep / Glob 中心
- model は Haiku か Sonnet
- 返却フォーマットを「要点3つ + 参照ファイル」に固定
これは built-in の Explore に近いですが、自分のコードベースや業務に合わせた調査観点を足せるのが custom subagent の利点です。
2. reviewer
用途:
- 実装後レビュー
- セキュリティ観点の確認
- テスト不足の洗い出し
設定方針:
- 原則 read-only
use proactively after code changesのように description を明確化- 優先順位付きで findings を返すよう指示
ここで write 権限まで与えると、reviewer が reviewer ではなく second implementer になります。最初は読み取り専用で十分です。
3. debugger
用途:
- failing test の切り分け
- エラーログ解釈
- 再現条件の整理
設定方針:
- Read + Bash を許可
- 必要なら worktree isolation
- 「原因仮説、再現手順、修正案」を分けて返す
この3つがあれば、調査、検証、レビューの大半を main 会話から分離できます。逆に最初から 8 体以上作ると、description が被って自動委譲が不安定になります。
設定は /agents から始めればよいが、重要なのは frontmatter の設計
Claude Code の subagent は Markdown ファイルの YAML frontmatter で定義できます。docs 上でも /agents が推奨されていますが、実務上重要なのは UI そのものより 何を frontmatter に固定するか です。
---
name: code-reviewer
description: コード変更後に自動委譲する read-only reviewer。セキュリティ、回帰、テスト不足を優先順位付きで指摘する
tools: Read, Glob, Grep
model: sonnet
permissionMode: default
maxTurns: 8
---
あなたはコードレビュアーです。実装は行わず、重大度順に問題点を返してください。docs で明示されている主要フィールドは name、description、tools、disallowedTools、model、permissionMode、skills、memory、background、isolation などです。ここで雑に作ると、あとでほぼ確実に運用事故になります。
特に重要なのは description
Claude は description を見て「いつ委譲するか」を判断します。つまり description が曖昧だと、良いプロンプト本文を書いても自動委譲がぶれます。
悪い例:
コードを手伝うエージェントデバッグもレビューもできる万能エージェント
良い例:
変更後に自動で呼ぶ read-only reviewer。セキュリティ、回帰、テスト不足を確認する失敗したテストの再現と原因切り分けに使う debugger。原因仮説と修正案を分けて返す
description には「いつ呼ぶか」と「何を返すか」を含めるべきです。
スコープは user より project を先に考える
Claude Code の docs では、subagent の配置先として managed settings、CLI flag、.claude/agents/、~/.claude/agents/、plugin が整理されています。個人利用だけ見ると user scope が便利ですが、チーム運用では project scope を先に検討した方がよいです。
~/.claude/agents/ が向くケース
- どのリポジトリでも使う reviewer を持ちたい
- 自分だけの調査用エージェントを作りたい
- まだチーム標準にするには早い
.claude/agents/ が向くケース
- リポジトリ固有の制約を prompt に埋め込みたい
- チームで改善しながら共有したい
- CI、権限、ディレクトリ構成などプロジェクト前提が強い
私なら、その repo でしか意味がない reviewer / debugger は project に置く、汎用 researcher は user に置く、という切り方をします。最初から全部 user 配下に置くと、別プロジェクトに誤適用しやすいです。
速くしたいなら「並列化」より「summary の粒度」を設計する
subagents = parallel と考えがちですが、実際にはここが一番危ないです。独立していない仕事を並列にすると、統合フェーズで破綻します。これは上位のオーケストレーション記事でも触れましたが、Claude Code の subagents 運用ではさらに 返り値の粒度 が重要です。
悪い例:
- 調査役3体に全部長文で返させる
- 戻り値に生ログを含める
- どのファイルを見たか分からない要約を返させる
良い例:
- 各 subagent に担当領域を固定する
要点3つ / 根拠ファイル / 次アクション1つで返させる- 必要なときだけ main 会話から追加質問する
たとえば私は、フロント、認証、SEO の3領域調査を並列で投げるとき、返却形式を次のように固定します。
- 今の実装を 3 行で要約
- 変更が必要なファイルを列挙
- main 会話に持ち帰る判断ポイントを 2 つだけ返す
これをやるだけで、並列化の効果が初めて出ます。単に「調べて」と言うだけでは、速くなる代わりに整理コストが main 側へ戻ってきます。
reviewer を分けるなら、書き込み禁止と worktree 分離を先に決める
運用で意外と効くのが reviewer 役の設計です。Claude Code には built-in の general-purpose もありますが、レビュー役を切るなら 何をさせないか を先に決めるべきです。
docs では subagent ごとに tools 制限や permission mode を設定でき、isolation: worktree を使うと一時的な git worktree 上で動かせます。これは「レビューしつつ勝手に直す」「危険な修正を main 作業ディレクトリに混ぜる」を避けるのに有効です。
私の基準はこうです。
- reviewer: 原則 read-only
- debugger: Bash は許可、Write は必要時のみ
- refactorer: 書き込みあり。ただし
isolation: worktreeを優先
特にチーム利用では、「subagent ごとに permissionMode を変えられるから安全」とは限りません。設定が repo に共有される以上、誰がどの subagent を使って何を変更してよいか は社内ルールとセットで決める必要があります。この論点は AIコーディングツールの社内ガイドライン と接続します。
background、memory、skills は便利だが、全部載せしない方がよい
2026年4月時点の docs では、subagent に skills の事前ロード、persistent memory、background 実行、effort 指定まで設定できます。機能としては強いですが、最初から全部使うと設計が不透明になります。
background が向くケース
- 長い調査を横で走らせたい
- main 会話は別の軽作業を続けたい
- 返却を急がず、まとまった summary を待てる
memory が向くケース
- reviewer に継続的なコードベース癖を学ばせたい
- recurring な監査観点を蓄積したい
skills が向くケース
- 毎回同じワークフローを読み込ませたい
- subagent の system prompt を短く保ちたい
ただし、subagent は parent conversation の skills を継承しません。つまり「main 会話では使えていた skill が subagent では急に効かない」という事故が起きます。ここを理解せずに使うと、再現性が落ちます。
私なら初期段階ではこうします。
- background: researcher だけ
- memory: まず off
- skills: reviewer など再利用価値が高いものだけ
便利そうだから全部 enable する、は運用上ほぼ悪手です。
よくある失敗は 5 つ
サブエージェント運用でハマりやすい点を、実務目線で先に潰しておきます。
1. 自動委譲の条件が広すぎる
description が広すぎると、Claude が意図しないタイミングで subagent を呼びます。help with code のような文言は避けた方がよいです。
2. 返却フォーマットを決めていない
summary の粒度が毎回変わると、main 会話側の扱いが安定しません。特に reviewer は severity 順、researcher は論点順、のように固定した方がよいです。
3. 小さい作業まで subagent に投げる
1ファイルの typo 修正のような仕事に subagent を使うと、起動コストだけ増えます。速度改善ではなく習慣で切ると失敗します。
4. nested delegation 前提で設計する
Claude Code の docs でも、subagents cannot spawn other subagents と明記されています。深い階層化が前提なら、subagent ではなく agent teams や別のワークフロー設計を検討すべきです。
5. isolated worktree を使わずに危険な変更を混ぜる
refactor や大規模置換を subagent に任せるなら、main 作業ディレクトリと分けた方が安全です。とくに Bash と Write を同時に許可する subagent は、worktree 隔離を第一候補にした方がよいです。
実務で効いた最小運用ルール
最後に、私ならチーム導入時にこの4つだけは固定します。
- read-only reviewer を project 配下に 1 つ置く
- researcher の返却フォーマットを固定する
- 書き込み可能 subagent には用途を明示し、必要なら
isolation: worktreeを使う - main 会話で持つべき仕事と切り出す仕事を README か CLAUDE.md に短く書く
ここまでやると、subagent は「たまに使う裏機能」ではなく、再現性のあるチーム運用に変わります。逆に、description と権限設計を曖昧にしたまま増やすと、便利さよりも観測不能性が勝ちます。
まとめ
Claude Code のサブエージェントは、単に AI を複数動かす機能ではありません。main 会話の文脈を守りながら、役割・権限・コストを切り分けるための運用境界です。
私なら次の順で導入します。
- main 会話で持つ仕事と切り出す仕事を分ける
- researcher / reviewer / debugger の3体だけ作る
- description と返却フォーマットを先に固定する
- 危険な変更では tools 制限と worktree isolation を使う
- 並列化は最後に足す
この順番を飛ばすと、サブエージェントは高機能なわりに成果が安定しません。逆にここを押さえると、Claude Code の運用品質はかなり上がります。
一次情報としては、Claude Code docs の Create custom subagents と Settings / managed configuration 周辺のドキュメント を先に読むのが確実です。