要約
Claude Code /deep-research の API レート制限は、単に「Verify が重い」というだけの問題ではありません。私のケースでは、多数のエージェントが検索、Fetch、要約、再検証を繰り返し、累積したトークン使用量が最後の Verify 段階で Anthropic API の上限に達しました。
有効だった対策は、全体を一つの大きな並列ジョブとして扱わないことでした。Verify を小さな claim バッチに分け、Fetch と Verify が重ならないようにし、前回失敗した Fetch キャッシュを引きずらない fresh 実行にしたところ、3票検証の品質を保ったまま安定しました。
この記事の内容
この記事で扱う内容
状況：最後の Verify で止まった
Claude Code で /deep-research を使っていたとき、最後の検証、つまり Verify 段階で API レート制限に引っかかりました。前半の調査は進んでいたのに、結果を確認する段階で急に上限超過になった形です。
最初は「Verify が重すぎるのでは」と考えがちです。しかし実際には、Verify そのものだけでなく、それ以前に積み上がった調査量、エージェント数、そしてトークン総量が原因でした。
今回の核心：多数のエージェントが大量のトークンを使い、API 上限を超えました。Verify はその累積コストが表に出た地点に近いです。
なぜレート制限が起きたのか
Anthropic の公式ドキュメントによると、API のレート制限はリクエスト数だけで決まりません。Messages API では RPM、ITPM(input tokens per minute)、OTPM(output tokens per minute) などが見られ、どれか一つでも超えると 429 エラーになり得ます。
| 制限 | 意味 | deep-research で問題になる点 |
|---|---|---|
| RPM | 1分あたりのリクエスト数 | 並列エージェントが増えると急に増える |
| ITPM | 1分あたりの入力トークン数 | 検索結果、Fetch したページ、過去の要約、claim 一覧が入力に入る |
| OTPM | 1分あたりの出力トークン数 | 各エージェントが長い分析や検証メモを出す |
| Acceleration limit | 急激な利用量増加に対する制限 | 広い調査を一気に走らせるとバーストしやすい |
deep-research で起きやすい理由
Claude Code の subagent は、探索結果を別の context window に分離できるため便利です。複雑な調査には大きな利点があります。ただし調査範囲が広がると、同じ構造がトークン使用量を増幅します。
- 複数のサブトピックを並列に調べる。
- 各エージェントが文書、コード、Issue、Web ページを読む。
- 各エージェントが中間要約を作る。
- メインエージェントがそれらを統合する。
- Verify が claim、根拠、矛盾をもう一度確認する。
品質面では良い流れですが、トークン面では高コストです。Verify は軽い最終チェックではなく、既に生成された調査結果をもう一度読む工程になりやすいからです。
queue 方式で分割する
今回効果があったのは、単に「もう一度やって」と頼むことではなく、実行構造そのものを変えることでした。目的は、ピーク並列数と分あたりトークン使用量を同時に下げることです。
実際に変えた実行構造
| 段階 | 以前 | 変更後 | 効果 |
|---|---|---|---|
| Verify | 全 75 claim を parallel で検証 | 3 claim ずつのバッチに分け、順番に await | ピーク 9 同時程度まで上がっていた流れを TPM 上限以下に抑えた |
| Fetch | pipeline 内で中첩 parallel | Search を先に終える barrier の後、Fetch を 4件ずつ順次処理 | Fetch と Verify が重ならなくなった |
| 総量 | claim 25、fetch 15 | claim 18、fetch 12 | 総トークン量を下げた |
| 検証品質 | 広い範囲を一括検証 | 3票検証の品質は維持 | 品質を落とさずボトルネックだけ下げた |
| 実行状態 | 前回失敗した Fetch キャッシュを引きずる可能性 | fresh 実行で再収集 | 失敗状態を持ち越さない |
一番効いたのは、Verify を 75件の一括並列検証から 3 claim 単位の順次バッチに変えたことです。検証品質を下げたのではなく、検証が一瞬に集中する形を細かく分けました。Search barrier も重要でした。Fetch と Verify が同時に走らないため、トークン予算を奪い合わなくなります。
そのまま使える依頼文
次に大きな /deep-research を動かすなら、最初から次のように依頼します。
/deep-research を実行するが、全体を queue 方式の pipeline に分割して進めてください。
ルール:
1. Verify は全 claim を一括 parallel で検証しない。3 claim ずつバッチ化し、各バッチを順番に await する。
2. Fetch は pipeline 内の中첩 parallel として実行しない。
3. Search を先に完了し、その後 Fetch を 4件ずつ順次処理する。
4. Fetch と Verify が重ならないように barrier を置く。
5. 必要なら総量を減らす。例: claim 25→18、fetch 15→12。ただし中心となる3票検証品質は維持する。
6. 前回 Fetch が失敗している場合は fresh 実行にし、失敗キャッシュを引きずらない。
7. トークン使用量が跳ねそうなら停止し、現在の queue 状態を報告する。実際に詰まる場面と対策
ケース1. Verify で 429 または rate limit が出る
同じ形で再試行するより、現在までの結果を短く圧縮し、残りの claim を小さなバッチに分けて検証する方が安全です。
現在までの調査結果を15行以内に圧縮してください。
残りの Verify を 3 claim ずつのバッチに分けてください。
重要度の高いバッチから検証し、各バッチ後に queue 状態を報告してください。ケース2. Fetch と Verify が同時に走る
情報収集と検証が同時に走ると、入力トークンと出力トークンの両方が跳ねます。Search、Fetch、Verify の間に barrier を置くと安定しやすくなります。
ケース3. 失敗した Fetch キャッシュを引きずる
前回 Fetch 段階で失敗した場合、中途半端な状態から再開するより fresh 実行で取り直した方がよいことがあります。特に rate limit 境界で失敗した場合は、状態をきれいにする価値があります。
結論
Claude Code /deep-research が Verify 段階で API レート制限に当たった場合、原因は一つの Verify 呼び出しだけではないことが多いです。多数のエージェント、多数の Fetch、長い中間要約、そして最後の一括検証が重なって、瞬間的なトークン使用量が跳ねます。
大きな調査では、最初から queue 設計にするのが安全です。Verify は小さなバッチにし、Fetch と Verify を分離し、総量を少し減らし、前回失敗した場合は fresh 実行にする。少し遅くなっても、最後に TPM 上限で止まるよりはずっと実用的です。
参考文献
- Anthropic API Docs: Rate limits
- Claude Code Docs: Create custom subagents
- Claude Code Docs: Troubleshooting performance and stability
- Claude Code Docs: Slash commands