Claude Codeを使い始めて、最初に驚くのは便利さだ。コードを書いてくれる、エラーを直してくれる、リファクタリングも提案してくれる。
でも、請求書を見て二度驚く人も多いんじゃないだろうか。
「思ったより高くない？」
その原因、実はコードを書かせている部分じゃないかもしれない。
・Claude Codeの請求額が想定より高い
・何にトークンを使っているか分からない
・節約したいけど、どこを削ればいいか見当がつかない
そんな人ほど、この記事を読んでほしい。
CLAUDE.mdが「毎回まるごと読まれている」という事実
Claude CodeにはCLAUDE.mdという設定ファイルがある。プロジェクトのルール、コーディング規約、アーキテクチャの概要なんかを書いておくと、AIがそれを踏まえて応答してくれる仕組みだ。
これ自体はすごく便利な機能なんだけど、落とし穴がある。
CLAUDE.mdは、リクエストのたびに全文が読み込まれる。
READMEのタイポを直してもらうだけの簡単なお願いでも、CLAUDE.mdに書いた数千トークンの設定が丸ごとコンテキストに入る。毎回。例外なく。
海外のある開発チーム（9人体制）の事例では、CLAUDE.mdが約10,000トークンまで膨れ上がっていたそうだ。40以上のDjangoアプリのアーキテクチャ文書、コーディング規約、APIリファレンス、セッションメモ——半年かけて育ったCLAUDE.mdが、毎リクエストで全文注入されていた。
元記事の著者の試算では、1人あたり1日約60リクエスト × 9人 × 10,000トークン = 月間540万トークンがCLAUDE.mdだけで消費されていた計算になる。コードを1行も書かせる前に、だ。
これを知ったとき、正直ゾッとした。
プロンプトキャッシュが効かないパターンがある
Anthropicにはプロンプトキャッシュという仕組みがある。1,024トークン以上のプロンプトが前回と同一なら、キャッシュから読んでコストを大幅に下げてくれる機能だ。
「じゃあCLAUDE.mdが大きくても、キャッシュが効くから大丈夫でしょ？」
って思うじゃないですか。自分もそう思ってました。
キャッシュが効くのは、プロンプトが完全に同一の場合だけだ。1文字でも違えばキャッシュミスになり、フルプライスで請求される。
つまり、CLAUDE.mdにタイムスタンプ付きのセッションメモや、環境ごとに変わるパス情報が入っていると、リクエストのたびに内容が微妙に変わる。結果、キャッシュは毎回ミスする。毎回フル課金。
元記事のチームでは、キャッシュヒット率がわずか12%だったそうだ。これでは仕組みがあっても意味がない。
自分がやった対策：CLAUDE.mdの「ダイエット」
自分もClaude Codeを日常的に使っていて、設定ファイルの肥大化は身に覚えがあった。プロジェクトの情報をどんどん追記していくと、あっという間に膨れ上がる。
そこでやったのが、CLAUDE.mdの分割だ。
考え方はシンプルで、常に読み込む必要がある情報と、必要なときだけ参照すればいい情報を分ける。コアとなる最低限のルールだけをCLAUDE.mdに残し、詳細なリファレンスは別ファイルに切り出して、必要なときだけ読ませる構造にした。
さらに、設定の記述を英語に統一した。日本語はトークン効率が悪く、同じ内容でも英語の2〜3倍のトークンを消費する。設定ファイルは人間が読むためのものじゃなく、AIが読むためのものだ。ここは割り切って英語にした方が圧倒的にコスパがいい。
この2つだけで、毎リクエストで消費されるトークン量はかなり減った。地味な作業だけど、効くんですよ。地味な作業が。
claudectx：トークン浪費を可視化するオープンソースツール
元記事のチームは、この問題を解決するためにclaudectxというCLIツールを開発してオープンソースで公開している。
使い方は簡単で、プロジェクトディレクトリで以下を実行するだけだ。
`
npx claudectx analyze
`
インストール不要。これだけで、CLAUDE.mdのトークン数、開いているファイルのトークン数、会話履歴のトークン数が一覧表示される。さらに「ここが無駄ですよ」という警告も出してくれる。
主な機能は3つある。
- analyze: トークンの内訳を可視化。CLAUDE.mdが推奨の2,000トークンをどれだけ超えているか、キャッシュを壊す動的コンテンツがないかをチェックしてくれる
- optimize: CLAUDE.mdを自動で分割し、
.claudeignore（不要ファイルの読み込みを防ぐ設定）を生成し、キャッシュを壊すコンテンツを除去する。処理前のファイルは自動バックアップされるので安心だ - watch: リアルタイムでトークン消費量とキャッシュヒット率をモニタリングできるダッシュボード
元記事の著者によると、optimizeを実行した結果、1リクエストあたりのトークンが18,432から3,740に減少（約80%削減）、キャッシュヒット率は12%から74%に改善、月額コストは約87ドルから約17ドルまで下がったそうだ。
ただし、これは「CLAUDE.mdが異常に大きく、.claudeignoreも未設定」という状態からの改善なので、すでにある程度整理している環境なら20〜40%の削減が現実的なラインだと思う。
ツールに頼る前に、まず自分でできること
claudectxは便利だけど、ツールを入れる前にまず手動でできる対策がある。これだけでもかなり効果がある。
1. CLAUDE.mdの棚卸し
今すぐCLAUDE.mdを開いて、本当に毎回読ませる必要がある情報だけ残す。「いつか使うかも」で残している記述は、毎リクエストのコストになっている。書いた本人は忘れていても、AIは律儀に毎回読んでいる。
2. 動的コンテンツの排除
タイムスタンプ、セッションメモ、環境変数のパスなど、リクエストごとに変わる可能性がある内容は別の場所に移す。これだけでキャッシュヒット率が劇的に変わる。
3. .claudeignoreの設定
node_modules、dist、ロックファイル、画像ファイルなど、AIに読ませる必要がないファイルを除外する。.gitignoreと似た仕組みだ。設定していないと、Claude Codeがこれらのファイルまで読みに行ってトークンを消費する可能性がある。
4. 日本語→英語への切り替え（設定ファイルのみ）
CLAUDE.mdの内容を英語で書く。記事の本文やコメントじゃなく、あくまでAIへの指示書の話だ。日本語で500トークンの内容が、英語なら200トークン程度で済むこともある。これ、半年前に知ってたら相当節約できてた。
Claude Codeの「見えないコスト」を意識する時代
Claude Codeの課金は、多くの人が「AIにコードを書かせた分」だと思っている。でも実際には、設定ファイルの読み込み、不要なファイルの参照、キャッシュミスによる重複課金——こうした「見えないコスト」が請求額のかなりの割合を占めている可能性がある。
これはClaude Codeに限った話じゃない。Cursor、GitHub Copilot、その他のAIコーディングツールでも、コンテキストウィンドウの管理は今後ますます重要になる。AIツールの性能が上がるほど、「何を読ませるか」の設計がコストと品質の両方を左右する。
まとめると、こうだ。
- CLAUDE.mdは毎リクエストで全文読み込まれる。肥大化はそのままコスト増に直結する
- 動的コンテンツはキャッシュを殺す。設定ファイルから排除するだけでキャッシュヒット率が跳ね上がる
- まずは手動で棚卸し、次にツールで最適化。
npx claudectx analyzeで現状を把握するだけでも価値がある
AIツールの請求書を見て「高いな」と感じたら、コードの書かせ方じゃなくて、設定ファイルの太り具合を疑ってみてほしい。急所は意外とそこにある。
【PR】フリーランスエンジニアにおすすめのツール
Misoca — クラウドで見積書・請求書をサクッと作成。フリーランスの事務作業を最小限にできる。
Value Domain レンタルサーバー — 開発用途にも対応するレンタルサーバー。コスパ重視で選びたい人向け。
コメント