Manage costs effectively

一行要約

エンタープライズ平均は 1開発者あたり 1稼働日 $13 / 月 $150〜250。コストは context のサイズに比例するので、無関係な作業の間に /clear することとモデルを仕事に合わせることが最も効く2つの習慣。

要点

相場

指標	値
1開発者あたり 1稼働日	約 $13
1開発者あたり月	$150〜250
ユーザーの 90%	1稼働日 $30 未満

Budget more for a coding seat than a chat seat: each Claude Code turn carries file contents, tool calls, and multi-step reasoning, so one debugging session can consume more than a day of chat.

チャット用の席よりコーディング用の席に多く予算を見込め。Claude Code の1ターンはファイルの中身、ツール呼び出し、複数段の推論を伴うため、デバッグ1セッションがチャット1日分を超えて消費しうる。

追跡

/usage の Session ブロック:

Total cost:            $0.55
Total duration (API):  6m 20s
Total duration (wall): 6h 33m 10s
Total code changes:    0 lines added, 0 lines removed
Usage by model:
   claude-sonnet-4-6:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)

Claude Code computes the dollar figure locally from token counts at list price, unless a modelPricing table is in effect.

Claude Code は金額をローカルで、定価に基づくトークン数から計算している。ただし modelPricing の表が効いている場合を除く。

金額はあくまで推定。 正式な請求は Claude Console の Usage ページを見る。契約単価を反映させたい場合は managed settings の modelPricing を設定する（後述）。効いている間は Total cost の行に at your organization's configured rates の注記が付く。

/clear で新しいセッションを始めると合計はリセットされる（v2.1.211 より前は、Claude Code プロセスの生存中ずっと /clear をまたいで積み上がっていた）
data residency rate（1.1倍）で課金される応答については、そのトークンの定価を 1.1 倍してセッションコストに載せる。同じ合計値をステータスラインの cost フィールドにも出し、--max-budget-usd との比較にも使う（v2.1.239 より前は 1.1 倍が適用されず、表示が請求より低かった）

プロンプトキャッシュの統計（Prompt cache (main) 行、v2.1.251 以降）—— 本会話の最初の API 応答の後に付く。

Prompt cache (main):   14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago)

部分	意味
misses	キャッシュがすでに持っていた内容を再処理したリクエスト（最後の miss の時刻と、それらが書き戻したトークン数も出る）。最後の miss の原因の見当がつくときは、それも出る（`likely cause: tool definitions changed` など）。よくある原因は prompt-caching の「キャッシュを無効にする操作」の一覧
expected rebuilds	Claude Code 自身が会話を書き換えた直後（compaction、古い tool result の除去）の同種の miss。これは miss ではなくこちらに数える。1回以上起きた後にだけ表示される
warm / cold	キャッシュ済みの接頭辞がまだ寿命内か。cold ならセッションが何分 idle だったかを出す。API がキャッシュトークンを1度も報告していなければ `no prompt caching reported by the API` で終わる

数字は API 応答のキャッシュトークンから取るので、どのプロバイダ・ゲートウェイでも動く。対象は本会話だけで subagent は含まない。/clear でリセットされる。ステータスライン用スクリプトからは prompt_cache オブジェクトで同じ数字が読める。

プラン利用者向けの内訳（Pro / Max / Team / Enterprise）:

Attribution — skill、subagent、plugin、個別の MCP サーバごとの利用割合。MCP サーバの取り分に数えるのは、そのサーバのツール結果を消費したリクエストだけ（v2.1.222 より前は、1度呼んだ後の全リクエストをそのサーバに帰属させていて、取り分を過大に見せていた）
Behavior flags — long context や cache miss など、直近の利用の 10% 以上を占める振る舞いにフラグが立つ
Loops — 直近に走った /loop や scheduled task のうち重いものをトークン合計順に1行ずつ（発火間隔、実行回数、合計と1回あたりのトークン、最終実行時刻）。行はタスクのプロンプトで引くので、止めて作り直しても同じ1行のまま。v2.1.242 以降
d / w で 24時間 / 7日間を切り替え。VS Code 拡張では Account & usage ダイアログに attribution と behavior flags が出る（Loops の行は無い。v2.1.174 以降）
数字はこのマシンのローカルなセッション履歴から計算した概算。他のデバイスや claude.ai の利用は入らない

usage credits の支出の行（usage credits がオンの間）: Pro / Max は今月の支出を自分で決めた月次上限と並べて出す。上限を決めていなければ Unlimited とだけ出て、支出額は出ない。 Team / Enterprise は自分の今月の支出を、自分に掛かる組織の上限と並べて出す（組織全体の上限は出ず、自分の上限が無ければ支出だけ）。上限があれば usage credits をオンにした時点で行が出て、使い始めるまで 0%。v2.1.236 より前は Pro / Max だけで、上限つきの行は一度使うまで隠れていた。

/usage 自体が失敗したとき（利用状況エンドポイントが rate limit されたときが多い）: 直近60分以内にこのマシンで読めた最後のバーを Showing last-known usage の注記付きで見せる（いつ取得したかも出る）。r で再試行でき、成功すれば新しい数字に置き換わる。 60分以内のスナップショットが無ければ、rate limit された旨と同じ再試行ショートカットを出す（v2.1.208 より前は、まだ利用状況を読み込んでいないセッションで rate limit されると、バー無しでエラーだけを出していた）。

利用の「傾向」を見る — `/insights`

トークン量ではなく働き方の報告を作る。このマシンの最近のセッションを解析し、何に取り組んでいるか、摩擦点（要求の取り違え、バグを含むコード）、使い方の提案を HTML で書き出す。1回の実行で未見のセッションを最大200本まで解析し、非常に短いものは飛ばす。落ちたぶんがあると見出しに 200 sessions (412 total) のように出る。 auto mode が使えるのに最近のセッションがほぼ auto mode なしで走っていた場合、そのセッションの確認プロンプトのうち auto mode が処理できたはずの数の見積もりも報告に入ることがある。

最新は ~/.claude/usage-data/report.html、各実行のタイムスタンプ付きコピーも同じ場所に残る
削除は他のセッションデータと同じ規則（起動時に cleanupPeriodDays = 既定30日より古いものを消す）
どのプラン・どのプロバイダでも走る。通常のセッションと同じ経路を通るので、トークンは自分の枠から引かれる

usage credits（`/usage-credits`）

プランの上限を超えて作業を続けるための仕組み。/login で claude.ai のサブスクリプションにサインインしてから使う。API キー認証では使えない。 役割によって開くものが違う。

役割	`/usage-credits` の動作
Pro / Max	claude.ai の Settings > Usage をブラウザで開く（オンオフ、残高、今月の支出、月次上限）
Team / Enterprise（課金権限あり）	組織の Organization settings > Usage を開く
Team / Enterprise（課金権限なし）	確認を取ってから管理者へ要求を送る（v2.1.211 より前は確認なしで送っていた）

課金権限が無い場合の確認は対話セッションでのみ出る。-p や Remote Control では要求を送らず、対話セッションで実行するよう伝える。要求が管理者待ちの間に再実行しても重複は送らない。管理者が却下した後なら再実行で新しい要求を送る（v2.1.222 より前は却下されると再要求も塞がれた）。

Pro / Max で、usage credits が残っているのに自分の支出上限に達すると、CLI を離れずに上限を上げるか外すかを尋ねられる。

/usage-credits は、self-serve の Enterprise・Enterprise の試用・AWS Marketplace 経由の Enterprise では v2.1.248 以降が要る（それより前は Unknown command: /usage-credits）。

なぜ長いセッションで利用が跳ねるのか（重要）

Claude Code sends your full conversation with every request, and each time Claude uses tools it sends another request carrying that batch of tool results. With prompt caching, Claude Code re-reads that history at the cached token rate, so a one-line question in a session that has been open all day still draws usage for the whole conversation.

Claude Code は毎リクエストで会話の全体を送る。そして Claude がツールを使うたびに、その分の tool result を載せた別のリクエストを送る。prompt caching があれば、その履歴はキャッシュ済みトークンの単価で読み直される。だから一日開けたままのセッションでの一行の質問でも、会話全体分の利用量を消費することになる。

原因の一覧:

原因	内容
long context	全会話が毎リクエスト送られる。prompt caching があればキャッシュ単価で読み直されるが、それでも会話全体分を消費する
cache miss	キャッシュ寿命を超える中断の後、最初のメッセージが全 context を再処理する。寿命はサブスクリプションで 1時間、usage credits を使い始めると 5分に落ちる。API キーやクラウドプロバイダでは既定 5分
scheduled tasks	セッションが idle でも間隔ごとに発火し、毎回全 context を送る
cross-session messages	他セッションからのメッセージが新しいターンとして配送され、毎回全 context を送る。`crossSessionInbound` を `hold` にすると配送せず保留する
goal check-ins	バックグラウンドの作業が goal を待たせている間、セッションが idle でも Claude Code がその作業を確認させる。新しいターンが立ち、毎回全 context を送る
subagent と workflow	各 subagent と、dynamic workflow が起こす各エージェントは、本流の会話とは別に自分のリクエストを送る。取り分は使用量の内訳（Attribution）で見える
agent teammates	各 teammate が終了するまでトークンを消費し続ける
compaction	`/compact` は要約対象の会話を読むので、それ自体が大きなリクエスト。継続が要らないなら `/clear` はコストゼロ

goal check-ins は、あなたのプロンプトの間に goal あたり最大3回まで（v2.1.246 より前は上限なし）。切るには CLAUDE_CODE_GOAL_CHECKIN_MINUTES を 0 にする。v2.1.236 以降が要る。

usage credits を使っている間も1時間のキャッシュ寿命を保つ方法は、この原典から prompt caching の文書（TTL を自分で選ぶ）へ委ねられている。

Pro / Max では、長い中断の後に大きなセッションを再開すると、要約からの再開を提案してくるので、以降のリクエストが全履歴を運ばずに済む。

トークンを減らす戦略

1. context を先手で管理する

無関係な作業に移るとき /clear。 古い context は以降の全メッセージでトークンを無駄にする。/rename してから clear すれば後で /resume で戻れる
/compact に焦点を指定する — /compact Focus on code samples and API usage
CLAUDE.md に # Compact instructions セクションを置いて既定の挙動を変える

2. モデルを選ぶ — Sonnet がほとんどのコーディング作業に十分で Opus より安い。Opus に切り替えると、セッションのモデルを継承する subagent も Opus になる。 単純な subagent には model: haiku。

3. MCP のオーバーヘッドを減らす

Prefer CLI tools when available: Tools like gh, aws, gcloud, and sentry-cli are still more context-efficient than MCP servers because they don’t add any per-tool listing.

使えるなら CLI ツールを選べ。gh、aws、gcloud、sentry-cli といったツールは、ツールごとの一覧を増やさないぶん、MCP サーバより context 効率が良い。

/mcp で使っていないサーバを無効化する。

4. 型付き言語には code intelligence プラグインを入れる — 「go to definition」1回が、grep + 複数ファイル読みの代わりになる。編集後の型エラーも自動で報告される。

5. hook と skill に処理をオフロードする

Instead of Claude reading a 10,000-line log file to find errors, a hook can grep for ERROR and return only matching lines, reducing context from tens of thousands of tokens to hundreds.

Claude に1万行のログファイルを読ませてエラーを探させる代わりに、hook で ERROR を grep して該当行だけを返せる。これで context は数万トークンから数百トークンへ減る。

6. CLAUDE.md から skill へ指示を移す — CLAUDE.md はセッション開始時に必ずロードされる。200行以内を目標に。

7. extended thinking を調整する — thinking トークンは出力トークンとして課金され、既定の予算はモデルによってはリクエストあたり数万トークンになりうる。/effort を下げる、/config で thinking を切る、固定 thinking 予算のモデルなら MAX_THINKING_TOKENS を下げる。adaptive reasoning のモデルは 0 以外の予算を無視するので、そちらでは effort レベルを使う。Opus 5.5・Sonnet 5.5・Fable のモデルは常に extended thinking を使うので、thinking を切れない。

8. 冗長な処理を subagent に委譲する —— 冗長な出力は subagent の context に留まり、本流には要約だけが戻る。ただし subagent 自身のリクエストは使用量に数えられる。減らすなら subagent に小さいモデルを選ぶか、すべての subagent を1つのモデルで走らせる

9. agent team のコストを管理する

Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, because each teammate maintains its own context window and runs as a separate Claude instance.

teammate を plan モードで走らせる場合、agent teams は通常のセッションのおよそ7倍のトークンを使う。teammate がそれぞれ自分の context window を持ち、別々の Claude インスタンスとして走るからである。

原典は別節で、抑えるための5点を挙げている。

teammate には Sonnet を使う — 協調タスクでは能力とコストの釣り合いが良い
チームを小さく保つ — 各 teammate が自分の context window を持つので、トークンはおよそチーム規模に比例する
spawn プロンプトを絞る — teammate は CLAUDE.md・MCP サーバ・skill を自動で読む。spawn プロンプトに書いたものは最初から context に乗る
仕事が終わった teammate は落とす — 終了するかセッションが終わるまでトークンを消費し続ける
agent teams は既定で無効。 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 で有効にする

10. 具体的なプロンプトを書く — “improve this codebase” のような曖昧な要求は広い走査を引き起こす。

11. 複雑な作業の進め方

plan mode を使う — 方向が間違っていたときの高価なやり直しを防ぐ
早めに軌道修正する — Escape で即停止、/rewind か Escape 二度押しでチェックポイントに戻る
検証対象を与える
少しずつテストする

バックグラウンドのトークン消費

会話の要約（claude --resume 用）と一部のコマンド処理で、操作していなくても通常 1セッションあたり $0.04 未満を消費する。

プロンプト候補もリクエストを1本使う。 プロンプト候補（次のプロンプトの提案）がオンだと、Claude の応答の後にセッションのモデルへ短いリクエストを送る。会話の prompt cache を再利用するのでほとんどがキャッシュ読み取りと少しの出力トークンで、利用上限に近いときは送らない。止めたいならプロンプト候補をオフにする。

開発者が上限に当たったときの見分け方

メッセージ	意味
”You’ve hit your session limit” / “weekly limit”	座席ベースの利用枠。全モデル共通なので `/model` で切り替えても回復しない
”You’ve hit your Opus limit” / “Sonnet limit”	モデル別。この場合は `/model` でその系統の外のモデルに移れば作業を続けられる
”You’ve hit your individual spend limit” / “org’s monthly spend limit” / “team’s shared budget”	usage credits に請求されるはずのリクエストが、管理者の決めた支出上限に達した。続けさせるには Organization settings > Usage でメッセージが名指しした上限を上げる。プランのリセット時刻も出ていれば、それまで待つ手もある
Claude apps gateway の spend limit メッセージ	自前ホストのゲートウェイに設定した支出上限。期間がリセットされるか上限を上げるまでブロックされる
context / auto-compact の警告	利用上限ではない。 auto-compact の閾値に近づいただけ
API / クラウドで想定外に高い	大抵はclear されないまま続いた長いセッションか、既定モデルが Opus のまま

座席枠に当たった開発者ができること: /usage-credits で枠を超える利用を要求するか、 リセットを待って中断したタスクを自動で続ける（v2.1.234 以降。Claude Code が自分で待ちに入る場合と、 /rate-limit-options から選ぶ場合がある）。組織として自動の待ちの可否を決めるには、managed settings の autoContinueAtUsageLimit を設定する。

組織としてのコスト管理

どの経路で Claude Code を使っているかで、見る場所・止める場所・per-user の出し方が変わる。 Teams / Enterprise は各メンバーの座席枠から引かれ、Console とクラウドプロバイダは組織へトークン課金される。サインイン方法が混在する組織では、開発者ごとに、認証に使った経路の計り方になる。

経路	支出を見る	上限をかける	per-user の数字
Claude for Teams / Enterprise	組織 analytics の spend report	admin settings の spend limits	spend report CSV / Enterprise Analytics API（Enterprise のみ）
Claude Console（API）	Console の usage ページ	workspace の spend limits	Console ダッシュボード / Claude Code Analytics API
Bedrock / Google Cloud Agent Platform / Microsoft Foundry	自分のクラウドの請求コンソール	クラウドの予算管理	OpenTelemetry または LLM ゲートウェイ

OpenTelemetry export works on every setup and is the only option that streams per-user token and cost metrics into your own observability stack in near real time.

OpenTelemetry のエクスポートはどの構成でも動き、per-user のトークンとコストの指標を自前の可観測性スタックへほぼリアルタイムで流し込める唯一の選択肢である。

座席枠の性質（Teams / Enterprise）: 5時間のローリング枠と週次の枠でリセットされ、Claude チャットや Cowork と共有される。大きさは seat tier（Standard / Premium）による。枠の中の利用はドル建てで計量されない。

クラウドプロバイダの利用は Anthropic に戻ってこないので、analytics ダッシュボードと Claude Code Analytics API はその分を含まない。

契約単価で表示させる — `modelPricing`

既定では、Claude Code が開発者に見せる金額はすべて定価で計算される。 契約単価を払っている組織では /usage・ステータスライン・OpenTelemetry の数字が請求と合わない。合わせるには managed setting の modelPricing に自分の単価を書く。v2.1.242 以降。

この設定が変えるのは Claude Code の表示だけで、Anthropic の請求額は変わらない
単価は契約書から手で入れる。Claude Console から取ってはこないので、契約が変わったら自分で直す
定価からの一律割引なら multiplier を1未満に、上乗せ（markup）なら1より大きく（上乗せは v2.1.271 以降）。モデルごとなら overrides に4種のトークン単価。両方併用も可
managed settings 経由でのみ有効。 user / project / local settings と --settings では無視される
効いているかは /usage の Total cost 行の注記で確かめる。/model のピッカーに出る単価は定価のまま

組織の TPM / RPM 目安

チーム規模	TPM / user	RPM / user
1-5	200k-300k	5-7
5-20	100k-150k	2.5-3.5
20-50	50k-75k	1.25-1.75
50-100	25k-35k	0.62-0.87
100-500	15k-20k	0.37-0.47
500+	10k-15k	0.25-0.35

規模が大きいほど1人あたりの TPM が下がるのは、大きな組織ほど同時利用率が下がるため。

そのまま使える具体例

CLAUDE.md に compact の指示を書く:

# Compact instructions
 
When you are using compact, please focus on test output and code changes

テスト出力を失敗行だけに絞る hook（数万トークン → 数百トークン）:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')
 
# If running tests, filter to show only failures
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "$input" | jq --arg filtered "$filtered_cmd" \
    '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi

セットアップの確認 —— /hooks で PreToolUse の下に出ているか見る。あるいはデバッグログを取り、 hook がコマンドを書き換えたときに出る modified tool input keys の行に command が並ぶことを確かめる:

claude --debug-file ./claude-debug.txt
# セッション内で npm test を走らせてから ./claude-debug.txt を見る

thinking の予算を下げる:

export MAX_THINKING_TOKENS=8000              # 固定 thinking 予算のモデルのみ
export CLAUDE_CODE_GOAL_CHECKIN_MINUTES=0    # idle の goal check-in を止める

日々の習慣（この文書で最も効果が大きい2つ）:

/clear —— 無関係な作業に移るとき（コストゼロ。/compact と違い会話を読まない）
/model —— 仕事にモデルを合わせる（Sonnet を既定に、Opus は複雑な設計判断に）

原典で言及されている関連文書

context-window — auto-compact の閾値と何が生き残るか
agent-teams — teammate ごとの context window
sub-agents — 冗長な処理の隔離
mcp — tool search による MCP の context 削減
hooks-guide — 前処理による context 削減
memory — CLAUDE.md を 200行以内に保つ
skills — オンデマンドロードによる削減
sessions — 要約からの再開

ai-docs

エクスプローラー

Manage costs effectively

一行要約

要点

相場

追跡

利用の「傾向」を見る — `/insights`

usage credits（`/usage-credits`）

なぜ長いセッションで利用が跳ねるのか（重要）

トークンを減らす戦略

バックグラウンドのトークン消費

開発者が上限に当たったときの見分け方

組織としてのコスト管理

契約単価で表示させる — `modelPricing`

組織の TPM / RPM 目安

そのまま使える具体例

原典で言及されている関連文書

目次

バックリンク

ai-docs

エクスプローラー

Manage costs effectively

一行要約

要点

相場

追跡

利用の「傾向」を見る — /insights

usage credits（/usage-credits）

なぜ長いセッションで利用が跳ねるのか（重要）

トークンを減らす戦略

バックグラウンドのトークン消費

開発者が上限に当たったときの見分け方

組織としてのコスト管理

契約単価で表示させる — modelPricing

組織の TPM / RPM 目安

そのまま使える具体例

原典で言及されている関連文書

目次

バックリンク

利用の「傾向」を見る — `/insights`

usage credits（`/usage-credits`）

契約単価で表示させる — `modelPricing`