token-optimizer

トークン最適化

トークン消費を抑え、AI コストを削減するための包括的なツールキットです。Claude Code ユーザー（ファイル整理、CLAUDE.md、コンテキストの整理）とAPI 開発者（プロンプトキャッシュ、Batch API、effort の調整、プロンプトアーキテクチャ）の両方を対象としています。推奨事項は、実際の実験データと現在の Anthropic の料金に基づいています。

該当するセクション：

• Claude Code を使用していますか？ → セクション 1～5 と「すぐにできる改善チェックリスト」をご覧ください。
• Anthropic API を直接呼び出していますか？ → references/api-optimization-guide.md もご覧ください。最も大きなコスト削減効果があります（プロンプトキャッシュで 90％ 割引、Batch API で 50％ 割引。併用可能です）。

インストール

npx skills add amunozdev/token-optimizer

または、手動でインストールします。

cp -r token-optimizer ~/.claude/skills/

主な機能

1. ファイル整理の最適化

最も効果の高い最適化です。小さく目的を絞ったファイルにすると、日常の開発作業の大半を占める、対象を絞ったタスクでのトークン消費を 18.2％、ノイズを 92％ 削減できます。

基本ルール：

• 1 ファイルあたり最大 150 行です。それ以上になる場合は、責務ごとに分割します。
• 単一責務にします。1 ファイルにつき 1 つの関心事に絞ります。
• kebab-case のわかりやすい名前を付けます。ファイル名から、AI が内容を正確に把握できるようにします。

実例： メール検証のバグ修正で、モノリシックなファイルでは 814 行（49,466 トークン）を読む必要がありましたが、モジュール化された構成では 67 行（40,447 トークン）で済みました。18.2％ の削減、ノイズを 92％ 削減できます。

命名規則、避けるべきもの／推奨するものの比較表、プロジェクト構成のテンプレートについては、references/file-organization-guide.md をご覧ください。

2. CLAUDE.md の最適化

適切に構成された CLAUDE.md によって、トークン消費を 50～70％ 削減できます。多くのプロジェクトでは CLAUDE.md が肥大化しており、やり取りのたびに不要なコンテキストが読み込まれています。

主な原則：

• 500 行未満に収め、必須事項だけを記載します。
• 具体的に記述します。「データベース」だけではなく、「Prisma を使用した PostgreSQL」のように記載します。
• プロジェクト構成とコマンドを記載し、AI が推測しなくて済むようにします。
• ドキュメント全体ではなく、トリガーを使います。詳細はスキルやファイルを参照させ、すべてを直接記載しないようにします。

すぐに使える最適化済みテンプレートについては、references/claude-md-template.md をご覧ください。

3. コンテキスト管理

トークンの無駄は、個々の操作よりも、関係のないコンテキストが蓄積することで生じることがよくあります。

基本的なコマンド：

コマンド	使用するタイミング	効果
/clear	タスクを切り替えるとき、大きな修正を行った後	コンテキストを完全にリセットします
/compact	会話が長くなったとき（50 回を超えるやり取り）	履歴を圧縮し、重要な情報を保持します
/context	トークン消費が多い原因を調べるとき	トークンを消費している内容を表示します

遅延読み込み： 情報をすべて最初に読み込まないようにします。あるプロジェクトでは、CLAUDE.md にトリガーだけを記載し、詳細を必要に応じて読み込むことで、初期トークンを 54％ 削減しました（7,584 → 3,434）。

高度な戦略、サブエージェントのパターン、MCP の管理については、references/context-management-guide.md をご覧ください。

4. タスクに応じたモデルの選択

タスクの種類に応じて適切なモデルを選ぶことは、簡単に実践できるコスト削減策の 1 つです。

タスクの種類	モデル	理由
日常タスクの 80％	Sonnet	コストと性能のバランスが最良です
複雑なアーキテクチャ	Opus	より深い推論が必要です
簡単なタスク／短時間で済むタスク	Haiku	Opus より最大 18 倍安価です

通常は Sonnet を使います。本当に複雑な問題に限り、Opus に切り替えます。簡単なタスク、テスト、検索には Haiku を使います。

5. MCP とサブエージェントの最適化

MCP の管理：

• 同時に有効にする MCP は最大 10 個にします（ツールは合計最大 80 個）。
• 現在のタスクで必要ない MCP は無効にします。
• 使用していない MCP も、ツールの説明によってトークンを消費します。

出力が多いタスクにはサブエージェントを使用： テストの実行、ビルド、検索など、大量の出力が生成される操作には Task ツールを使います。大量の出力はサブエージェントのコンテキスト内に保たれ、要約だけがメインの会話に返されます。

6. プロンプトの設計（Claude Code と API）

プロンプトの書き方は、トークン数に直接的かつ測定可能な影響を与えます。増えることも減ることもあります。

• 率直に、依頼内容を最初に述べ、一度だけ伝えます。 繰り返しても遵守率は上がらず、料金がかさむだけです。
• 出力を明示的に制限します。 「50語以内」「箇条書きは最大3項目」「キーが X、Y、Z の JSON。説明は不要」などです。自由度の高いプロンプトは、自由度の高い（コストのかかる）応答を生みます。
• XML タグ（<instructions>、<context>、<output_format>）を使って曖昧さを減らします。
• 関連するコンテキストだけを含めます。 1つの関数で十分な場合に、500行を貼り付けないでください。

7. API 限定の最適化

Anthropic API を直接呼び出す場合（SDK、カスタムエージェント、本番アプリ）、以下は最も効果の高い最適化手段です。ほとんどは、ハーネスが処理するため Claude Code では必要ありません。

手法	削減効果	備考
プロンプトキャッシュ	キャッシュされた読み取りで90％	キャッシュへの書き込みは1.25倍、読み取りは0.1倍のコストです。2回目の呼び出しで元が取れます。
Batch API	すべてのトークンで50％	レイテンシは24時間未満です。キャッシュと併用すると、合計で最大95％削減できます。
effort: low	大幅な削減	分類や抽出では、深い推論を省略します。
budget_tokens の上限	上限に応じて削減	ほとんどのタスクでは8K～16Kで十分です。日付の書式設定に100Kを使わないでください。
アシスタントのターンを事前入力	前置きを削除	{"role": "assistant", "content": "{"} を指定すると、「もちろんです！こちらが…」を省略できます。
トークン効率の高いツール	出力を平均約14％削減	Claude 4 ではデフォルトです。3.7 では token-efficient-tools-2025-02-19 ヘッダーを追加します。
動的なツール読み込み	ツール数に応じて拡張	すべてのリクエストに各ツールのスキーマが含まれます。タスクに必要なものだけを含めてください。
トークン数カウントエンドポイント	デバッグ用	推論を実行する前に正確なコストを確認できます。

キャッシュに関する重要な注意点：

• 画像はキャッシュを無効にします。 プロンプト内のどこであっても画像を追加または削除すると、キャッシュが無効になります。フローによって画像を送信する場合は、別のリクエストパターンとして扱ってください。
• キャッシュブレークポイントより前の内容は安定している必要があります。 タイムスタンプ、セッション ID、またはブレークポイントより前に置かれたユーザーメッセージがあると、キャッシュが完全に機能しなくなります。その結果、読み取りが一切ないまま、毎回1.25倍の書き込み追加料金が発生します。
• 並行処理の落とし穴。 キャッシュエントリが利用可能になるのは、最初の応答のストリーミング開始後です。10件のリクエストを並列に一斉送信すると、9件はキャッシュミスになります。まず1件送信し、ストリームの開始を待ってから、残りを並列に送信してください。
• ブレークポイントごとの最小トークン数に注意してください（Sonnet 4.6 は2,048、Opus 4.6 と Haiku 4.5 は4,096）。これを下回ると、キャッシュされず、エラーも発生しません。応答の cache_creation_input_tokens を確認してください。

詳細、料金の計算方法、TTL のトレードオフ、セットアップのチェックリスト：references/api-optimization-guide.md

すぐに実践できるチェックリスト

効果の高い順に適用してください。

1. 最初に /context を実行します → 変更前の基準値を確認できます
2. 大きなファイル（150行超）を分割して、目的別のモジュールにします → トークンを18％以上削減できます
3. CLAUDE.md を最適化します → 消費量を50～70％削減できる場合があります
4. タスクの切り替え時に /clear を使います → 無関係なコンテキストを取り除けます
5. 長い会話では /compact を使います → 履歴を圧縮できます
6. 出力が多いタスクにはサブエージェントを使います → テスト出力、ビルドログ、検索結果がメインの会話を汚さず、サブエージェントのコンテキスト内にとどまります
7. 適切なモデルを使います → 日常的な作業には Sonnet、簡単なタスクには Haiku（Opus より18倍安価）、本当に複雑なアーキテクチャ上の判断に限って Opus を使います
8. アクティブな MCP を10個以下に制限します → 使用していない MCP も、ツールの説明がすべてのリクエストに送られるため、ターンごとにトークンを消費します
9. /cost でコストを追跡します → セッションごとの支出を確認できます。ステータスラインを設定して、継続的に表示してください
10. API の利用者はプロンプトキャッシュを有効にします → システムプロンプトとツールに cache_control を設定すると、繰り返しの入力が90％割引になります。references/api-optimization-guide.md を参照してください

期待される節約効果

814 行の TypeScript 製 EC サイトアプリを使った、管理された実験の結果です。

最適化	効果
モジュール化されたファイル（対象を絞ったタスク）	トークン数 -18.2%
ノイズの削減（処理する行数）	-92%
最適化された CLAUDE.md	消費量 -50～70%
コンテキストの遅延読み込み	初期トークン数 -54%
Haiku と Opus の比較（簡単なタスク）	コスト -94%

重要なポイント： 対象を絞ったタスク（バグ修正や特定の変更など。日々の作業の約 80%）では、モジュール化されたコードが非常に効果的です。複数箇所にまたがるタスクでは、小規模な場合は差がほとんどありません（+1～5%）が、5,000 行を超えるとモジュール化が明確に優位になります。

規模に関する注記： これらの結果は、814 行のコードベースを使った管理された実験によるものです。より大規模なコードベース（5,000 行以上）では、モノリシックなファイルがコンテキストウィンドウの上限に達し始める一方、モジュール化されたファイルは一定のサイズ（各 35～146 行）を維持できるため、モジュール型アーキテクチャによる節約効果はさらに大きくなります。

実験方法の詳細と生データについては、references/metrics-report.md を参照してください。

診断ワークフロー

有効になったら、次の手順に従ってください。

0. まず測定する： 必ず最初に、ユーザーに /context を実行するよう依頼してください。基準となる数値がなければ、最適化の効果を証明できません。この手順は省略できません。
1. ユーザーのコードを読む： 何かを推奨する前に、実際のファイルとプロジェクト構成を確認してください。150 行を超えるファイルを探し、CLAUDE.md のサイズを確認し、アクティブな MCP の数を数えます。実際のコードベースに基づく推奨は、一般的なアドバイスよりはるかに役立ちます。
2. 特定する： 無駄の最大の原因を特定します（大きなファイル、肥大化した CLAUDE.md、蓄積したコンテキスト、多すぎる MCP など）。
3. 推奨する： クイック改善チェックリストから、最も効果の高い最適化を提案します。
4. 確認する： 変更後、ユーザーに /context を再実行してもらい、改善を測定します。

重要なガイドライン：

• 必ず最初に診断し、最適化をすべて一度に提示しないでください
• 変更前と変更後に測定し、すべての最適化を /context で確認してください
• ユーザー固有の問題に焦点を当て、最も効果の高い変更を最初に特定してください
• トレードオフを明確に伝えてください。モジュール化されたファイルは対象を絞ったタスクで 18% 以上を節約しますが、小規模な場合、複数箇所にまたがるタスクでは差がほとんどありません

使用例

「Claude Code のセッションが高くつくようになってきました」

1. /context を実行して、現在のトークン消費量の内訳を確認します
2. CLAUDE.md のサイズを確認します。500 行を超える場合は、必要な内容だけに絞ります
3. 150 行を超えるファイルを確認し、分割候補を特定します
4. アクティブな MCP の数を数え、使っていないものを無効にします
5. モデルの使用状況を見直し、定型的なタスクには Sonnet／Haiku に切り替えます

「AI 向けにコードベースを整理してください」

1. プロジェクト内で 150 行を超えるファイルをスキャンします
2. 汎用的なファイル名（ロジックを含む utils.ts、helpers.ts、index.ts）を特定します
3. 新しい説明的な名前を付け、責務ごとにファイルを分割する案を提示します
4. 整理ガイドに沿ったプロジェクト構成を提案します

「コンテキストウィンドウがすぐいっぱいになります」

1. /context を実行して、トークンを消費している要因を特定します
2. CLAUDE.md に、参照先として分離すべきインラインのドキュメントがないか確認します
3. タスクの合間に /clear を実行し、長いセッションでは /compact を使うよう推奨します
4. 冗長な内容を参照先ファイルに移す（遅延読み込み）ことを提案します

トラブルシューティング

問題	原因	解決策
最適化後も改善が見られない	最適化前の測定を行っていない	変更の前と後の両方で /context を実行します
使用中のトークン数がわからない	トークン消費量はデフォルトでは表示されない	/context を使って内訳をすべて確認します
/compact を実行しても十分に削減されない	圧縮されますが、必須情報は保持されます	以前のコンテキストが無関係な場合は /clear を使います
分割後、横断的なタスクに時間がかかる	複数回読み込む必要があるためです（トークンが1～5％増加）	想定内であり、影響はわずかです。作業の80％を占める集中的なタスクでは、引き続き18％以上削減できます
API：キャッシュが機能していないように見え、毎回書き込みが行われる	ブレークポイントより前のコンテンツがリクエストごとに変化する（タイムスタンプ、セッションID、ユーザーメッセージなど）、最小トークン数を下回っている、または画像が追加・削除されている	cache_creation_input_tokens を確認します。変動するコンテンツをブレークポイントより後に移動し、モデルごとの最小値を満たしてください
API：並列リクエストがすべてキャッシュにヒットしない	最初の応答のストリーミングが始まって初めて、キャッシュエントリが作成される	最初のリクエストを送信し、ストリームが始まるのを待ってから、残りのリクエストをまとめて送信します
API：思考トークンによってリクエストのコストが高くなる	デフォルトの budget_tokens が数万に達することがある	budget_tokens を8K～16Kに制限するか、effort: low を設定するか、書式設定や検索タスクでは思考を無効にします

参考資料

• references/file-organization-guide.md — 命名規則、プロジェクト構成のテンプレート、実装チェックリスト
• references/context-management-guide.md — 遅延読み込み、サブエージェント、MCP の管理、モデル選択の戦略
• references/metrics-report.md — 実験データと方法論の全容（生データを含む）
• references/claude-md-template.md — すぐに使える最適化済み CLAUDE.md テンプレート
• references/api-optimization-guide.md — 直接 API を利用するユーザー向けのプロンプトキャッシュ、Batch API、effort／思考予算、プレフィル、トークン効率のよいツール、モニタリング