環境変数

CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS

同一プレフィックスを持つ複数のワークフローエージェントにおいて、プロンプトキャッシュを共有するために、他のエージェントの初回レスポンス開始を待機する最大時間をミリ秒単位で指定します。

使い方・用途

  • 複数のエージェントが同じキャッシュプレフィックス（同一のモデル、エフォートレベル、ツール、スキーマなど）を共有して同時に起動された際、不要なキャッシュミスを防ぐために利用します。
  • デフォルト値は5000（5秒）で、この時間だけエージェントの処理開始をずらすことで全体のトークンコストと待機時間を削減します。
  • 待機機能を無効化したい場合は値を0に設定し、環境変数 DISABLE_PROMPT_CACHING が設定されている場合もこの待機は機能しません。
英語原文(公式ドキュメントより)

Upper bound in milliseconds on how long a workflow agent waits for a same-prefix sibling's first response to begin before sending its own first request. When a fan-out starts several agents that share a prompt-cache prefix, Claude Code holds all but the first agent for up to this long so the rest read the cached prefix instead of each processing it uncached. Default 5000. Set to 0 to disable the wait. When DISABLE_PROMPT_CACHING is set, agents never wait. Requires Claude Code v2.1.229 or later

関連する変更履歴

v2.1.229(1件)

Improved
ワークフローの並列展開（fan-out）処理において、同じプロンプト接頭辞を持つ兄弟エージェントの起動を千鳥足（stagger）状にわずかに遅らせて実行することで、後続エージェントがキャッシュされたプロンプトを使用し、トークン料金の重複支払いを防ぐ機能を追加しました（CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0 で無効化可能）。
英語原文を表示
Improved workflow fan-outs to stagger same-prefix sibling agents so subsequent agents read the cached prompt prefix instead of re-paying it (CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0 disables)

変更前

複数の並列エージェントを完全に同時に起動すると、キャッシュが生成される前にすべてのリクエストが API に到達するため、全員が同じ長大プロンプトの読み込み料金をフルで支払う必要がありました。

変更後

1人目の起動からごく僅かな時間差を設けて次を起動させるため、2人目以降は1人目が構築したプロンプトキャッシュを再利用し、料金を大幅に削減できます。

ユーザーへの恩恵

並列処理を伴う大規模なワークフローを実行する際の、API トークン消費コストを大幅に抑えることができます。

関連ドキュメント