mcpField
C
cost-verification-auditor

cost-verification-auditor

github.com/curiositechテスト・品質257165 回インストール2 日前に更新
リポジトリ

cost-verification-auditor について

Claude APIのトークンコスト見積もりの精度を検証する監査スキルです。見積もりを実行前に行い、入力・出力や総コストの差から調整上の問題を特定します。

主な機能

  1. 01±20%を目標にトークン見積もりを検証
  2. 02見積もりと実際のAPI使用量を比較
  3. 03単純・中程度・複雑なテストケースを用意
  4. 04入力・出力トークンの調整指針を提示
  5. 05よくある誤差と修正方法を特定

活用シーン

  1. 01実装後の見積もり精度の検証
  2. 02デプロイ前のコスト見積もり確認
  3. 03予想外のAPI請求の調査
  4. 04見積もりの定期的なずれの検出

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/curiositech/some_claude_skills --skill cost-verification-auditor

インストール後、Claude Code で/cost-verification-auditorを入力して読み込まれたか確認します。

同梱ファイル.claude-plugin/plugin.jsonreferences/calibration-data.md

詳細

コスト検証監査

トークンコストの推定値が、実際の Claude API 使用量の ±20％ 以内であることを検証します。

使用する場面

✅ 次の用途に使用します：

  • 実装後のトークン推定システムの検証
  • デプロイ前のコスト精度チェック
  • 予期しない API 請求のデバッグ
  • 定期的な推定値の乖離検出

❌ 次の用途には使用しません：

  • モデルの料金を調べる（料金ドキュメントを参照してください）
  • 予算の計画や予測
  • コスト最適化の戦略
  • 価格によるモデルの比較

監査の基本プロセス

判断フロー
Has estimator? ──No──→ Build estimator first (see Calibration Guidelines)
      │
     Yes
      ↓
Define 3+ test cases (simple/medium/complex)
      ↓
Estimate BEFORE execution (no peeking!)
      ↓
Execute against real API
      ↓
Calculate variance: (actual - estimated) / estimated
      ↓
Variance ≤ ±20%? ──Yes──→ PASS ✓
      │
     No
      ↓
Apply fixes from Anti-Patterns section
      ↓
Re-run verification
乖離の計算式
const inputVariance = (actual.inputTokens - estimate.inputTokens) / estimate.inputTokens;
const outputVariance = (actual.outputTokens - estimate.outputTokens) / estimate.outputTokens;
const costVariance = (actual.totalCost - estimate.totalCost) / estimate.totalCost;

// PASS if both input AND output within ±20%
const passed = Math.abs(inputVariance) <= 0.20 && Math.abs(outputVariance) <= 0.20;

よくあるアンチパターン

アンチパターン：500 トークンのオーバーヘッドという誤解

初心者の考え：「Claude Code では約 500 トークンのオーバーヘッドが加わるので、すべての推定値に加算しよう。」

実際のところ：直接の API 呼び出しで発生するオーバーヘッドは約 10 トークンです。500 トークン以上のオーバーヘッドが生じるのは、Claude Code の全コンテキスト（システムプロンプト、ツール、会話履歴）を使用する場合に限られます。

経緯：

  • 2025 年以前：多くのチュートリアルで 500 トークン以上の推定値が使われていました
  • 2025 年以降：直接の API 呼び出しのオーバーヘッドは最小限（約 10 トークン）です

代わりに使用する値：

コンテキストオーバーヘッド
直接の API 呼び出し約 10 トークン
システムプロンプトあり50～200 トークン
ツール／関数あり100～500 トークン
Claude Code の全コンテキスト500～2000 トークン

検出方法：40～90％の過大推定が継続している場合は、オーバーヘッドが高すぎます。

アンチパターン：ノードごとの精度への固執

初心者の考え：「すべてのノードが ±20％ 以内でなければ、推定器に問題がある。」

実際のところ：LLM の出力長は非決定的です。ノードごとの出力のばらつきが 30～50％ になるのは正常です。重要なのは、全体のコスト精度です。

代わりに行うこと：

  • DAG 全体のコストの乖離に注目します（±20％ 以内が目標です）
  • ノードごとの出力のばらつきは ±40％ まで許容します
  • 「3 項目を正確に列挙」のような制約付きプロンプトを使用して、ばらつきを抑えます

検出方法：入力の推定値は正確なのに出力が大きくばらつく場合は、通常の LLM の挙動です。

アンチパターン：推定前に API を実行する

初心者の考え：「まず API を呼び出してトークン数を確認してから、推定器を作ろう。」

実際のところ：これでは、特定のプロンプトに完全に適合した推定値が作られ、新しいプロンプトでは機能しなくなります。推定は実行前に行う必要があります。

正しい方法：

  1. プロンプトの長さとヒューリスティックに基づいて推定します
  2. API 呼び出しを実行します
  3. 乖離を比較します
  4. 必要に応じてヒューリスティックを調整します

キャリブレーションのガイドライン

入力トークンの推定
// Calibrated 2026-01-30
const inputTokens = Math.ceil(prompt.length / CHARS_PER_TOKEN) + OVERHEAD;
テキストの種類CHARS_PER_TOKEN備考
英語の文章4.0最も一貫しています
コード3.0～3.5記号は異なる方法でトークン化されます
混在3.5バランスが取れています（推奨されるデフォルト値）
JSON／構造化データ3.0句読点が多く含まれます
出力トークンの推定
プロンプトの制約乗数備考
「N 個の項目を正確に列挙」入力の 0.8 倍制約が強い
「簡潔に要約」入力の 1.0 倍中程度
「詳細に説明」入力の 2～3 倍詳細な出力
制約なし入力の 1.5 倍変動します

必ず守ること：意味のある応答では、出力トークン数を最低 100 にします。

モデルの挙動
モデル出力の傾向
Claude Opus長めで、より詳細
Claude Sonnetバランスが取れている
Claude Haiku簡潔で効率的

すぐにできる修正

症状原因修正方法
40％以上の過大推定オーバーヘッドが高すぎる500 から 10 に減らします
入力を過小推定する文字／トークン数が高すぎる4.0 から 3.5 に減らします
出力が大きくばらつくLLM の非決定性制約付きプロンプトを使用します
合計コストは正確だが、ノードごとの値に差がある集計による通常のばらつき許容し、合計値に注目します

検証チェックリスト

  • テストケースが 3 件以上（単純、中程度、複雑）
  • API 呼び出しの前に推定を実行する
  • 乖離の計算式：(actual - estimated) / estimated
  • 目標：入力と出力の両方で ±20％
  • レポートに実行可能な推奨事項が含まれている

参考資料

詳細なキャリブレーション表と過去のデータについては、/references/calibration-data.md を参照してください。

コメント

Markdown 対応