Claude Codeを使った開発におけるトークン節約術

本記事は、IVRy Advent Calendar 2025「IVRy AIブログリレー Part2」23日目の記事です。昨日は清水文明（@Fumiaki_Shimizu）が「コールセンターにおけるAI活用」を書きました。こちらもぜひご覧ください！

https://adventar.org/calendars/11552

はじめに

IVRyでモバイルエンジニアとして働いているAmemiyaです。最近、バックエンド含め複数のリポジトリを統合したモノレポ環境での開発が増えたことで、ある課題に直面しました。

「コンテキスト（トークン）の消費が激しすぎる」

Claude CodeなどのAIエージェントは非常に便利ですが、リポジトリが巨大になればなるほど、その構造を理解するために大量のトークンを消費します。起動するだけで数万トークン、少し探索させただけであっという間にコンテキストウィンドウ（例: Claude opus4.5 - 200k）の上限に近づいてしまいます。

そしてコンテキストウィンドウが圧迫されると、「記憶の喪失」が起きます。

トークンが上限に近づくと、Claude Code は 自動的に/compactコマンドを実行 し、過去の会話履歴を要約して空き容量を作ります。しかし、この圧縮プロセスで「詳細な文脈」や「最初に読み込ませた重要な指示」が失われてしまうことがあります。

そこで今回、実際のモノレポ開発環境を用いて、「何がトークンを消費しているのか」「どうすれば削減できるのか」を検証しました。

結論から言うと、以下の2点を徹底することで、無駄な探索やメモリ消費を削減し、コンテキストの寿命を延ばすことができました。

1. プロンプトに具体的なパスを含める。ignoreするパスも含めるとより効果的（探索コストの削減）

2. CLAUDE.md は簡潔に保ち、@ 記法の乱用を避ける（公式も簡潔で人間が読みやすい形式にすること、とある）

本記事では、その検証結果の詳細と具体的な実践方法を共有します。

検証

検証環境

ツールは Claude Code v2.0.75 (Claude 4.5 Opus)

対象プロジェクトはIVRyの実務で使用しているリポジトリで、それらをモノレポ化しています。

• Backend Server (API周り)
• AI対話システム
• Web UI (管理画面など)
• Mobile App (受電や管理画面など)

システム概要は以下になります。

https://speakerdeck.com/ivry/ivry-culture-deck-for-engineers?slide=24

測定方法

Claude Code の /context コマンドを使用し、以下の指標を測定しました。

1. 起動時トークン … 何もしない状態で消費される固定コスト
2. タスク実行トークン … 特定の指示を与えて完了するまでの消費量
3. 探索回数 … AIが実行した ls, Search, Read などのツール呼び出し回数

検証① プロンプトの具体性

AIエージェントを使う際、「とりあえずざっくり指示して、あとはAIに考えてもらおう」としがちです。しかし、モノレポにおいてその「思考（探索）」のコストは、対話を重ねるごとに雪だるま式に膨れ上がります。

実際の開発（実装→修正→テスト）を想定した3つの連続タスクで、累積トークン消費量がどう変化するかを測定しました。

比較したシナリオ

曖昧コース … 「ポイント機能実装して」 → 「エラーになるようにして」 → 「テスト書いて」丸投げ指示の繰り返し。

具体コース … 「backend/app/services/point_service.rb を作成して、add_points メソッドを実装して...」ファイルパスや仕様を具体的に指定しながら進行。

測定結果

ステップ	曖昧コース	具体コース	差分
Start	63k	63k	-
Task 1（実装）	91k (+28k)	88k (+25k)	3k
Task 2（修正）	105k (+14k)	94k	11k
Task 3（テスト）	107k	95k	12k

3つのタスクを終えた時点で 12,000トークン（コンテキストの約6%）もの差がつきました。「たった6%」と思うかもしれませんが、長時間のセッションになれば、この差がコンテクストウィンドウの占有を早める決定打になります。

Anthropic の 公式ベストプラクティス でも "Be specific"（指示を明確にする）と強調されている通り、AIにとって最もコストがかかるのは「コードを書くこと」ではなく「探索」です。ファイルパスを明示するだけで、コンテキストの寿命は確実に延びます。

検証② パス記法による「遅延ロード」

Claude Codeには、プロジェクト固有の知識を与える CLAUDE.md という仕組みがあります。公式ドキュメント によると、CLAUDE.md はディレクトリ階層ごとに配置でき、作業中のディレクトリに応じて適切なファイルが読み込まれる仕様になっています。

しかし、便利な @ 記法（ファイル内容の展開）も使い方を誤ると大量のトークンを浪費します。

CLAUDE.md に記載された内容は起動時にすべて読み込まれるため、無制限にファイルを追加すると、何もしていない段階でコンテキスト（トークン）を圧迫してしまいます。

比較したシナリオ

1. 即時ロード（@記法） … CLAUDE.md 内に @docs/architecture.md と記述
2. 遅延ロード（パス記法） … CLAUDE.md 内に「詳細は docs/architecture.md を参照」と記述

測定結果

• 即時ロード（@記法） … Memory files 1,900 トークン
• 遅延ロード（パス記法） … Memory files 117 トークン（未読込）
• 削減率 93.8%

なぜパス記法なのか？

@ 記法を使うと、Claude Code は起動時にそのファイルの中身をすべて展開し、コンテキスト（Memory files）に常駐させます。常に参照する必須ルールなら良いですが、特定のタスクでしか使わないドキュメントまで暗記させるのは無駄です。

一方、「詳細は path/to/doc.md を参照」と書いておくと、Claude は「そのファイルに情報があること」だけを学習します。そして実際にその情報が必要になったタイミングで初めて Read ツールを使って読みに行きます。

つまり、CLAUDE.md は「知識の保管場所を示す地図」として機能させるべきです。すべての情報を詰め込むのではなく、ポインタ（パス）を示すことで、初期ロード時間を短縮し、トークンを節約できます。

まとめ

今回の検証から、探索させないことが効果的であることがわかりました。

1. 探索させない（プロンプトの具体性）

「何かやって」 ではなく 「どこ（ファイルパス）の何（関数・クラス）をどうして」 と伝える。連続タスクで 12,000トークン（コンテキストの約6%） の差がつきました。

2. 暗記させない（CLAUDE.md の簡潔化）

CLAUDE.md には詳細を書かず、詳細ドキュメントへのパス（地図） を書く。
@ 記法は起動時に全展開されるため、Memory files を 94% 削減できます。

💡 TipsMCP サーバーを追加している場合、それ自体もトークンを消費します。使っていない MCP は /mcp で確認するとトーク節約に寄与します。

最後に

自分も曖昧な指示を出しがちで、compact による会話内容の喪失が起きたり、結果として Claude Code の weekly limit に当たることがありました。

とはいえ、知見のないリポジトリでは具体的な指示を出すこと自体が難しい場面もあります。幸い、直近のアップデート (v2.0.74) で LSP (Language Server Protocol) ツール が標準で追加され、コード探索の効率が向上しました。今回の検証では具体的なプロンプトの方がトークン効率が良かったですが、今後はこうした機能の進化により、曖昧な指示でも最小限のトークン消費で開発できるようになっていくかもしれません。

それでも今できる工夫として、本記事の内容が参考になれば幸いです。

キャリア登録 / カジュアル面談

IVRy では「イベントや最新ニュース、新着ポジションの情報を受け取りたい」「会社について詳しく話を聞いてみたい」といった方に向けて、キャリア登録やカジュアル面談の機会をご用意しています。ご興味をお持ちいただけた方は、ぜひ以下のページよりご登録・お申し込みください。

https://ivry-jp.notion.site/209eea80adae800483a9d6b239281f1b?pvs=105

https://herp.careers/v1/ivry/wmZiOSAmZ4SQ

関連求人はこちら

https://herp.careers/v1/ivry/SiflmzT9SNfb

https://herp.careers/v1/ivry/3Fbz-fIeJEuR