Claude Code deep-researchコマンドでウェブ横断調査を任せる

/deep-researchはClaude Codeにバンドルされたdynamic workflowです。1つの質問から複数の角度でWeb検索を広げ、見つけた出典を相互にクロスチェックし、各主張を投票で判定して、引用付きのレポートを1本だけ会話に返します。実行はバックグラウンドなので、調査中もセッションは空いたままです。

この記事は、実行前に引っかかりやすい点(動かない環境・承認プロンプト)と、走り出してからの扱い(進捗の見方・止めた後の再開・コスト)を、v2.1.285で確認した内容を交えて書きます。

まず動かす — 実行例と進捗の見方

引数に調査したい質問を渡すだけです。

/deep-research Node.jsのパーミッションモデルはv20からv22でどう変わったか

検証エージェントがレート制限やAPIエラーで判定できなかった主張は、「反証された」ではなく「未検証」として報告されます。レポートに未検証の主張が混じっていても、それは調べた結果として否定されたわけではなく、確認が終わらなかっただけです。重要な主張は、その部分だけ狭い質問にして走らせ直すと確かめられます。

動かないときの切り分け

/deep-researchはWebSearchツールが使えることを前提にしています。dynamic workflow自体が使える環境と、/deep-researchが使える環境は一致しません。

コマンド自体が見当たらないときは、次の順に確認します。

• Proプラン: /configの「Dynamic workflows」の行が有効か確認します。Proでは自分でオンにする必要があります
• 無料プラン: dynamic workflowは有料プランが前提です
• 無効化設定: /configでオフにしている、~/.claude/settings.jsonに"disableWorkflows": trueがある、環境変数CLAUDE_CODE_DISABLE_WORKFLOWS=1がある、のいずれでもバンドルのワークフローコマンドは使えなくなります。組織の管理設定で無効にされている場合も同じです

手元のv2.1.285では、claude --helpが--safe-modeについて「workflows」を含む一連のカスタマイズをすべて無効にして起動すると表示しました。ワークフローが出ないときにこのフラグで起動していないかも見ておきます。

承認プロンプトは権限モードで変わる

実行前の承認は、権限モードによって出るかどうかが違います。

デスクトップアプリでは、ワークフロー名・フェーズ一覧・トークン使用の注意を載せた承認カードが出て、Once・Always・Denyから選びます。進捗はバックグラウンドタスクのサイドペインに表示されます。

最後の行には注意が要ります。claude -pやAgent SDKでは承認プロンプトを出さない代わりに、Workflowツールの呼び出しが通常の権限評価にかかります。denyルールやaskルール、dontAskモードがそのまま効きます。そのため許可ルールにWorkflow(個別ならWorkflow(<名前>))を入れるか、Autoモード・Bypass permissions・PreToolUseフックのいずれかで通す必要があります。

/effort ultracodeをオンにしたセッションでは、Autoモードの初回承認が出なくなります。ultracodeをオンにした時点で大きな実行に同意した扱いになるためで、Large workflowの警告も出なくなります。省かれるのはAutoモードの初回承認だけで、Manualなど他のモードの承認はそのまま出ます。

サブエージェントの権限モードは、ワークフロー固有の指定ではなくサブエージェント共通の規則で決まります。メインの会話がAuto・acceptEdits・Bypass permissionsならサブエージェントも同じモードで動き、それ以外では各エージェントの定義が優先されます。許可リストに無いシェルコマンドやMCPツールは途中でも確認を求められるため、長い調査を止めたくなければ必要なツールを先に許可ルールへ入れておきます。

バージョンごとの変更点

更新履歴に載っている/deep-researchの変更は4件です。特に自動起動の廃止は、コストの発生源を変えた変更です。

重い調査が意図しないタイミングで始まらなくなったぶん、コストの発生源はユーザー自身の操作に絞られます。

コストを見積もる

エージェントを多数走らせるので、同じ質問を会話で進めるより消費トークンは増えます。実行は契約プランの使用量とレート制限に数えられます。目安になる数字は次のとおりです。

同じプロンプトの接頭辞を共有するエージェントは、最初の1体がキャッシュを作れるよう最大5秒遅れて始まるのが既定です。並列で走らせても、後続はキャッシュ済みの接頭辞を読み直せる設計になっています。

まず狭い質問で小さく試し、/workflowsでトークン消費を見てから対象を広げる、という進め方が公式にも示されています。実行中はいつでも止められ、通常は完了済みの作業を失いません。エージェントの目安は/configの「Dynamic workflow size」でsmall(5未満)・medium(10未満)・large(50未満)・unrestrictedから選べます。これは助言で、上限ではありません。v2.1.219以降は、設定ファイルのworkflowSizeGuidelineキーでも目安を指定できます。どれかの設定ファイルにこのキーがあると、/configの「Dynamic workflow size」の行は隠れます。自分でサイズを選ぶと、そのエージェント数が25体の警告しきい値の代わりになります。

検索そのものにも上限があります。1セッションで呼べるWebSearchは最大200回で、メインの会話と生成した全サブエージェントの合計です。並列の調査が使う検索も同じ枠に数えられます。詳しくはClaude Codeのセッション検索上限にあります。

サブスクリプションでは、エージェントが使用量の上限に当たると実行は失敗せず、リセットまで待って自動で続きます(v2.1.271以降)。ただし待つのは、対話セッションでclaude.aiにサインインしていてautoContinueAtUsageLimitがオンで、24時間以内にリセットされ、その実行の待機がまだ2回に達していない場合に限られます。3回目に上限へ当たると、エージェントは失敗します。claude -p、バックグラウンドセッション、Remote Controlなどでは待たずにエージェントが失敗します。

途中で止めたら何が再実行されるか

/workflowsの進捗画面には、実行を操作するキーがあります。

止めた実行を再開すると、Claude Codeはエージェントが始まった順に再生します。完了済みのエージェントは保存された結果をそのまま返しますが、失敗したエージェントとそれ以降に始まったエージェントは、完了していたものも含めて再実行されます。A・B・C・Dの順に始まってBが失敗したなら、再開時にAは再利用され、B・C・Dが走り直します。特定のエージェントをxで個別に止めた場合も失敗として数えられます。

実行全体を止めた場合は、止めた時点で動いていたエージェントが最初からやり直しになるだけで、失敗には数えられません。前回の実行とプロンプトが変わった最初のエージェントも、それ以降のエージェントとともに再実行されます。なおpは一時停止した実行を再開するキーです。停止した実行を戻すには、同じスクリプトでワークフローを再起動するようClaudeに頼みます。

再開できるのは同じセッションの中です。セッションを離れたときの扱いは、離れ方で変わります。

• セッションをバックグラウンドに回す: 同じ規則で再生され、バックグラウンドセッションで続きます
• 実行中に終了する: agent viewがオンなら、終了ダイアログにMove to background and exitが出ます。これを選ぶと実行は同じ形で持ち越されます
• Exit and stop tasksを選ぶ、またはこの選択肢が出ない: 実行はセッションとともに止まります。保存結果は~/.claude/projects/のそのセッションのディレクトリに残るため、claude --resumeで戻ってClaudeにワークフローの再起動を頼むと、保存済みの結果を再生できます
• 新しいセッションから始める: Claudeには再起動できる前の実行がなく、新しい実行として最初からやり直します

保存された結果が見つからないまま再起動を頼むと、実行は自動でやり直されずnothing to resumeエラーで失敗します。その場合はClaudeに、新しい実行として始め直すよう頼みます。クラウドセッションでは、結果がセッションの会話履歴と一緒に保存されるため、VMが回収されたあとで開き直しても、完了済みのエージェントは保存結果を返します。

実行中にできないこと

実行中に追加の指示を挟むことはできません。途中で人が判断したいときは、調査を段階に分け、段階ごとに別のワークフローとして走らせます。

ワークフロー自体はファイルやシェルに直接触りません。検索・取得・読み込みは各サブエージェントが担い、ワークフローは調整役です。

使い分けと関連する記事

/deep-researchは、Claude Codeのセッション内でWeb上の出典を多角的に集めたいときのコマンドです。コードベースの調査や移行のようにファイルを触る作業は、自分の言葉で「ワークフローで」と頼むかultracodeを含めて依頼すると、Claudeが専用のスクリプトを書きます。

Claude Codeのdynamic workflow全般とSkillsの仕組みはClaude Code Skills完全ガイド、他のスラッシュコマンドとの並びはClaude Codeスラッシュコマンド一覧にあります。claude.ai側のResearch機能は別の仕組みで、使い方はClaudeリサーチの使い方にまとめています。

まとめ

/deep-researchが動くかどうかは、プランよりも環境のWebSearch対応で決まることが多く、Bedrockでは使えません。走らせる前に/workflowsの見方と、止めた後にどこから再実行されるかを知っておくと、コストの見積もりが立てやすくなります。