CLAUDE LABEN
VERSION — 8月10日に v2.1.227 が出ていました。新機能はなく、プラン判定と CI まわりの不具合修正が中心ですAUTO — 8月14日の既定化まで残り2日です。Pro・Max・Team で Claude Code の auto モードが既定で有効になりますCI — claude-code-action で allowed_non_write_users を指定すると GitHub ホストランナー上の Bash が全て失敗していた問題が直りましたBILLING — 期限切れトークンで開始したセッションが加入プランを取り違え、Max 利用者に使用クレジットの有効化を促していた不具合も解消していますSUNSET — 旧 Workbench と実験的プロンプトツール API の廃止は8月17日で、残り5日ですPRICE — Sonnet 5 のプロモ価格 $2/$10 per Mtok は8月31日までで、9月1日から $3/$15 per Mtok になりますVERSION — 8月10日に v2.1.227 が出ていました。新機能はなく、プラン判定と CI まわりの不具合修正が中心ですAUTO — 8月14日の既定化まで残り2日です。Pro・Max・Team で Claude Code の auto モードが既定で有効になりますCI — claude-code-action で allowed_non_write_users を指定すると GitHub ホストランナー上の Bash が全て失敗していた問題が直りましたBILLING — 期限切れトークンで開始したセッションが加入プランを取り違え、Max 利用者に使用クレジットの有効化を促していた不具合も解消していますSUNSET — 旧 Workbench と実験的プロンプトツール API の廃止は8月17日で、残り5日ですPRICE — Sonnet 5 のプロモ価格 $2/$10 per Mtok は8月31日までで、9月1日から $3/$15 per Mtok になります
記事一覧/API & SDK
API & SDK/2026-06-15上級

課金変更が発効した日に、headless 実行のコストを工程ごとに計測する仕組みを入れた

6月15日の課金変更で headless 実行とエージェント委譲が月次クレジット制になりました。どの工程がいくら使っているかを response.usage から工程タグ単位で記録し、日次で円換算レポートを出す計測レイヤーの実装を共有します。

claude-agent-sdk6headless13cost-control2metering課金変更2可観測性5

プレミアム記事

月次クレジット制への移行が本日発効し、自動投稿パイプラインの headless 実行が「サブスクの定額内」から「使った分だけクレジットを削る」世界に変わりました。移行前に工程の振り分けは見直していたのですが、いざ初日を迎えて気づいたのは、そもそも自分が「どの工程がいくら使っているか」を数字で把握していなかったということです。

個人開発で4サイトを回している自分にとって、見積もりは立てていました。けれど見積もりは見積もりで、実測ではありません。繰越のないクレジットを月内で配分するなら、推測ではなく「先週この工程は実際にいくら溶かしたか」という台帳が要ります。そこで初日のうちに、各 API 呼び出しのトークン消費を工程タグ単位で記録し、日次で円換算するだけの薄い計測レイヤーを差し込みました。今日はその中身を順番に書いていきます。

派手な可観測性基盤の話ではありません。狙いは「既存のコードにほぼ手を入れず、後から工程別にコストを問い詰められる状態」を最小コストで作ることです。

なぜ Console の請求画面だけでは足りないのか

Anthropic Console の使用状況画面は、アカウント全体・API キー単位での消費は見せてくれます。けれど私の運用では、ひとつの API キーで「記事生成」「品質ゲート判定」「ニュース収集」「翻訳同期」という性質の違う工程が混ざって走っています。Console を開いても、今週クレジットを最も食ったのが生成なのか、それともリトライを繰り返した品質ゲートなのかが分からないのです。

月次クレジットは繰越がありません。つまり「月末に足りなくなる工程」を事前に特定できなければ、優先度の低い工程が高い工程のクレジットを食い潰したまま気づけません。Console の粒度では、この「工程別の取り合い」が見えないのが本質的な問題でした。

必要なのは、API 呼び出しのたびに usage を工程名つきで記録し、後から stage=quality-gate の今月の累計はいくら と聞ける台帳です。これはアプリ側でしか作れません。

response.usage を取りこぼさない

計測の土台は、すべての応答に含まれる usage オブジェクトです。ここで最初の落とし穴がありました。usage は単純な入力・出力の2項目ではありません。プロンプトキャッシュを使っていると、実際には4種類のトークンが返ってきます。

// Anthropic SDK の応答に含まれる usage の実際の形
// (キャッシュを使うと cache_* が非ゼロになる)
type RawUsage = {
  input_tokens: number;             // 非キャッシュの入力
  output_tokens: number;            // 生成された出力
  cache_creation_input_tokens?: number; // キャッシュへの書き込み(割増)
  cache_read_input_tokens?: number;     // キャッシュからの読込(大幅割引)
};

ここを input_tokens + output_tokens だけで集計すると、キャッシュ生成・キャッシュ読込のトークンがまるごと台帳から抜け落ちます。キャッシュ生成は通常の入力より割高、キャッシュ読込は大幅に安い、という非対称な単価がついているので、4種類を別々に持っておかないと円換算が合いません。私は最初これを2項目で集計していて、実測値が Console の請求とどうしても噛み合わず、半日溶かしました。

そこで、4種類を必ず別フィールドで保持する正規化関数を最初に置きます。

// 欠けたフィールドを 0 で埋め、4種類を必ず揃える
export function normalizeUsage(raw: Partial<RawUsage> | undefined) {
  return {
    input: raw?.input_tokens ?? 0,
    output: raw?.output_tokens ?? 0,
    cacheWrite: raw?.cache_creation_input_tokens ?? 0,
    cacheRead: raw?.cache_read_input_tokens ?? 0,
  };
}

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること
「今月のクレジットが何に消えたか分からない」状態を、工程タグ単位の実測データで説明できるようになります
response.usage の4種類のトークン(入力・出力・キャッシュ生成・キャッシュ読込)を取りこぼさず記録し、円換算する計測ラッパーをコピペで導入できます
計測結果から「どの工程を headless に残し、どこをサブスク枠へ戻すか」をクレジット消費の根拠つきで判断できるようになります
Stripe による安全な決済 · いつでもキャンセル可能

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または
メンバーシップなら全記事が読み放題 →
シェア

お読みいただきありがとうございます

Claude Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • コピー&ペーストで使える実装コード付き
  • 毎日新しい上級ガイドを追加
  • ¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

関連記事

API & SDK2026-06-12
月次クレジット移行を前に、自動パイプラインの工程配分を見直した記録
6月15日の課金変更で Agent SDK・headless 実行・GitHub Actions が月次クレジット制へ移行します。自動投稿パイプラインの工程を実測トークンから棚卸しし、3つの実行経路へ振り分け直した設計判断を共有します。
API & SDK2026-07-11
本番で観測した引数分布からツールスキーマを締め直す
Claudeのツール呼び出しが渡してくる引数を本番で丸ごと記録し、その分布からJSON Schemaにenumやpatternを足して締め直す運用手法を整理しました。緩いスキーマが生む意味のドリフトの実例、段階的に締める手順、締め直し前後の実測値、状況別の推奨まで計測コード付きで紹介します。
API & SDK2026-06-14
Claude Agent SDK のツールを冪等にする — 二重実行を止める冪等性キーと Outbox の実装メモ
Claude Agent SDK のリトライやセッション再開で決済を二重処理する事故を防ぐ実装メモ。決定的な冪等性キー・Outbox・軽量ラッパーの3パターンを、動くコードと運用メトリクスつきで設計します。
📚RECOMMENDED BOOKS
大規模言語モデル入門
山田育矢
LLM開発
生成AIプロンプトエンジニアリング入門
我妻幸長
プロンプト
Claude CodeによるAI駆動開発入門
平川知秀
AI駆動開発
※ アフィリエイトリンクを含みます
もっと見る →