エージェント型トークン爆発：CI/CDにおけるClaudeコードのコスト帰属と予算

エージェントが対話型セッションからCI/CDパイプラインに移行すると、人間によるペース調整メカニズムがなくなり、ReActループはコンテキストを二次関数的に増加させます。プロバイダーからの請求書は、どれだけ費用がかかったかを教えてくれますが、その理由や、開発速度を著しく低下させることなくどこを削減すべきかは教えてくれません。

なぜCI/CDが経済性を変えるのか

対話型AIセッションには、キーボードの前にいる人間という組み込みのペース調整メカニズムがあります。人間はエージェントの出力を読み、次に何をすべきかを決定し、数分ごとに約1つのプロンプトを消費します。このペースは、たとえポリシーによって強制されていなくても、緩やかなレート制限として機能します。

CI/CDパイプラインにはそれがありません。自動PRレビュー用に設定されたエージェントは、通常のコミットトラフィックによって1時間に何百回もトリガーされる可能性があり、その環境にはそれを減速させるものは何もありません。呼び出しごとのコスト自体が増加するため、計算はトリガー頻度が示唆するよりもさらに悪化します。ReActのようなエージェント型フレームワークは、次の推論ステップの前に、すべてのアクションの結果をコンテキストウィンドウに再度追加します。エージェントの実行ごとのトークン消費量は、ステップ数に対しておよそO(n²)で増加します。

.

‍

プロバイダーの請求における盲点

AnthropicとOpenAIのダッシュボードは、先週の火曜日にあなたの組織が消費したトークン数を正確に教えてくれますが、その理由は教えてくれません。プロバイダーはアプリケーションのコンテキストを持たないため、重要な本番データパイプラインと、ジュニアエンジニアの無限ループするサイドプロジェクトを区別できません。どちらも同じように請求されます。

詳細な費用帰属がなければ、財務部門は利用可能な唯一の手段である一律禁止に頼ることになります。AIの使用はレビュー待ちで一時停止され、正当なワークロードも暴走するワークロードと一緒に制限されます。エンジニアリングリーダーは毎月の締め日の連絡を恐れるようになります。根本的な問題は、費用帰属が請求時ではなく取り込み時に行われるべきだということです。請求書が届く頃には、必要だったラベルは失われているからです。

プロバイダーの請求書は「いくら」に答えますが、ゲートウェイで帰属された台帳は「どのリポジトリ、どのパイプライン、どのエージェントステップ、そして何を修正すべきか」に答えます。この違いが、財務上の危機をエンジニアリングのチケットへと変えるのです。

ゲートウェイレベルのメタデータタグ付け

コスト帰属の基盤は、ゲートウェイでの必須タグ付けです。CI/CDパイプラインからのすべてのリクエストは、X-TFY-METADATAヘッダーを介して小さなJSONオブジェクトを挿入し、チーム、リポジトリ、パイプライン、エージェントステップ、および責任のあるコストセンターを識別します。その形式はシンプルで意図的であり、すべてのチームで同じです。

HTTP  ·  すべてのCIリクエストで必須のヘッダー

X-TFY-METADATA: {
  "team":         "payments-platform",
  "repo":         "transaction-service",
  "pipeline":     "pr-security-audit",
  "agent_step":   "step-2-policy-check",
  "cost_center":  "eng-backend",
  "environment":  "production"
}

タグは必須であり、推奨ではありません。タグ付けされていないリクエストは、黙って通過するのではなく、ゲートウェイで拒否されます。これが100%の可観測性を生み出すポリシーです。ダッシュボードに「不明」なバケットは存在しません。なぜなら、それが発生する経路がないからです。実施にかかるコストは1つのCedar/OPAルールですが、実施しない場合のコストは四半期ごとの財務部門からのエスカレーションです。

‍

‍

タグ付けされた状態で、ゲートウェイはすべての呼び出しについて入力、出力、キャッシュされたトークンをカウントし、その結果を現在のプロバイダー料金に基づいて価格設定し、完全な属性付き台帳エントリを書き込みます。コストビューは、ユーザー、モデル、チームごとにすぐに利用でき、「生データダウンロード」オプションを使用すると、カスタムのgroupByフィールド（ユーザー名、モデル名、チーム、またはタグ付けした任意のメタデータキー）でエクスポートできます。すべての費用が明確に紐付けられます。

サーキットブレーカー付きのプロジェクトごとの予算

実施を伴わない可視化は、誰も行動を起こさないダッシュボードに過ぎません。TrueFoundryは、タグ付けによって生成されるすべてのコストセンターに、階層的で数学的に強制力のある予算を割り当てます。予算は、対象、モデル、またはメタデータキーによってスコープが設定された、順序付けられたルールのリストです。予算ルールとレート制限ルールを区別する2つのセマンティクスがあり、これらを正確に理解しておく価値があります。

• 予算追跡は、一致するすべてのルールに対して行われます。リクエストが3つのルールに一致する場合、コストは3つすべてから差し引かれます。階層化された予算 — 10ドルの開発者ごとの予算の上に50ドルのリポジトリごとの予算、さらにその上に500ドルのチーム予算 — はすべて同時に同期されます。
• 許可/ブロックの決定は、最初に一致したルールのみから行われます。ルールは上から下へ評価され、条件が一致した最初のルールが、リクエストを通過させるか拒否するかを決定します。優先度の高いオーバーライドは上部に、デフォルトは下部に配置してください。

予算アラートは、設定可能な4つのしきい値（上限の75%、90%、95%、100%）で発生し、メール、Slackウェブフック、Slackボットの通知チャネルが利用可能です。チェックは、最新の属性付き台帳に対して20分ごとに実行されます。

表1 — 予算しきい値。各しきい値は、予算期間（日/週/月）ごとに1回発生し、次の期間の開始時にリセットされます。アラートは20分ごとにチェックされます。

100%に達した際の動作は、後付けではなく設計の一部です。ゲートウェイは、上限に達した予算を特定し、オペレーターをダッシュボードに誘導する構造化されたエラーを返します。

JSON  ·  ハードキャップでの429応答

{
  "error":      "Budget Exceeded",
  "rule_id":    "transaction-service-daily",
  "detail":     "Repository \"transaction-service\" has exhausted its
                 daily $50 AI budget at 14:32 UTC.",
  "mitigation": "Review pipeline logs for infinite loops or request a
                 quota increase via the platform team.",
  "dashboard":  "https://gateway.example.com/budgets/transaction-service"
}

予算上限に達したパイプラインは、開発者がプラットフォームチームに状況を問い合わせる必要なく、次に何をすべきかを知るべきです。CIランナーは429を標準的なバックオフシグナルとして解釈し、ビルドは混乱した方法でクラッシュするのではなく、実行可能なメッセージとともにきれいに失敗します。

もう一つ知っておくべき動作があります。それは監査モードです。任意のルールで `block_on_budget_exceed: false` を設定すると、追跡とアラートはアクティブなままですが、リクエストは通過させます。これは、ロールアウトの最初の1ヶ月間における適切なデフォルト設定です。シミュレートされた上限に対してアラートが発動するのを確認し、上限を調整してから、強制適用をオンにしてください。監査モードをスキップすると、午前3時にすべてのパイプラインが失敗して怒っているチームに直面することになります。

YAML  ·  階層型予算設定

name: cicd-budget
type: gateway-budget-config
rules:
  - id: "ml-team-override"
    when: { subjects: ["team:ml-engineering"] }
    limit_to: 200
    unit: cost_per_day
    budget_applies_per: ["user"]
  - id: "default-user-daily"
    when: {}
    limit_to: 10
    unit: cost_per_day
    budget_applies_per: ["user"]
  - id: "per-repo-daily"
    when: {}
    limit_to: 50
    unit: cost_per_day
    budget_applies_per: ["metadata.repo"]
    alerts:
      thresholds: [75, 90, 100]
      notification_target:
        - type: slack-webhook
          notification_channel: "ai-budget-alerts"

コスト帰属ダッシュボードの構築

ゲートウェイのメトリクス層に流れるタグ付けされたデータにより、プラットフォームチームは、集計されたノイズを増やすのではなく、所有権に関する疑問に答えるダッシュボードを構築できます。スパイクをじっと見て「誰がこれをやったのか？」と尋ねる代わりに、ダッシュボードはすでに、UTC午前2時にフロントエンドチームがreact-monorepoに新しいエージェントをデプロイし、それが不足している依存関係を幻覚し、400ステップの解決ループに入ったことを教えてくれます。

そのような運用上のコンテキストは、コストを財務問題からエンジニアリング問題へと変えます。最初のコード要約ステップをSonnetからHaikuに切り替えることで、PRレビューの品質に影響を与えることなく、そのステップのコストを80%削減できることがわかれば、変更を行います。運営委員会で予算上限について議論することはありません。TrueFoundryのコスト追跡ビューは、ユーザー、モデル、チームの視点からすぐに利用でき、生データのエクスポートにより、任意のメタデータキーでスライスできます。そのため、リポジトリごと、パイプラインごと、またはエージェントステップごとのビューは、データエンジニアリングプロジェクトではなく、ワンクリックでダウンロードできます。

‍

‍

請求書が届く前の月間支出予測

集計されたタグ付けデータは、予測も容易にします。エージェントワークロードはバースト的であり、定期的な重いCIジョブが請求の大部分を占めるため、単純な移動平均では支出を体系的に過小評価してしまいます。95パーセンタイルが平均の4倍であるワークロードにとって、過去7日間の平均は誤った予測です。

適切なモデルは、リポジトリごと、チームごとに実行されるP95ローリング予測です。P95は、平均値では見過ごされがちなバーストリスクを捉え、月末の支出を予測することで、財務部門が驚く前に予算調整、クォータ引き上げ、または問題のあるパイプラインの停止を行うのに十分なリードタイムを提供します。「驚き」がキーワードです。これは、驚きを生み出さないように設計された予測なのです。実際、私たちが測定したワークロードにおいて、7日間のP95は実際の月末支出を8～12%の範囲で追跡しており、行動を起こすのに十分な精度であり、移動平均の代替案よりもはるかに優れています。

実際の例：8,400ドル → 800ドル未満

50人規模のエンジニア組織が、すべてのプルリクエストで実行される3段階のClaudeコードレビューエージェントを構築しました。(1)差分を要約する、(2)MCPドキュメントサーバーを介してセキュリティポリシーに対して差分をレビューする、(3)コード変更を提案する、というものです。合理的なアーキテクチャで、有用なワークフローであり、明らかな危険信号はありませんでした。

エンジニア1人あたり週に約15件のPRがあり、リトライと、プロンプトにファイル全体を挿入する際のコンテキストウィンドウのコストを考慮すると、エージェントはPRあたり平均約40万入力トークンを消費しました。CI/CD自動化の初月請求額は8,400ドルでした。

表2 — コスト帰属デバッグのウォークスルー。ゲートウェイを5回クリックし、設定を1箇所変更。帰属がなければ、CIワークフローでのSonnetは全面禁止という対応になっていたでしょう。帰属があったため、対応は1行の設定変更で済みました。

「モデルを禁止する」と「プロンプトを1つキャッシュする」というこの隔たりこそが、適切な帰属を行うことの最大の成果です。コストデータはどちらの場合でも存在します。問題は、それを読み解くためのラベルがあるかどうかです。

よくある質問

予算はドル建てとトークン建てのどちらにすべきですか？

両方、同時にです。ドルは財務および運用計画と連携します。トークンは、プロンプトの効率をデバッグできるエンジニアリング指標です。TrueFoundryは両方を追跡します。財務部門はドル建てのダッシュボードを、エンジニアリング部門はトークン建てのダッシュボードを所有し、ゲートウェイが両方の信頼できる情報源となります。プロバイダーの価格変更は、エンジニアリングが何もリファクタリングすることなくドル層で吸収されます。新しいファインチューニングは、財務部門がモデル名を知る必要なくトークン層で吸収されます。

パイプラインの途中でハードリミットに達するとどうなりますか？

パイプラインは、以前に示された詳細なエラーと予算ダッシュボードへのリンクを含む429エラーを受け取ります。CIランナーは429を標準的なバックオフシグナルとして解釈し、ビルドは混乱した方法でクラッシュするのではなく、実行可能なメッセージとともにきれいに失敗します。クォータの増加はプラットフォームチームに対する標準的なチケットとして提出されます。エラー本文のダッシュボードURLは、「なぜこれが失敗しているのか理解できない」という通常のやり取りを短縮します。

強制的なタグ付けはロールアウトを遅らせますか？

実際には、いいえ。SDKラッパーがCIテンプレート内で自動的にインジェクションを処理するため、個々の開発者がヘッダーを編集することはありません。1回限りのコストはチームのパイプラインテンプレートの更新であり、継続的なコストはゼロです。継続的なメリットは、それに続くすべてのダッシュボード、すべてのアラート、すべての事後分析です。

レート制限と予算制限の違いは何ですか？それぞれをいつ使用するのですか？

レート制限はバーストを止め、予算制限は支出を止めます。レート制限は1分あたりのリクエスト数または1分あたりのトークン数で表され、ダウンストリームサービスが過負荷になるのを防ぎ、リクエストごとに評価されます。予算は1日/週/月あたりのドルで表され、会社の財源を保護し、累積台帳に対して評価されます。ほとんどのプロダクションスタックは、異なるエンティティにスコープを設定して両方を実行します。これらのパターンは補完的であり、冗長ではありません。

‍

‍