AIコーディングで「どのモードで動かす?」を迷わない — Claude Code Agent 判断軸

「これ、Task でいいんだっけ。それとも Agent Team？　いや、メインで書いた方が速い気もする……」

Claude Code Agent を本格的に使い始めると、コードを書く前に毎回ここで2秒くらい固まります（正直、1日10回はやっている）。Task tool で投げるか、TeamCreate でチームを組むか、それともメインスレッドのまま書き切るか――選択肢が3つあるのに判断軸が曖昧なまま、なんとなく Task に流していた時期がありました。

playpark の Skills リポジトリでは70本以上の skill を運用していて、当初は「並列で速くなりそうだから Task でいいか」くらいの軽さで分けていたのですが、これがじわじわ効いてくるんですよね。メインで書けば数秒で済む処理に subagent を起動して10秒以上待たされたり（待ってる間にコーヒーを淹れに行くには中途半端な長さ）、本当に並列協調が必要な調査を素朴な Task 並列で組んでしまって途中で身動きが取れなくなったり、という地味なミスが積み上がっていきます。

本記事では、その後に整理した「いつ Task / いつ Agent Team / いつメインスレッド」の判断軸と、各パターンのレイテンシ・コンテキスト消費の目安をまとめます。Claude Code Agent の使い方・設定・運用感をひと通り掴みたい方向けです。

この記事で学べること

• Claude Code Agent の3つの実行モード（メイン / Task subagent / Agent Team）の違い
• 「分割可能か」「副作用を伴うか」「コンテキストを汚したくないか」の3問判断フロー
• 各モードのレイテンシ・コンテキスト消費の体感目安
• playpark Skills の実例（ブログ公開・バグ調査・コード監査等）でどう使い分けているか

前提：Agent は「並列で速くなる道具」ではない

「Task や Agent Team を使うと並列で速くなるって聞くけど、実際どうなの？」というのが、たぶん最初に湧く疑問だと思います。先に結論を置いておきます：速くなる効果はあるけど、それが第一目的ではないんですよね。

Task tool を使う第一目的は、並列実行ではなく context isolation です。並列はその副産物（速さに釣られて使い始めると、本来の効能を見落とすわけです）。

メインスレッドで Read / Grep / WebFetch を連発すると、その全ログがメインのコンテキストウィンドウを食います。一方 Task で subagent を呼ぶと、subagent 側のコンテキストで探索が走り、メインに戻るのは 最終出力だけ。途中の grep ヒット数千行はメインの目に触れません。

つまり Task は「メインのコンテキストを汚さずに、別プロセスに探索や生成を任せたい時」の道具です。並列で走らせるかは別の話で、Task を1つだけ呼ぶケースも普通にあります（むしろ最初はこのパターンが多い）。

この前提を踏まえて、3つの実行モードを並べます。

3つの実行モードの違い

モード	仕組み	通信	向いている問題
メインスレッド	通常の tool call	なし（メインで完結）	短い検索 / 単一ファイル編集 / 既知の修正
Task subagent	Task tool で別プロセス起動	親→子→親（一方通行）	探索 heavy / 分割可能な並列タスク
Agent Team	TeamCreate + SendMessage（要実験フラグ）	メンバー間で双方向 DM	相互依存のある探索（バグ調査・監査）

Task と Agent Team の本質的な違いは 通信方向 です。Task は依頼して結果を受け取るまで一直線。Agent Team は走っている最中にメンバー同士でメッセージを送り合えるので、A の発見を受けて B が調査方向を変える、という動的な連携ができます。

Note: Agent Team（TeamCreate / SendMessage）は2026年2月時点で実験的機能（CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が必要）です。将来的に GA になる可能性があります。

Agent Team の協調設計の詳細は別記事で扱っているので、本記事は どれを選ぶか に振り切ります。

判断フロー：3問で決まる

毎回ゼロから考えると消耗するので、判断を3問のフローに圧縮しました。

Q1: 分割できるか

タスクが「単一ファイルの単一修正」「既知のパターンの直し」のような 小さくて分割不要な作業 なら、subagent の起動コストのほうが高くつきます。メインで素直に書きます（小回りが効く方が、最後は速い）。

判断の目安は、対象ファイル数と修正手順の数です。3ファイル以下・3手順以下なら、まず分割しない。

Q2: 探索ログをメインに残したいか

「ユーザーと対話しながら探索したい」「途中の grep 結果を見て次の判断をしたい」場合、subagent に隔離してしまうとメインから経過が見えなくなります。教育的な探索や、ユーザーの意思決定が挟まる調査はメインで走らせます。

逆に「結果だけ欲しい」「途中のヒット数十件はメインに残したくない」なら、subagent に隔離します。これが Task の本来の用途です。

Q3: 途中で他の調査ラインの結果を参照するか

ここが Task と Agent Team の分かれ目です。

• 独立して走り切れる → Task を並列で複数呼ぶ。例: 3つの異なるディレクトリで型エラーを集計する
• A の発見が B の方向を変える → Agent Team。例: ログで遅延を発見したら、コード担当が同時刻のデプロイ差分を見に行く

「並列調査だから Agent Team」ではなく、「途中で互いに影響し合うかどうか」で決めます。互いに干渉しない並列なら Task で十分で、Team を組む分の管理コスト（誰が誰に何を送るかの設計）が浮きます。

レイテンシとコンテキスト消費の目安

選択を体感で支えるために、3モードの実コストを並べておきます。数値は playpark の Skills 運用での体感値で、タスクの中身によって幅があります（厳密な計測ではなく、運用判断の目安として読んでください）。

モード	起動オーバーヘッド	メインのコンテキスト消費	並列可否
メイン	なし	tool call ごとに直接消費	×
Task subagent	数秒〜十数秒	最終出力分のみ	○（同一 message 内で複数呼び出し）
Agent Team	チーム作成 + メンバー spawn でさらに数秒乗る	メンバー数 × 起動コスト分はメインに乗らない	○（メンバー間で双方向通信）

ここから読み取れる運用ルールは2つです。

1. 小タスクに subagent を使うとレイテンシで負ける。1秒で終わる grep に Task を使うと、起動オーバーヘッドのほうが長くなります（手で書いた方が速かった、をやりがち）
2. 大きい探索ほど subagent の効果が大きい。メインで grep 10回・WebFetch 5回をやると context が一気に膨らむ。これを1つの Task に押し込めて summary だけ返してもらうと、メインの寿命が伸びます（=セッションを途中で畳まずに済む）

「速くなる」より「コンテキストが長持ちする」が Task / Agent の主効果、というのが運用してみての結論でした。

playpark Skills での使い分け実例

抽象論だけだと判断がブレるので、実際にどう振り分けているかを並べます。

メインスレッドのまま書くもの

• コミットメッセージ生成：差分を読んでメッセージを整える。範囲が小さく、判断がそのままユーザーに見えるべき
• 画像リサイズ：vips を1コマンド叩くだけ（ここに subagent を挟むのは、コンビニのおにぎりを買うのにタクシーを呼ぶ感じ）
• 単一ファイルの設定更新：1ファイル取得して上書き

ここに subagent を入れると、得られるものより起動コストのほうが高くなります。

Task subagent に切り出すもの

• ブログ公開スキル：記事生成・voice 適用・タイトル整形を 直列の4ゲート として subagent 連結。1つ1つは独立タスクで、途中の探索ログをメインに残す必要がない
• 実装キックオフスキル：実装フェーズを Task に隔離して、メインを軽く保つ
• 情報収集スキルの並列検索：6カテゴリ並列で WebFetch する。各検索は独立で、結果 summary だけ欲しい

「直列の品質ゲート」と「独立並列の探索」が Task の主戦場です。

Agent Team を組むもの

• バグ調査スキル：仮説を3つ立てて並列調査するが、A 線が原因を発見したら他の線を打ち切りたい。SendMessage で「root cause found」を流せる
• コード監査スキル：security / performance / architecture の3観点で、ある観点の発見が他の観点に波及することがある
• インシデント対応スキル：log / code / config の異常が相互依存

共通しているのは 動的な方向転換が要る探索 です。これらを Task の素朴な並列で組むと、A 線が答えを見つけても B 線が無駄に走り続ける、という事態になります。

やりがちな失敗

最後に、判断フローに乗せきれずに何度かやらかしたパターンを残しておきます。同じ落とし穴を踏まないために。

失敗1: 短いタスクに subagent を使う

「念のため Task でやっておくか」の積み重ねで、レイテンシが地味に伸びます。1分で終わる grep に Task を使うと、起動オーバーヘッドで体感がもっさりします（速くしたつもりが、ちょっと遅くなる、という最も悲しいパターン）。Q1 で「分割不要」が出たらメインで書く、を徹底します。

失敗2: 干渉する並列を Task で組む

「3つの仮説を Task 並列で投げれば速い」と思って組んだら、A 線が答えを出した後も B / C が止まらない。動的な方向転換が必要だったので、本来は Agent Team が正解でした（B / C はずっと別世界で答えを探し続けている）。Q3 で「途中で参照する必要があるか」を聞くのはこの失敗の予防策です。

失敗3: Agent Team を「とりあえず並列」で使う

逆方向の失敗。並列実行が目的なら Task で十分なのに、TeamCreate を使って team_name の管理 / SendMessage の hub-and-spoke 設計まで書いて、複雑度だけが増す（道具の格好良さで選んでいる）。動的協調が要らないなら Team は overkill です。

失敗4: dispatch プロンプトの仕様不足

これは subagent を使うと決めた後の話ですが、Objective / Output format / Tools / Boundary / Token cap の5要素を書かないと、せっかく分けても期待した結果が返ってこない。subagent 運用の5要素ルールに詳しく書いています。

まとめ

Claude Code Agent の3モード使い分けは、3問で決まります。

1. 分割できるか？ → No ならメイン
2. 探索ログをメインに残したいか？ → Yes ならメイン
3. 途中で他の調査ラインを参照するか？ → No なら Task / Yes なら Agent Team

体感で覚えるなら、メインは「短くて見せたい作業」、Task は「直列ゲートと独立並列」、Agent Team は「動的協調が要る探索」 です。

playpark では現在、Skills を新しく作る時にこの3問をテンプレに入れていて、判断を都度ゼロから考えなくて済むようになりました（=冒頭の「2秒固まる」が消えた）。同じように Agent をどう組むか毎回迷っている方の足場になれば嬉しいです。