【ClaudeCode】コスト発生要因から考えるトークン消費最適化術【トークン】

Posted at 2026-07-27

はじめに

Claude Codeをはじめとする AI コーディングエージェントを使っていると、「トークン消費を減らすには？」というTipsは世の中にたくさん転がっています。「CLAUDE.mdを短くしよう」「/clearしよう」「サブエージェントを使おう」。どれも間違いではないのですが、Tipsを闇雲に集めるだけだと、

なぜそれが効くのか分からないまま導入してしまう
逆効果になるケース（例：サブエージェントの乱用）に気づけない
自分のワークロードにどのTipsが刺さるのか優先順位がつけられない

という問題が起きがちです。

そこで本記事では、「何がトークンコストを発生させているのか」という原因（発生要因）から出発して、対策を組み立てるというアプローチを取ります。Anthropic公式ドキュメント、AWS公式リポジトリの実装を実際に調査し、根拠を確認しながら整理しました。記載内容には確度に応じてラベルを付けています。

Anthropic 公式検証済み — Anthropic公式ドキュメント（code.claude.com/docs）に直接の記載・引用がある内容
AWS実例 — AWS公式リポジトリ（awslabs/agent-plugins）独自の運用基準。Anthropic公式仕様ではない

トークンコストを生む5つの構造

まず全体像です。トークンコストの発生要因は、「いつ・なぜ発生するか」で大きく5つに分類できます。

カテゴリ	発生タイミング	回避可能性
A. 構造的コスト	常時（毎ターン）	設計で軽減可（ゼロにはできない）
B. 非効率な振る舞い	特定の行動・指示の結果	回避可能（プロンプト・設計の工夫次第）
C. 状態遷移コスト	特定の操作のタイミング	操作を意識すれば軽減可
D. スケール・並列化コスト	複数インスタンス稼働時	規模の管理で軽減可
E. 背景コスト	アイドル時も含め常時	ほぼ回避不可（影響は小さい）

それぞれのカテゴリには、具体的なコスト要因が複数ぶら下がっています。詳細な解説に入る前に、まず全項目を一覧表にまとめます。

コスト要因一覧

ID	名称	カテゴリ	確度	概要
A1	コンテキスト常駐コスト	A. 構造的コスト	Anthropic	CLAUDE.md・MCPツール一覧・Skill説明文は使う使わないに関わらず毎回コンテキストに載る
A2	会話の累積再送コスト	A. 構造的コスト	Anthropic	ステートレスなため毎メッセージで会話全体を送信し直す
B1	探索コスト	B. 非効率な振る舞い	Anthropic	手順・構造が明示されていないと毎回ファイルを読み漁って再発見する
B2	冗長な出力の混入コスト	B. 非効率な振る舞い	Anthropic	巨大なログや生のJSONなど、必要以上の出力がそのままコンテキストに乗る
B3	曖昧な指示によるやり直しコスト	B. 非効率な振る舞い	Anthropic	曖昧なリクエストは広範囲スキャンを誘発する
B4	誤った方向への手戻りコスト	B. 非効率な振る舞い	Anthropic	実装の方向性を誤るとそれまでの作業がやり直しになる
B5	推論（Extended Thinking）トークンコスト	B. 非効率な振る舞い	Anthropic	thinkingトークンは出力トークンとして課金され、デフォルト予算は数万トークンに及ぶ
B6	ツール往復コスト	B. 非効率な振る舞い	AWS	逐次的な複数回のツール呼び出しはまとめて処理するより非効率（詳細は第2部）
C1	キャッシュミスコスト	C. 状態遷移コスト	Anthropic	キャッシュのTTL（サブスクリプション1時間・APIキー5分）超過でプレフィックスが全額課金になる
C2	要約（`/compact`）自体のコスト	C. 状態遷移コスト	Anthropic	`/compact`は会話全体を読むため、大きいコンテキストの要約はそれ自体が大きいリクエストになる
D1	Agent teamsの重複コスト	D. スケール・並列化コスト	Anthropic	各チームメイトが独立したフルコンテキストウィンドウを持ち、通常の約7倍のトークンを消費する
E1	アイドル時のバックグラウンド処理	E. 背景コスト	Anthropic	会話要約ジョブや`/usage`確認、スケジュールタスクなどがアイドル時にも発生する（影響は小さい）

以下、それぞれを具体的に見ていきます。

第1部 Anthropic公式ドキュメントに基づくコスト構造

ここからは、Anthropic公式ドキュメント（code.claude.com/docs）に直接の記載・引用がある内容を中心に見ていきます。

A. 常に発生する構造的コスト

A1. コンテキスト常駐コスト（Anthropic）

CLAUDE.md・MCPツール一覧・Skillの説明文などは、そのターンで使う使わないに関わらず毎回コンテキストに読み込まれます。Anthropic公式ドキュメントにも明記されています。

"If it contains detailed instructions for specific workflows (like PR reviews or database migrations), those tokens are present even when you're doing unrelated work."
—— code.claude.com/docs/en/costs.md

【対策】

CLAUDE.mdは200行以内を目安に、本質的な内容だけに絞る
常時必要でない手順的な内容（PRレビュー手順、マイグレーション手順など）はCLAUDE.mdに書かず、Skillsに切り出す（詳細はSkillsの構造を参照）
MCPツールは未使用サーバーを /mcp で無効化する。ツール定義はデフォルトで遅延ロードされるため、使わないツールは実際に呼ぶまでスキーマがロードされない

（注意点） CLAUDE.mdはセッション開始時に一度だけ読み込まれてメモリ上に保持されます。セッション中に編集してもキャッシュは無効化されませんが、その代わり「編集内容もそのセッションには反映されない」という点に注意が必要です。

"Editing them mid-session does not invalidate the cache, but the edit also doesn't apply. Claude keeps working with the version that was loaded at session start."
—— code.claude.com/docs/en/prompt-caching.md

新しい内容が読み込まれるのは次回の/clear・/compact・再起動時です。「CLAUDE.mdを直したのに反映されていない」という無駄なやり取りを避けるため、この仕様は押さえておく価値があります。

A2. 会話の累積再送コスト（Anthropic）

Claude Codeはステートレスで、毎メッセージで会話全体を送信し直しています。1行の質問であっても、それまでの会話全部のコストが乗ります。

"Claude Code sends your full conversation with every message, so a one-line question in a session that has been open all day uses tokens for the whole conversation, not just the one line."
—— code.claude.com/docs/en/costs.md

【対策】

無関係なタスクに入る前は /clear で完全リセットする。継続性が不要なら /clear は実行コストがゼロ（何も読まず単に破棄するだけ）
実際、Anthropicは高額請求の典型的な原因として「クリアされない長時間セッション」を明示的に挙げています。

"Unexpectedly high spend on an API or cloud-provider plan: usually traces back to long sessions that were never cleared or to Opus left as the default model."
クリアで会話を失いたくない場合は、/rename してからクリアすれば、後で /resume で戻れます

B. 非効率な振る舞いによる無駄

ここからは、特定の行動・指示によって「本来不要だったはずのトークン」が発生するケースです。

B1. 探索コスト（Anthropic）

既知の手順や構造がどこにも明示されていないと、Claudeは毎回ファイルを読み漁って再発見する羽目になります。

"A skill can give Claude domain knowledge so it doesn't have to explore. For example, a 'codebase-overview' skill could describe your project's architecture, key directories, and naming conventions. When Claude invokes the skill, it gets this context immediately instead of spending tokens reading multiple files to understand the structure."
—— code.claude.com/docs/en/costs.md

【対策】
定型的な手順・プロジェクト構造の知識をSkillとして明示的に与える（詳細はSkillsの構造を参照）。

B2. 冗長な出力の混入コスト（Anthropic）

巨大なログファイルや生のJSONレスポンスなど、必要な情報以上の出力がそのままコンテキストに乗ってしまうケースです。

"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."
—— code.claude.com/docs/en/costs.md

【対策】
PreToolUse フックで、Bashコマンドが実行される前にコマンド文字列自体を書き換え、フィルタ処理込みのコマンドに差し替える。PreToolUse は実行前に発火するため tool_output（実行結果）は受け取れないが、tool_input（実行しようとするコマンド）は書き換え可能（hookSpecificOutput.updatedInput）。これを利用し、例えば npm test を npm test 2>&1 | grep -E 'FAIL|ERROR' | head -100 のようなパイプ付きコマンドに置き換えてから実行させることで、Claudeに渡る時点の出力（実行後の結果）自体をすでに絞り込んだ状態にできる（costs.md）。

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

テストコマンドの出力を失敗行だけに絞るフックなどが典型例です。実際、公式ドキュメントのサンプルスクリプトも、テストコマンドかどうかを判定し、コマンド文字列に | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100 を追加してから updatedInput.command で差し替える、という実装になっています。

B3. 曖昧な指示によるやり直しコスト（Anthropic）

"Vague requests like 'improve this codebase' trigger broad scanning. Specific requests like 'add input validation to the login function in auth.ts' let Claude work efficiently with minimal file reads."
—— code.claude.com/docs/en/costs.md

【対策】
対象ファイル・関数名を具体的に指定するなど、曖昧さを減らしたプロンプトを書く。当たり前のようですが、公式が明示的に「トークンコストの要因」として言及している点は押さえておく価値があります。

B4. 誤った方向への手戻りコスト（Anthropic）

実装の方向性を誤ると、それまでの作業がすべてやり直しになります。

"Claude explores the codebase and proposes an approach for your approval, preventing expensive re-work when the initial direction is wrong."
—— code.claude.com/docs/en/costs.md

【対策】

Plan mode（Shift+Tabで切り替え）でまず承認を得てから実装に入る
方向性がずれたら即座に Escape で止め、/rewind で巻き戻す
テストケースや期待する出力を事前に提示し、Claude自身が検証できるようにする
1ファイル書いてテスト、また1ファイル書いてテスト、という段階的な進め方をする

（補足） /rewindは/compactよりキャッシュ効率の面でも有利です。/compactは会話履歴を新しい要約に置き換えるため新しいプレフィックスを作り直す必要がありますが、/rewindは既にキャッシュ済みの過去の時点まで会話を切り詰めるだけなので、そのプレフィックスは既存のキャッシュをそのまま再利用できます。

"Rewinding truncates back to a prefix that is already cached, rather than building a new one as compaction does."
—— code.claude.com/docs/en/prompt-caching.md

「間違った方向に進んだら/compactではなく/rewind」は、手戻り防止と課金面の両方で理にかなっています。

B5. 推論（Extended Thinking）トークンコスト（Anthropic）

Extended thinkingはデフォルトで有効になっており、thinkingトークンは出力トークンとして課金されます。デフォルトの予算はモデルによっては数万トークンに及びます。

"Extended thinking is enabled by default because it significantly improves performance on complex planning and reasoning tasks. Thinking tokens are billed as output tokens, and the default budget can be tens of thousands of tokens per request depending on the model."
—— code.claude.com/docs/en/costs.md

【対策】
深い推論が不要な単純作業では、/effort でeffortレベルを下げる、/config でthinkingを無効化する、固定thinking budgetを持つモデルでは環境変数 MAX_THINKING_TOKENS（例：MAX_THINKING_TOKENS=8000）で予算を絞る、といった調整が可能です。

（補足） Extended thinkingに限らず、出力トークンは入力トークンより単価が高く設定されています。例えばClaude Sonnet 5は入力$2 / 出力$10（2026年8月31日までの導入価格。以降は入力$3 / 出力$15に移行予定）、Opus 5は入力$5 / 出力$25（いずれも1Mトークンあたり）で、いずれの価格帯でも出力は入力の5倍です（公式Pricingページ）。つまりthinkingの有無に関わらず、Claude自身の応答が冗長になること自体がコストに直結します。加えてマルチターンの会話では、ある回の冗長な応答がそのまま次のターン以降の入力トークンとして再送信され続けるため、応答の長さは「その場の出力コスト」と「以降の入力コストの膨張」の両方に効いてきます。CLAUDE.mdや/output-styleで簡潔な応答を促す指示を与えるのは、この単価の非対称性を踏まえると理にかなった対策と言えます。

（B6. ツール往復コストについては、AWS公式リポジトリの実例に基づく内容のため、第2部「具体的な数値基準」でまとめて解説します。）

C. 状態遷移で発生するコスト

C1. キャッシュミスコスト（Anthropic）

Claude Codeはデフォルトでプロンプトキャッシュを自動管理しています。モデル切替・設定変更、そしてキャッシュのTTL（サブスクリプションで1時間、APIキーで5分）を超える間隔でのセッション再開などでプレフィックスが変わり、以降が全額課金になります。

"Cache misses: your first message after a break longer than the cache lifetime misses the cache and reprocesses your full context."
—— code.claude.com/docs/en/costs.md

【対策】
APIキー・Bedrock・Google Cloud・Microsoft Foundry・Claude Platform on AWSでの利用（デフォルトTTLが5分）では、環境変数 ENABLE_PROMPT_CACHING_1H=1 を設定するとTTLを1時間に延長できる（キャッシュ書き込み単価は上がるが、長い間隔でのキャッシュミスを防げる）。また、公式ドキュメントは以下のように明確に推奨しています。

"Pick your model and effort level at the top of a session, then save /compact for natural breaks between tasks. The fewer changes you make mid-task, the higher your cache hit rate."
—— code.claude.com/docs/en/prompt-caching.md

すなわち、モデル・エフォートレベルはセッション開始時に決めて途中で変えない、/compactはタスクの区切りで実行する（自動コンパクション任せにしない）、といった「キャッシュを無効化する操作」を意識的にタスクの途中で避けることが、公式に裏付けのある対策になります（他の無効化トリガー：fast modeの切り替え、MCPサーバーの接続変更、ツール全体の拒否ルール追加、Claude Codeのアップグレードなど）。

C2. 要約（`/compact`）自体のコスト（Anthropic）

これは見落とされがちですが、/compact はタダではありません。

"/compact reads the conversation it summarizes, so compacting a large context is itself a large request. When you want a fresh start instead of continuity, /clear costs nothing."
—— code.claude.com/docs/en/costs.md

「コンテキスト使用率が◯%になったら/compact」という具体的な閾値は、実は公式ドキュメントのどこにも存在しません。代わりにClaude Codeには、最大入力サイズに近づくと自動で要約する仕組み（自動コンパクション）があります。

【対策】

継続性が不要なら /compact（コストがかかる）より /clear（無料）の方が合理的、という判断基準が公式に示されている
手動/compactは「自動コンパクションに任せる」か「/compact [焦点]で能動的に要約内容を制御するか」の選択になる

D. スケールならびに並列化による乗数コスト

D1. Agent teamsの重複コスト（Anthropic）

複数のClaude Codeインスタンスを立ち上げるAgent teams機能（実験的機能、デフォルト無効）では、各チームメイトが独立したフルコンテキストウィンドウを持ちます。

"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."
—— code.claude.com/docs/en/costs.md

約7倍という数字はインパクトがあります。costs.mdには、この重複コストを抑えるための専用セクションが用意されています。

"To keep agent team costs manageable: Use Sonnet for teammates... Keep teams small... Keep spawn prompts focused... Shut down teammates when their work is done."
—— code.claude.com/docs/en/costs.md

【対策】

チームメイトにはSonnetを使う（コーディネーションタスクにはコストとのバランスが良い）
チームを小さく保つ（トークン消費はチーム規模にほぼ比例する）
spawnプロンプトを軽くする（CLAUDE.md/MCP/skillsは自動ロードされるため、spawnプロンプトに書いた内容がそのままコンテキストに追加で乗る）
作業完了後は速やかに終了させる（稼働中のチームメイトは終了するかセッションが終わるまでトークンを消費し続ける）

E. 背景コスト

E1. アイドル時のバックグラウンド処理（Anthropic）

--resume用の会話要約ジョブ、/usageのステータス確認、スケジュールタスクの定期発火などが、セッションがアイドル状態でも発生します。1セッションあたり通常$0.04未満と影響は小さいものの、存在は知っておいて損はありません。

【対策】
影響が小さいため積極的な対策は不要です。こうした背景コストが存在することを把握しておく程度で十分です。

Skills・サブエージェントは「使えば必ず安くなる」わけではない

ここが本記事で一番強調したいポイントです。「Skillsを使おう」「サブエージェントに任せよう」という助言をよく見かけますが、単発の呼び出しだけで見ると、むしろトークンが増えることが多いというのが正確な理解です。

サブエージェントの構造

サブエージェントは親のキャッシュを引き継ぎません（コールドスタート）。そのため、次のようなコストが発生します。

システムプロンプト分のトークンをゼロから消費する
「元の出力を読む」＋「要約を書く」＋「その要約を親が読む」という工程が増える
起動オーバーヘッドは、サブエージェント自身の会話全体が新規に発生する分だけかかる

削減効果が出るのは、単発呼び出しではなく、セッション全体・長期的な視点です。冗長な出力をメインの会話に残すと、以降の全ターンでその分が累積コストとして乗り続けます（A2）。サブエージェントに隔離すればメインスレッドは要約分だけで済み、キャッシュのヒット率も維持しやすくなります。本質的な価値は「探索作業そのものを安くすること」ではなく、「その後の会話が長引いたときの複利的な肥大化を防ぐこと」です。

向いている：大規模なコードベース探索・大量ログ処理など、生の出力が巨大でメインに残したくない一回性の作業。並列化できる独立したタスク。
向いていない：ちょっとした確認、メインの会話と密にやり取りが必要なタスク（コールドスタート＋要約往復のオーバーヘッドの方が高くつく）。

なお、通常のサブエージェントはサブスクリプション利用でも常に5分TTLのキャッシュになります（メインの会話に適用される1時間TTLの自動延長は適用されない）。

"Subagents use the five-minute TTL even on a subscription, since the automatic one-hour TTL applies to the main conversation."
—— code.claude.com/docs/en/prompt-caching.md

（補足）「コールドスタートを避けたいが、隔離もしたい」場合の例外として /subtask（旧/fork）という「フォーク」機能があります。フォークは会話履歴・システムプロンプト・ツール・モデルをメインセッションからそのまま引き継ぐサブエージェントで、最初のリクエストがメインの会話のプロンプトキャッシュをそのまま再利用できます（＝コールドスタートにならない）。結果だけがメインに返り、フォーク自身のツール呼び出しはメインの会話に残らないため、「背景説明なしで頼める」かつ「メインの会話を汚さない」を両立できます。ただし通常のサブエージェントと違い、フォークは独自のシステムプロンプトやツール制限を持てない点がトレードオフです。

"Because a fork's system prompt and tool definitions are identical to the parent, its first request reuses the parent's prompt cache. This makes forking cheaper than spawning a fresh subagent for tasks that need the same context."
—— code.claude.com/docs/en/sub-agents.md

Skillsの構造

SkillsもCLAUDE.mdと違い、本文は「使われるまでロードされない」というprogressive disclosureの仕組みを持ちます。

"Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it."
—— code.claude.com/docs/en/skills.md

つまりSkillが発火する瞬間のコストは、その内容をCLAUDE.mdに直接書いていた場合と大差ありません。得をするのは「そのSkillを使わないセッション」においてゼロコストになる点です。したがって、次のように使い分けるのが合理的です。

発生頻度が低い・特定タスクでしか使わない手順（PRレビュー、マイグレーション手順など）はSkill化が有効
ほぼ毎ターン使う内容は、遅延ロードの旨みが薄れるため、むしろCLAUDE.mdに常駐させた方が合理的な場合もある

Anthropic公式も、定型ワークフローの切り出し先としてSkillsを明確に推奨しています。

"Move instructions from CLAUDE.md to skills... Aim to keep CLAUDE.md under 200 lines by including only essentials."
—— code.claude.com/docs/en/costs.md

定型作業がSkillsと相性が良い理由は3つあります。

遅延ロードとの相性（頻繁だが常時ではない、という使用頻度パターンに合う）
探索コストの削減（B1で述べた通り、Skillがあれば毎回ファイルを読み漁らずに済む）
一貫性による手戻り削減（手順が明示されていれば、Claudeが毎回異なるアプローチを試みて修正が発生する、といった無駄が減る可能性が高い）

第2部 AWSの実例から学ぶトークン節約ノウハウ

ここからは、AWSが公開しているAgent Skills集のリポジトリ awslabs/agent-plugins から得られる知見です。Anthropic公式仕様ではなく、AWSがこのリポジトリのために独自に定めた運用基準・設計指針である点にあらためて注意してください（AWSラベル）。

具体的な数値基準

Anthropic公式ドキュメントにも、SKILL.mdのサイズについて具体的な数値基準が実は存在します。

Anthropic公式
"Keep SKILL.md under 500 lines. Move detailed reference material to separate files."
—— code.claude.com/docs/en/skills.md

500行という、この一点の基準に対して、AWSが公開しているAgent Skills集のリポジトリ awslabs/agent-plugins は、より運用レベルまで踏み込んだ基準を持っています（ここから先はAWS独自の運用基準で、Anthropic公式仕様ではありません）。

このリポジトリの設計哲学は、次の一文に集約されています。

AWS実例
"Files should be SHORT and FOCUSED. Every token counts in an agent's context window."
—— docs/DESIGN_GUIDELINES.md

そして、CIで強制されるサイズ基準（tools/markdownlint-skill-length.cjs、独自lintルールSKILL001）は次の表の通りです。

基準	行数	単語数	挙動
ハードエラー	500行超	8,000語超	CIをブロック
警告	300行超	5,000語超	警告のみ

ハードエラーの閾値（500行）が、Anthropic公式の「500行未満に」という基準とぴったり一致している点は興味深いところです。Anthropicが示す唯一の数値である「500行」を、AWSは①300行時点での警告という早期シグナル、②語数（8,000語／5,000語）という行数と独立した尺度、③CIによる自動強制、という3段階でさらに運用レベルまで具体化している、と整理できます。

同ツールのコメントが、Skillsの本質を端的に表しています。

"SKILL.md is loaded into the agent's context window on every invocation. Keep it lean — big ideas and routing only. Push detailed instructions, examples, and reference material into sub-files under references/ so the agent loads them on demand."

さらに詳細な目安として、SKILL.md本体は200〜300行、参照ファイル（references/配下）は1ファイル50〜100行、初回ロードは5,000トークン未満を目標にする、コードブロックが30行を超えたら切り出す、といった基準が示されています。計測方法として claude --plugin-dir ./plugin --verbose で実際のトークン消費を確認する運用も紹介されています。

このほか、同リポジトリからはいくつかの指針も得られます。「Write for Agents, Not Humans」という方針では、会話調・雑談・絵文字・前置きを避け、明示的で曖昧さのない指示にすることが求められています。Minimize Roundtrips（ツール往復コスト）という考え方では、10回に分けて別々にスキャンするような逐次的な複数回のツール呼び出しよりも、まとめて1回で処理できる設計の方が効率的だとされ、往復のたびに発生するコンテキスト消費を抑えられます。またCaching GuidanceをSkillの指示内に明記する手法もあり、「AWSサービス一覧はセッション中キャッシュせよ（変更頻度が低い）」「価格データは毎回再取得せよ（変更頻度が高い）」のように、エージェントの再取得判断を指示の中で明示的に制御します。

対策一覧

冒頭の「コスト要因一覧」と対になる表です。各コスト要因に対して、本記事で紹介した具体的な対策を一覧化しました。IDは冒頭の表と対応しています。

ID	名称	対策	確度
A1	コンテキスト常駐コスト	CLAUDE.mdは200行以内に絞る／手順的な内容はSkillsへ切り出す／未使用MCPサーバーを`/mcp`で無効化	Anthropic
A2	会話の累積再送コスト	無関係なタスクの前に`/clear`（実行コストゼロ）／残したい会話は`/rename`してからクリアし`/resume`で復帰	Anthropic
B1	探索コスト	定型的な手順・プロジェクト構造の知識をSkillとして明示的に与える	Anthropic
B2	冗長な出力の混入コスト	`PreToolUse`フックでコマンド文字列自体を書き換え、フィルタ処理込みのコマンドに差し替える（`updatedInput`）	Anthropic
B3	曖昧な指示によるやり直しコスト	対象ファイル・関数名を具体的に指定し、曖昧さを減らしたプロンプトを書く	Anthropic
B4	誤った方向への手戻りコスト	Plan modeで承認を得てから実装／方向性がずれたらEscapeで止め`/rewind`／検証目標を事前提示／1ファイルずつ段階的に進める	Anthropic
B5	推論（Extended Thinking）トークンコスト	`/effort`でeffortレベルを下げる／`/config`でthinkingを無効化／`MAX_THINKING_TOKENS`で予算を絞る	Anthropic
B6	ツール往復コスト	逐次的な複数回のツール呼び出しではなく、まとめて1回で処理できる設計にする（Minimize Roundtrips）	AWS
C1	キャッシュミスコスト	APIキー等の利用では`ENABLE_PROMPT_CACHING_1H=1`でTTLを1時間に延長／モデル・エフォートレベルはセッション開始時に固定し途中で変えない／`/compact`はタスクの区切りで実行する	Anthropic
C2	要約（`/compact`）自体のコスト	継続性が不要なら無料の`/clear`を使う／継続したい場合は自動コンパクションに任せるか`/compact [焦点]`で能動的に制御する	Anthropic
D1	Agent teamsの重複コスト	チームメイトにはSonnetを使う／チームを小さく保つ／spawnプロンプトを軽くする／作業完了後は速やかに終了させる	Anthropic
E1	アイドル時のバックグラウンド処理	影響が小さい（$0.04未満/セッション）ため、積極的な対策は不要。存在を把握しておく程度でよい	Anthropic

この表の「確度」は対策そのものの裏付けを指しており、コスト要因一覧の確度（コストが発生するという事実の裏付け）とは別軸である点にご留意ください。

実際に自分の環境で検証する方法

本記事の内容を自分のワークロードで検証したい場合、以下の方法が使えます。

手軽な方法（Claude Code内蔵）

方法	用途
`/usage`	セッション全体のトークン数、モデル別のinput/output/キャッシュ読み書きトークン数。Pro/Max/Team/Enterpriseプランでは、キャッシュミスなどが直近利用の10%以上を占める場合に警告も表示される
`/context [all]`	コンテキスト使用量を項目別に可視化
statusline設定	ターミナルに常時トークン使用量を表示。`current_usage`オブジェクトの`cache_creation_input_tokens`（新規キャッシュ書き込み）／`cache_read_input_tokens`（キャッシュ読み取り）を見れば、C1のキャッシュヒット率もその場で確認できる
`claude --plugin-dir ./plugin --verbose`	特定のSkill/プラグインの実際のトークン消費を確認

精密な方法（Token Counting API）

Anthropic公式のToken Counting API（POST /v1/messages/count_tokens）は無料で利用できます。CLAUDE.md・SKILL.md・プロンプトの書き方を変えた前後で input_tokens を比較すれば、その変更が実際にトークン数を減らしているかを具体的な数値で検証できます。

curl https://api.anthropic.com/v1/messages/count_tokens \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "messages": [{"role": "user", "content": "この関数はユーザーの入力を検証してからデータベースに保存します。"}]
  }'

ant CLIがあれば、より簡潔に呼び出せます。

ant messages count-tokens --model claude-opus-5 \
  --message '{role: user, content: "計測したいテキスト"}' \
  --transform input_tokens -r

（注意点） tiktoken（OpenAI用）など、Claude以外のトークナイザーで代用計測すると、Claudeの実際のトークン数とはズレが生じます（具体的な誤差率は公式のAPI/製品ドキュメントには記載がなく、公式裏付けのない数値のため本記事では割愛します）。必ずClaude公式のToken Counting APIを使ってください。また、「文字数÷4」のような簡易推定は英語テキストを前提にした経験則であり、日本語には当てはまらない可能性が高い点にも注意が必要です。

さいごに

今回のように「なぜコストが発生するか」という発生要因から出発すると、対策の適用範囲や優先順位が自然と見えてきます。発生要因を意識せずに対策だけを場当たり的に取り入れると、効果の薄い対策に時間を使ったり、サブエージェントの乱用のように意図しない副作用に気づけなかったりします。「何に効く対策なのか」を理解して初めて、次に何を試すべきかの判断もできるようになる、というのが本記事を書いてみての一番の実感です。

一般論だけを追っていては気づけない具体的な実装が公式ドキュメントに載っており、一次情報を直接あたることは大切です。トークン消費に限らず、こうした調査は「知っているつもり」を一度疑ってみるところから始めるのが、結局いちばんの近道なのかもしれません。

Claude Codeの仕様は今後も変わっていくはずなので、本記事の内容もいずれ古くなります。気になる点や実際に試してみた結果があれば、ぜひコメントで教えてください。

参考文献

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

【ClaudeCode】コスト発生要因から考えるトークン消費最適化術【トークン】

はじめに

トークンコストを生む5つの構造

コスト要因一覧

第1部 Anthropic公式ドキュメントに基づくコスト構造

A. 常に発生する構造的コスト

A1. コンテキスト常駐コスト（Anthropic）

A2. 会話の累積再送コスト（Anthropic）

B. 非効率な振る舞いによる無駄

B1. 探索コスト（Anthropic）

B2. 冗長な出力の混入コスト（Anthropic）

B3. 曖昧な指示によるやり直しコスト（Anthropic）

B4. 誤った方向への手戻りコスト（Anthropic）

B5. 推論（Extended Thinking）トークンコスト（Anthropic）

C. 状態遷移で発生するコスト

C1. キャッシュミスコスト（Anthropic）

C2. 要約（/compact）自体のコスト（Anthropic）

D. スケールならびに並列化による乗数コスト

D1. Agent teamsの重複コスト（Anthropic）

E. 背景コスト

E1. アイドル時のバックグラウンド処理（Anthropic）

Skills・サブエージェントは「使えば必ず安くなる」わけではない

サブエージェントの構造

Skillsの構造

第2部 AWSの実例から学ぶトークン節約ノウハウ

具体的な数値基準

対策一覧

実際に自分の環境で検証する方法

手軽な方法（Claude Code内蔵）

精密な方法（Token Counting API）

さいごに

参考文献

C2. 要約（`/compact`）自体のコスト（Anthropic）