AIコーディングエージェントのトークン使用量を削減する方法

AIコーディングエージェントのトークン使用量を減らすには、コンテキストに入る情報を減らします。読むべきファイルを明示する、プロジェクトの指示ファイルを簡潔に保つ、コードを書く前に計画を求める、検索は自分で実行する、セッションをこまめにリセットする、タスクに不要なツールをオフにする、といった方法があります。

多くの人がこの問題に向き合うのは、リファクタリングの途中でセッションが使用量上限に達したときや、作業量は変わらないのに請求額が倍になったときです。

これらの習慣は、Claude Code、Codex、Cursor などのエージェントで同じように機能します。以下の各セクションでは、習慣が効果を持つ理由、そのまま使える短い例、そして根拠が実測によるものか推論に基づく実践かを示します。

AIコーディングエージェントのトークン使用量を削減することはなぜ重要なのか？

トークンのコストは二重にかかります。一つは請求額や使用量上限、もう一つは出力の品質です。AIコーディングエージェントが読んだファイルと保持している過去のターンはすべてコンテキストに残るため、最も安いトークンはエージェントが一度も読まずに済むトークンです。また、コンテキストが小さく関連性が高ければ、モデルが無関係な情報に気を取られることも減ります。無駄のないセッションは、肥大化したセッションより安価で、精度も高くなるのが普通です。

たとえば「リポジトリ全体を調べて」という指示で始まるデバッグセッションでは、エージェントが実際のバグにたどり着く前に、無関係なファイルを何十個も読み込むことがあります。そのすべてに料金が発生し、モデルはそれらを踏まえたうえで推論しなければなりません。

エージェントが見る範囲を絞る

AIコーディングエージェントの探索的なファイル読み込みを減らすには、リポジトリ全体を指示するのではなく、読むべきファイルを指定します。指定しないとエージェントはファイルを探し回り、その途中で開いたファイルはすべてコンテキストに入ります。ファイルを指定すれば、読み込みはタスクに必要な範囲に限られます。

# Before
Why is the checkout total wrong? Look through the repo.

# After
The total in src/cart/total.ts is wrong when a discount code is applied.
Read src/cart/total.ts and src/cart/discounts.ts only. Do not open other files
without asking.

エージェントがアクセスできる範囲そのものを制限することもできます。エージェンティックコーディング用のリモートボックス環境のように専用マシンで動かす場合は、タスクに必要なリポジトリだけをクローンしましょう。

プロジェクト指示ファイルを用意する

プロジェクト指示ファイル（通常は AGENTS.md または CLAUDE.md）を用意しておけば、AIコーディングエージェントがセッションのたびにプロジェクトの規約を調べ直す必要がなくなります。ほとんどのエージェントがこのファイルに対応しているので、どのファイル名を読み込むかはエージェントのドキュメントで確認してください。Claude Code は CLAUDE.md を読み込みます。メモリに関するドキュメントによると、v2.1.277 以降はリポジトリに CLAUDE.md がない場合、AGENTS.md も直接読み込みます。

この方法には具体的な根拠があります。OpenAI Codex を使い、10リポジトリ・124件のプルリクエストを対象とした研究では、AGENTS.md ファイルがある場合、実行時間の中央値が28.64%短く、出力トークン数の中央値が16.58%少なくなりました。一方、同じ結果表では、総トークン数の中央値はほぼ変わらず、ファイルがある場合のほうがむしろ約1%多くなっています。つまり、このファイルの主な効果はエージェントの出力を減らし、作業を早く終わらせることであり、読み込む量全体を減らすものではありません。また、この研究には限界があります。対象は1つのエージェント（gpt-5.2-codex で動作する Codex）のみで、小規模なマージ済みPR（変更行数100行以下、ファイル数5つ以下）だけを扱っており、出力の正しさも十分には評価されていません。

ファイルは簡潔に保ちましょう。Claude Code はセッション開始時に CLAUDE.md をコンテキストに読み込むため、すべての会話で全行分のコストが発生します。Anthropic は200行未満に抑えることを推奨しており、Claude は長い指示や曖昧な指示より、短く具体的な指示のほうを確実に守ると述べています。

# AGENTS.md

## Project
Web API for order processing. Entry point: src/server.ts.

## Structure
- src/routes/: HTTP handlers, one file per resource
- src/services/: business logic; handlers never touch the DB directly
- tests/: mirrors src/; test files end in .test.ts

## Conventions
- Run `npm test` before proposing changes; run `npm run lint` on touched files
- Use the logger in src/lib/log.ts, never console.log
- Do not edit generated files in src/generated/

コードを書く前に計画を求める

コードを書く前にAIコーディングエージェントに計画を求めると、ファイルの読み込みや書き換えが始まる前に方向性の誤りに気づけます。計画を破棄するコストはほぼゼロです。一方、誤った実装に気づいた時点では、すでに関係したすべてのファイル分のトークンが消費されています。計画には、作業開始前に絞り込めるファイルの一覧が含まれるという利点もあります。

Before writing any code: list the files you intend to read and change, and
the steps you will take, in under 10 bullets. Wait for my approval.

計画に関係のないファイルが含まれていたら、承認する前にリストから外しましょう。

検索は自分で実行し、結果を渡す

grep を自分で実行して該当行を貼り付ければ、エージェントが消費するのはその行の分だけです。同じ検索をエージェントに任せると、途中で開くすべてのファイル分のコストがかかる場合があります。git grep や git diff などのツールは高速で、実行にトークンを消費しません。検索はこれらのツールで行い、モデルには結果だけを渡しましょう。

# Find every call site yourself
git grep -n "applyDiscount(" -- '*.ts'

# See only what changed, not whole files
git diff --stat
git diff -- src/cart/total.ts

そのうえで、出力を貼り付けて指示します。「applyDiscount の呼び出し箇所は次の4つです：[貼り付けた行]。currency 引数を渡すように更新してください。」

Spotify はこの習慣を自動化した仕組みを構築しています。Claude Code によるファイルの一括読み込みを安価なワーカーモデルに任せ、Claude には要約だけを渡すというものです。Spotify のエンジニアがJava のモノレポで4つのシナリオを使ってテストしたところ、Claude 自身がファイルを読む場合のトークン数と、ワーカーの要約を読む場合のトークン数を比べた結果、一括読み込みでの削減率は平均約90%でした。ただし、この数値は1つのコードベースに限られ、ワーカーモデルのトークンは含まず Claude のコンテキストのみを数えたもので、一括読み込みのシナリオだけが対象です。Spotify Engineering の記事には制約も挙げられています。要約には信頼できる行番号が含まれないため編集には直接の読み込みが必要なこと、推論とデバッグは Claude が担うこと、委譲のたびにレイテンシが増えることです。

セッションは短く保ち、新しく始める

1つの会話を伸ばし続けるのではなく、タスクごとに新しいセッションを始めましょう。長い会話では、新しいメッセージのたびに履歴全体が送られるため、古いスレッドを続けると不要になったコンテキストにも課金され続けます。Anthropic の Claude Code のコストに関するガイダンスでは、API またはクラウドプロバイダーのプランで支出が想定を上回る場合、主な原因は一度もクリアされなかったセッションか、デフォルトモデルのまま使われている Opus だとしています。また、無関係なタスクの合間にクリアすることを、特に効果の大きい習慣の一つに挙げています。

# End of session 1
Summarize in under 15 lines: what we changed, what we decided, what is left.
Write it to NOTES.md.

# Start of session 2 (new chat/session)
Read NOTES.md, then continue with the first remaining item.

要約で決定事項は残り、新しいセッションではそこに至るまでの履歴が破棄されます。

タスクに不要なツールや連携をオフにする

連携を有効にするたびに、エージェントが読み込むものや使える機能が増えます。タスクに不要な連携は無効にしましょう。特に影響が大きいのは MCP サーバーです。現在の Claude Code は、Claude が必要とするまで MCP ツールの完全な定義を読み込まないため、使われていないサーバーのコストは以前より小さくなりました。それでも、ツール名と指示はコンテキストに含まれます。Anthropic の Claude Code のコストに関するガイダンスでも、/mcp を実行して使っていないサーバーをオフにするよう勧めています。先月接続したデータベースサーバー、ブラウザ自動化サーバー、チケット管理の連携は、CSS しか扱わないセッションでは余計な負荷になります。

1ファイルのリファクタリングなら、エージェントの設定でデータベース、ブラウザ、課題管理のサーバーをオフにし、必要なタスクのときに再びオンにしましょう。各サーバーが何を公開しているかわからない場合は、MCP エコシステムのガイドでクライアントとサーバーの関係を確認できます。独自のサーバーを保守している場合は、MCP サーバーをステップバイステップで構築するで、自分で定義したツールだけを公開する方法を紹介しています。

まとめ

結論

トークンコストはコンテキストのサイズに比例して増えます。Claude Code のようなエージェントはリクエストのたびに会話全体を再送信するため、読み込まれ、再び読み込まれるコンテキストのコストはすぐに膨らみます。上記の習慣はいずれも、コンテキストを小さく、タスクに沿った内容に保つことで効果を発揮します。まず1つを選び、送信しようとしているプロンプトとファイルを LLM トークンカウンターに貼り付けて、変更前後のトークン数を比べてみましょう。計測しなければ、削減効果は推測にすぎません。

よくある質問

エージェントセッションのコンパクト化とクリアの違いは何ですか？

コンパクト化は古い会話履歴を要約に置き換えてセッションを続けるもので、クリアは履歴を破棄して新しいコンテキストで始めるものです。Claude Code では、要約を作るためにモデルが会話全体を読む必要があるため、大きなコンテキストのコンパクト化はそれ自体が大きなリクエストになります。一方、クリアにコストはかかりません。以前の決定事項がまだ重要なタスクの途中ではコンパクト化を、無関係なタスクの合間にはクリアを使いましょう。

使っていない MCP サーバーも Claude Code でトークンを消費しますか？

以前よりは少なくなっています。Claude Code はデフォルトでツール検索を使います。起動時にモデルが参照するのは各サーバーのツール名と指示だけで、ツールの完全なスキーマはタスクで必要になったときに取得されます。ただし、ANTHROPIC_BASE_URL がファーストパーティ以外のホストを指している場合、Azure 上でホストされる Microsoft Foundry のデプロイメントの場合、Claude 4.5 世代より古い Google Cloud の Agent Platform のモデルの場合は、最初にすべてを読み込む方式に切り替わります。alwaysLoad が指定されたサーバーも完全に読み込まれます。また、どのサーバーのツール出力もコンテキストに入ります。

安価なモデルに切り替えるとトークン使用量は減りますか？

いいえ。安価なモデルで変わるのはトークンあたりの価格で、トークン数は変わりません。エージェントは同じファイルを読み、同じ履歴を再送信します。ただし、2つの手段は組み合わせることで効果が重なります。Anthropic の Claude Code のコストに関するガイダンスでは、作業に合ったモデルを選ぶことと、無関係なタスクの合間にクリアすることを、支出削減に最も効果の大きい習慣として挙げています。

Claude Code 内でトークン使用量を確認するにはどうすればよいですか？

/usage を実行するとセッションのコスト、プランの使用量上限、アクティビティの統計を確認でき、/context を実行すると現在のコンテキストウィンドウを占める内容の内訳を確認できます。Pro、Max、Team、Enterprise プランでは、/usage は直近の使用量の10%以上を占める使い方（長いコンテキストなど）を指摘し、削減方法も提案します。表示される金額は常に定価から計算した推定値で、サブスクリプションの場合は実際の支払額を示すものではありません。