cost-counterfactual

複数のベースラインを用いた反実仮想コスト分析。既存の可観測性機能と組み合わせて使えます。

• cost-budget-check — 「しきい値を超えましたか？」（リアクティブ）
• cost-projection — 「いつしきい値を超えますか？」（予測）
• cost-counterfactual — 「ルーティングは見合う成果を上げていますか？」（比較） ← これです

アルゴリズム

1. cost-tracking 名前空間からすべての session-* レコードを読み込みます。
2. --since の期間フィルターを適用します（デフォルトは全期間）。
3. 各セッションの byModel[*] エントリーに含まれるトークンを合計します。
4. 指定された各ベースライン（デフォルト：3つすべて）について、次のように計算します。
   • counterfactualUsd = (input × tier.input + output × tier.output + cache_write × tier.cache_write + cache_read × tier.cache_read) / 1M
5. savings = counterfactualUsd − actualUsd を計算します。
6. 比較対象全体にわたるベースラインごとの合計と節約率を出力します。

スモークテストの実行例（2セッション：haiku のトークン 50K と sonnet のトークン 50K）

| Sessions considered | 2 |
| Total input tokens  | 100,000 |
| Actual spend        | $0.162500 |

| Baseline           | Hypothetical | Actual    | Savings    | %       |
| `always-haiku`     | $0.025000    | $0.162500 | -$0.137500 | -550.00% |
| `always-sonnet`    | $0.300000    | $0.162500 | +$0.137500 |   45.83% |
| `always-opus`      | $1.500000    | $0.162500 | +$1.337500 |   89.17% |

節約額がマイナスの場合の見方

always-haiku の結果がマイナスの場合は、ルーターが haiku でも処理できたタスクに、より高価なモデルを選択したことを意味します。これは過剰なエスカレーションの兆候です。

• qualityBar の設定が高すぎる可能性があります
• 複雑さを考慮すると sonnet／opus のセッションは妥当だったものの、ベースラインではその点が考慮されていない可能性があります
• 調査するには cost optimize を実行するか、cost conversation で個々のセッションを確認してください

プラスの節約額は、そのベースラインと比べたルーターの成果を示します。通常、最も参考になる数値は always-sonnet です。ルーティングがなければ多くのチームが選ぶ標準的な「安全なデフォルト」ベースラインです。

使用する場面

• 四半期ごとのコストレビュー：「常に Sonnet を使う場合と比べて $X 節約しました。その根拠はこちらです。」
• CI ゲート：cost counterfactual --format json | jq '.baselines[1].savingsPct > 30' — sonnet ベースラインと比べてルーティングによる節約が 30% 以上でない場合、ビルドを失敗させます（ワークロード変化の検出）。
• ルーティング設定の検証：新しい qualityBar またはコスト上限を導入する際に、カウンターファクチュアル分析を再実行して、節約額が悪化していないことを確認します。

定常性に関する注意点

すべての反実仮想分析と同様に、同じ複雑さのトークンをベースラインモデルに与えた場合、同じ結果が得られることを前提としています。これは上限値です。ベースラインでは処理に失敗して再試行が必要になった可能性がありますが、この計算では考慮されません。この数値は、品質を考慮しない上限として扱ってください。