token-optimization

トークン最適化

概要

トークン使用量の削減は、単一の工夫だけで実現することはほとんどありません。適切なレイヤーで小さな改善を積み重ねる必要があります。このスキルはトリアージマップです。トークンがどこで使われているか（システムプロンプト、会話履歴、ツールの結果、エージェントのループ、出力の冗長さ）を診断し、それに合った対策を示します。最適化の正しい目標は、リクエストあたりのトークン数ではなく、タスクあたりのトークン数です。問題を解決する1回限りの12kトークンのプロンプトは、30ターンかかる2kトークンのループよりも優れています。対策は順に適用してください。まず測定し、次にキャッシュし、その後に圧縮、モデルの振り分けを行い、最後に出力を削減します。

有効にするタイミング

• ✅ ユーザーがコンテキスト上限に達した、請求額に驚いた、またはループが遅いと伝えた場合
• ✅ ユーザーがプロンプトキャッシュ、圧縮、または拡張思考の予算の使い方を尋ねた場合
• ✅ ユーザーがより低コストのモデルを選ぶ、または複数のモデルに作業を分割する方法を知りたい場合
• ✅ エージェントが、長時間実行されているセッションでコンテキストウィンドウの使用率が約70%を超えたことに気付いた場合（目安となるトリガーです。正確なカウントが利用可能な場合はそれを使用し、それ以外の場合はヒューリスティックな推定を使用してください。余裕が重要な長時間セッションでは早めに、短いタスクでは遅めにトリガーしてください）
• ✅ 重く感じられるシステムプロンプト、CLAUDE.md、またはメモリファイルをレビューする場合

次の場合は有効にしないでください：

• 特定のトークナイザーライブラリが話題の場合（tokenization-* スキルを使用してください）
• 「トークン」が認証／JWT／決済用トークン、または UI デザイントークンを指す場合
• ユーザーが料金の計算だけを求めている場合（プロバイダーの料金ページを案内してください）

ワークフロー

以下の順序で対策を適用してください。各レイヤーは手軽に試せ、次のレイヤーとは独立しているため、コストまたはコンテキストの目標を達成した時点で停止してください。

ステップ 1 — トークンの使用箇所を測定する

最適化する前に、コストの発生源を特定します。1回のリクエストについて、プロンプトを次の5つのバケットに分け、それぞれの割合を推定してください。

バケット	内容	合計に占める一般的な割合
システム／ロール	静的なシステムプロンプト、CLAUDE.md、AGENTS.md、メモリファイル	5 – 40%
ツール定義	各ターンに挿入されるツールスキーマ	5 – 30%
会話履歴	以前のユーザー／アシスタントのターン	10 – 50%
ツールの結果	ファイルの読み取り、検索結果、コマンドの標準出力	20 – 70%
現在のユーザーメッセージ＋出力	このターンのリクエストと応答	5 – 20%

ヒューリスティックな推定（実際のトークナイザーは不要）：

• 英語の文章：tokens ≈ words × 1.3
• コードまたは混在テキスト：tokens ≈ chars / 4
• CJK／マルチバイト文字：tokens ≈ chars / 2

精度はおおよそ±15%です。Claude／Anthropic SDK のコンテキストで正確にカウントするには、実際の呼び出しの前に SDK の count_tokens エンドポイントを使用してください。詳細な予算計算（出力の倍率、深度ティア）については、references/measurement-and-budgets.md を参照してください。

出力：割合の大きいバケットを1～2個示してください。どのバケットが大きいかによって、以下のどのステップを重点的に行うかが決まります。

ステップ 2 — 静的なプレフィックスをキャッシュ可能にする

呼び出しを繰り返す場合、最大の効果が得られるのはプロンプトキャッシュです。安定したプレフィックス（システムプロンプト＋ツール定義＋長い参照ドキュメント）は一度ハッシュ化され、キャッシュの TTL 内に行われる以降のリクエストで大幅な割引価格で再利用されます。これを活用するには、次のようにします。

• 安定した内容はすべてプロンプトの先頭に置き、変化する内容（ユーザーの現在の質問、最新のツール結果）は末尾に置きます。キャッシュ検索では、完全に一致するプレフィックスが照合されます。
• 最も大きな安定ブロックの末尾にキャッシュブレークポイントを設定します。Anthropic SDK では、そのプレフィックスの最後のコンテンツブロックに cache_control: {type: "ephemeral"} を設定します。
• 呼び出し間でプレフィックスをバイト単位で一致させます。ツール定義の並べ替え、タイムスタンプの挿入、メモリファイルのシャッフルを行うと、キャッシュが無効になります。
• ファイル内容のブロックがターンをまたいで同じキャッシュエントリにヒットするよう、読み取り順を安定させてまとめます。

プレフィックスを変更する必要がある場合でも、以前のメッセージをその場で編集してはいけません。代わりに、更新後の状態を含む新しいメッセージを追加します。これにより、以前のすべての呼び出しのキャッシュされたプレフィックスが有効なまま保たれます。

変更	誤り（キャッシュが無効になる）	正しい方法（キャッシュを維持）
サンドボックス／権限モード	以前の権限メッセージを編集する	新しいモードを含む role=developer メッセージを追加する
作業ディレクトリ	以前の環境メッセージを編集する	cwd の変更を知らせる新しい role=user メッセージを追加する
ツールリストへの追加	以前のツール定義を並べ替える、または書き換える	末尾に追加する。新しいツールは次の呼び出しからキャッシュが開始される
MCP tools/list_changed	会話の途中でホットリロードする	会話の区切りまで更新を延期するか、キャッシュミスを受け入れる

その場で編集すると、キャッシュがすでにハッシュ化したバイト列が書き換わり、それ以降の呼び出しがすべてキャッシュミスになります。追加にかかるコストは、新しいメッセージのトークン分だけです。上記の role=developer／role=user などのロール名は Anthropic 向けの表記です。他のホストでは、相当するロール区分を使用してください。

プロバイダーごとのキャッシュの仕組み（TTL、最小ブロックサイズ、課金動作）については、references/prompt-caching.md を参照してください。

ステップ 3 — 常時読み込まれるコンテキストを減らす

CLAUDE.md、AGENTS.md、GEMINI.md、.cursorrules、メモリインデックスなどのファイルは、すべてのメッセージに挿入されます。5,000 トークンのメモリファイルを 100 件のメッセージで読み込むと、純粋なオーバーヘッドだけで入力トークンが 500,000 個になります。

目標と削減対象：

ファイル	目標予算	よくある肥大化の原因
最上位の指示ファイル（CLAUDE.md／AGENTS.md）	< 1,500 トークン	既定の動作の繰り返し、長いフレームワークリスト、段落形式の例
メモリインデックス	< 3,000 トークン	内容のインライン記述。各項目は1行の参照情報にする
スキルごとの指示	< 5,000 トークン	複数のスキルにまたがる説明の重複

簡潔にするためのルール：

1. 既定の指示を削ります。「役に立つアシスタントとして振る舞う」「読みやすいコードを書く」などは、モデルがすでに実行できます。
2. 重複する箇条書きを統合します。「簡潔にする」＋「冗長にしない」＋「回答を短く保つ」→ 1つの箇条書きにします。
3. 例を参照ファイルに移します。 例は常時読み込まれるペイロードを肥大化させます。オンデマンドで読み込む references/<topic>.md ファイルに移します。
4. 段落ではなく箇条書きにします。 短くなり、より確実に解析されます。
5. 使っていないエージェントやスキルを削除します。 メモリエントリが2週間参照されていない場合、削除候補です。
6. MCP スタイルのツールサーバーを監査します。 有効なサーバーはそれぞれのツール定義をすべてのターンに挿入します。各サーバーに5～10個のツール定義があるサーバーを10個使うと、ターンごとのオーバーヘッドは簡単に5,000トークン以上になります。さらに難しい最適化に取り組む前に、有効なサーバーのリストと実際の使用状況を照らし合わせ、直近の数セッションで呼び出されていないサーバーを無効にしてください。プロジェクトごとに有効なサーバーを約10個までにするのが、オーバーヘッドを抑えるための目安です。ただし、数よりも機能が重要です。タスクに必要なものは残してください。同等の機能を持つ CLI バイナリがある場合は、そちらを優先してください（例：GitHub MCP サーバーではなく gh）。

Step 4 — 会話履歴を圧縮する

長時間のセッションでは、古いターンが蓄積していきます。履歴のトークン数が Step 1 の集計で大きな割合を占める場合は、段階的な圧縮ポリシーを適用します。

• 直近の 3～5 ターン：そのまま保持します。
• 6～10 ターン前：決定事項と結論を残し、中間の推論は削除します。
• それ以前：各ターンを 1 行で要約します。ただし、具体的な推論が現在のタスクを支えるうえで引き続き重要なターンは、そのまま保持します。
• 修正後の失敗したツール呼び出し：失敗に関するノイズは削除し、修正内容を残します。
• 編集によって置き換えられた大きなファイルの読み込み：最終状態だけを残します。

圧縮したプロンプトの先頭に主な目標を明記し、圧縮中にモデルが目標を見失わないようにします。システム指示や安全性に関するヘッダーは、決して削除しないでください。構造化要約のテンプレートとアーティファクトの履歴に関するルールについては、references/context-management.md を参照してください。

不安を抑えるための調整。 コンテキストウィンドウを認識できる最先端モデルは、残りのコンテキストを実際より少なく見積もり、作業を急ぎ始めることがあります。たとえば、早すぎる要約や近道のための判断、タスクの途中で「仕上げましょう」と切り上げることなどです。次の方法で対処します。

• 長時間のセッションでは、ウィンドウの上限を大幅に下回る使用量を目指します（例：100 万トークンのウィンドウに対し、アクティブなコンテキストには約 20 万トークンを割り当てます）。この余裕はモデルの安心感を支えるための緩衝領域であり、厳格な上限ではありません。タスクに本当に必要な場合は拡張してください。
• 圧縮したスナップショットの冒頭付近に、明示的な予算を記載します（キャッシュ可能な静的プレフィックスには記載しないでください。Step 2 のルールに反します）。例：「コンテキスト予算：残り約 18 万トークンです。引き続き十分な深さで作業してください。」
• 実作業が明らかに残っているのに、タスクの途中で突然要約したり「仕上げましょう」と切り上げたりする兆候があれば、モデルに任せるのではなく予算を再提示します。切り上げが適切な場合、つまりタスクが完了した場合やコンテキストが本当に逼迫している場合は、そのまま仕上げてもらいます。

これはモデル側の挙動であり、ホスト側の挙動ではありません。コンテキストを認識できるモデルを実行するあらゆるホストに適用されます。

Step 5 — 冗長なツールの観測結果をマスクする

ツールの出力は、トークン数が際限なく増える最大の要因です。冗長な結果を、モデルが必要に応じて再取得できる観測結果への参照に置き換えます。

• ファイルの読み込みに成功 → [read src/foo.ts: 312 lines, exports: a,b,c]
• 検索に成功 → [grep "X": 7 hits in 4 files: …]
• 長いコマンドの標準出力 → 先頭と末尾の各 5 行に終了コードを加えて残します。
• スクリーンショット／画像 → タスクに支障のない最低解像度に縮小します。UI スクリーンショットでは通常、1280×720 が最適です。文字が密集している場合や、OCR で判読性が重要な場合は 1920×1080 以上に引き上げます。一般的な UI 作業では、4K 全体を使うと必要以上に約 5 倍のトークンを消費します。

これはマスキングであり、削除ではありません。元のファイルやコマンドには引き続きアクセスでき、モデルがすべてのターンでデータを保持する必要がなくなるだけです。

Step 6 — 適切なモデルを選ぶ

タスクの複雑さに応じてモデルを使い分けます。あらゆる呼び出しで最大のモデルを選ぶことが、過剰なコストの最も一般的な原因です。

タスク	推奨ティア
ステータス確認、応答確認、分類、簡単な検索	最小／最安のティア（例：Haiku クラス）
ファイルの読み込み、オートコンプリート、Lint、フォーマット、単一ファイルの編集	小規模ティア
複数ファイルの編集、デバッグ、テスト生成	中規模ティア（例：Sonnet クラス）
アーキテクチャ設計、複数ステップの計画、大規模なリファクタリング、非常に長いコンテキスト	最上位ティア（例：Opus クラス）

レート制限や遅延へのバックオフに備えて、フォールバックの順序（最上位 → 中規模 → 小規模）を用意します。サブエージェントが利用可能な場合は、対象を絞った検索やファイルのスキャンを低コストなモデルのサブエージェントに委任し、統合した結果だけをメインループに返します。メインループが検索結果の生データに対してコストを支払う必要はありません。

ステップ 7 — エージェントループのオーバーヘッドを削減する

ループを 1 回繰り返すたびに、会話コンテキスト全体が再送信されます。反復回数を減らすと、効果は倍増します。

• ツール呼び出しをまとめる。 独立したツール呼び出しは、複数ターンに分けて順番に実行するのではなく、1 回のアシスタントターンで並列に実行します。
• 小さなタスクをまとめる。 N 回の反復を開始するのではなく、1 回の反復で N 個のファイルを処理します。
• 反復回数に上限を設定する。 1 つの失敗した操作の再試行回数に上限（例：約 5 回）を設け、「要約して停止」する明確な終了処理を用意します。一方で、正当に複数ステップが必要な計画には、必要な長さで実行できる余地を残します。
• 推測に基づく読み取りを避ける。 「関連するものすべて」ではなく、タスクに必要なものを読み取ります。ファイルを開く前に glob／grep を使って対象を絞り込みます。
• 時間のかかるジョブはバックグラウンドで実行する。 数分かかるタスクで、モデルをポーリングループにとどめないでください。ウェイクアップをスケジュールするか、ホストのバックグラウンド実行機能を使用します。

プラットフォーム固有のパターン（Anthropic SDK での並列ツール呼び出し、Claude Code でのサブエージェントへの委任、Codex での Task ツール）については、references/agent-loop-patterns.md を参照してください。

ステップ 8 — 出力を簡潔にする

出力トークンは通常、入力トークンより高い料金が設定されています。次の方法を試してください。

• 詳細度の段階を提示する。 長文の質問に答える前に「要点／標準／詳細／徹底」の選択肢を提示し、ユーザーが明確に示した意図に沿う最小の段階をデフォルトにします。意図が曖昧な場合は、回答不足になるより 1 段階上を選びます。
• 前置きは省き、方向性は示す。 内容のない前置き（「もちろんです。こちらが……です」「素晴らしい質問です！」など）は省きます。「Z のため、X を Y に更新しました」のように、方向性を 1 行で示すのは問題なく、多くの場合役に立ちます。目標は前置きを削ることであり、文脈を取り除くことではありません。
• 機械処理には構造化出力を使う。 JSON／ツール使用スキーマは、同等の文章より通常短く、前置きも不要です。
• 停止シーケンスを使う。 既知の終端文字列で有用な出力の終わりを定められる場合は、それを設定します。モデルはその文字列に達すると生成を停止します。
• 思考量に上限を設ける。 拡張思考に対応したモデルでは、思考予算を明示的に設定します（例：通常のタスクでは 1k～4k トークン、より大きな予算は本当に難しい問題のために確保します）。

詳細度段階のテンプレート、つなぎ表現の削除リスト、停止シーケンスのレシピ、思考予算の調整表については、references/output-and-verification.md を参照してください。

ステップ 9 — 効果を検証する

成功を宣言する前に、ステップ 1 と同じ分類で再測定し、差分を報告します。

Before: input=N1, output=M1, est cost C1
After:  input=N2, output=M2, est cost C2
Delta:  -X% input, -Y% output, -$Z per call

差分がわずかであれば、支配的だった分類は最適化したものとは異なります。新たに測定し直して、ステップ 1 に戻ってください。

再測定用の完全なテンプレート（複数回の最適化ラウンドを追跡するための CSV 形式を含む）、差分がわずかな場合のトラブルシューティング表、タスクあたりのトークン数と呼び出しあたりのトークン数の検証方法、最適化を完了と判断する終了条件については、references/output-and-verification.md を参照してください。

期待される範囲。 保証値ではなく、調整の目安として使用してください。

• コンパクション：品質低下 5% 未満で、50～70% の削減。
• マスキング：マスクされた観測の 60～80% を削減。
• プレフィックスキャッシュヒット率：安定したワークロードで 70% 以上。

差分がこれらの範囲の上限に近い場合、一般的なワークロードではその手法の効果が逓減する領域に入っています。さらなる改善には、1 つの手段を強めるのではなく、複数の手法を組み合わせてください。

エージェント間の呼び出し

上記の手法はエージェントに依存しませんが、適用するためのコマンドはホストのランタイムによって異なります。次の表を使って、手法を現在のホストに合わせてください。

手法	Claude Code	Codex CLI	Cursor	Gemini CLI	Copilot CLI
コンテキストをリセットする（Step 4）	/clear	/clear	新しいチャット	/clear	新しいセッション
手動で圧縮する（Step 4）	/compact	手動で要約のみ	n/a	n/a	n/a
自動圧縮のしきい値（Step 4）	CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=<pct>（env）	n/a	n/a	n/a	n/a
モデルを切り替える（Step 6）	/model sonnet|opus|haiku	--model <id> フラグ	モデルピッカー	/model <id>	--model <id>
サブエージェント／委任先モデル（Step 6）	CLAUDE_CODE_SUBAGENT_MODEL=<id>（env）	タスクごとのモデル引数	n/a	サブエージェント設定	n/a
思考予算に上限を設定する（Step 8）	MAX_THINKING_TOKENS=<n>（env）	推論レベルフラグ	n/a	思考設定	n/a
トークン使用量を確認する（Steps 1, 9）	/cost	セッションのフッター	ステータスバー	/stats	gh copilot usage
プレフィックスキャッシュ（Step 2）	自動＋cache_control SDK フラグ	完全一致するプレフィックスでは自動	自動	暗黙的なコンテキストキャッシュ	プロバイダー経由

注記：

• 環境変数はホストランタイムの設定ファイルに適用されます（例： Claude Code の場合は ~/.claude/settings.json の env ブロック）。ほかのホストには、 それぞれ独自の設定場所があります。
• n/a は、現在そのホストの CLI では機能が公開されていないことを意味します。 基盤となる手法は、プロバイダーの SDK を直接使用すれば適用できる場合があります。
• MCP スタイルのツールサーバーは、対応するすべてのホストで、ツール定義のトークンを消費します。有効にする数は控えめにしてください（プロジェクトあたり約 10 個が妥当な上限です）。指示ファイル全体をさらに見直す方法については Step 3 を参照してください。

ルール

厳守すべきルール（決して違反しないこと）：

• 圧縮中にシステム指示、安全性に関するヘッダー、コンプライアンスに関する文言を削除しないでください。 コンテキストの喪失を利用したジェイルブレイクは現実的なリスクです。
• 意図せず安定したプレフィックスを無効化しないでください（たとえば、 先頭にタイムスタンプやランダム ID を挿入するなど）。呼び出しごとに値を変える必要がある場合は、 末尾に配置してください。
• 最適化の対象はタスクあたりのトークン数であり、リクエストあたりのトークン数ではありません。 ループ回数が 5 倍になるのに、呼び出しあたり 30％削減できたと喜ばないでください。
• 指示を削除するとユーザーに見える動作が変わる場合は、モデルが「知っているはず」という理由だけで その指示を削除しないでください。実際の例で検証してください。

推奨事項（変更可能）：

• 記載された順序で手法を適用し、目標を達成した時点で止めてください。
• 大量のコンテンツをインラインで出力するより、モデルが再読み込みできるファイルパスを参照する方法を優先してください。
• 呼び出しを繰り返す場合は、キャッシュ可能なプレフィックスの最適化が、通常ほかの単独の変更より効果的です。
• 2 つの手法のどちらを選ぶべきか迷った場合は、キャッシュの利点を得るため、プロンプトの末尾ではなく先頭を短くする方法を選んでください。

出力

このスキルが生成するのは、診断と優先順位を付けた手法の一覧であり、機械的な書き換えではありません。想定される引き継ぎ内容は次のとおりです。

1. 現在のトークン使用量を分類して測定した結果（Step 1）。
2. 使用量の大部分を占める項目に最も効果が見込める、Steps 2～8 の手法 2～3 個。
3. ユーザーが採用または却下できる、具体的な変更案（システムプロンプトの差分、キャッシュのブレークポイント配置、モデルのルーティングルールなど）。
4. 変更適用後の再測定（Step 9）。

抽象的な利用者は、このセッションをホストしているエージェントランタイム（Claude Code、Codex、Cursor、Gemini CLI、Copilot）のいずれかです。プロバイダー固有の機能（cache_control、思考予算、サブエージェント）を参照する手法には、参照ファイル内でプロバイダーを示すタグが付いています。

段階的な開示

詳細な情報はサブフォルダーに保存されており、必要に応じて読み込まれます。

• references/measurement-and-budgets.md — ステップ 1 で読み込みます。ヒューリスティックによる推定と正確な推定、複雑さに基づく 出力倍率、深度層ごとの計算方法。
• references/prompt-caching.md — ステップ 2 で読み込みます。キャッシュブレークポイントの配置、TTL、ブロックの最小 サイズ、無効化のトリガー、キャッシュミスのデバッグ。
• references/context-management.md — ステップ 3～5 で読み込みます。例を交えたスリム化ルール、圧縮用の構造化 サマリーテンプレート、観測内容をマスクするパターン、画像の 解像度に関するガイダンス。
• references/agent-loop-patterns.md — ステップ 6～7 で読み込みます。モデルルーティングの判断表、ツール呼び出しを 並列化するパターン、サブエージェントへの委任、反復回数の上限、バックグラウンド ジョブのパターン。
• references/output-and-verification.md — ステップ 8～9 で読み込みます。深度層選択テンプレートと既定の層を選ぶ ヒューリスティック、つなぎのフレーズの削除リスト、構造化出力の経験則、 ユースケース別の停止シーケンス集、思考予算の 調整表、再計測テンプレート（CSV 版を含む）、 差分が無視できる場合のトラブルシューティング表、「最適化完了と判断する タイミング」の終了条件。

v1 では assets/ と scripts/ は含まれません。トークン数の推定はヒューリスティックで、 インラインで説明しています。プロジェクトで後から正確なカウントが必要になった場合は、 ホストプロバイダーの count_tokens エンドポイントを直接呼び出してください。

本文の予算

目安であり、厳密な上限ではありません。トピックに十分な理由があれば本文を増やし、情報を 切り捨てるのではなく、超過分を references/<topic>-extras.md に移してください。

• description：agentskills.io の仕様では 1,024 文字が上限です。これはソフトな目安ではなく、 外部で定められた厳密な上限です。
• 本文：読みやすい長さとして、約 500 行／約 5,000 トークンを目指してください。
• ファイル全体のサイズ：Copilot のカスタムエージェントとして再レンダリングしたときも本文を 正しく解析できるよう、約 30,000 文字を大幅に下回るようにしてください。