とにかくToken圧縮をしたかった in CLAUDE.md

とある日、筆者は社内でのClaudeCode利用費にて頭を抱える事態となっていました。

コスト監視を怠っていた典型的な事例です。昔、ダイヤルアップ接続の従量課金で青ざめた経験を思い出しました。

既にMaxプランへの契約手続きは完了しており問題解消の見込みはありますが、それだけでは恐らく対応できない事象にも既に遭遇していました。

Error: File content (50836 tokens) exceeds maximum allowed tokens (25000). Please use offset and limit parameters to
read specific portions of the file, or use the GrepTool to search for specific content.

肥大化しがちなTokenを抑制するために試みたさまざまな対策について説明します。

ファイルの機能別分割

許可されるTokenの最大数に達するのは、単純なモックアプリに機能を次々と追加していくだけで簡単に起こります。分割時にはリンクや変数定義が原因で大抵機能不全を引き起こします。根気強く修正作業を行いましょう。

CLAUDE.mdには以下のように記載しておくと機能ごとに小さくファイルを分けていき、Tokenにも自然と余裕ができます。

ファイルは機能ごとに分割し、モジュール化を維持（500行を超える場合は分割を検討）

JavaScriptモジュール：1ファイルに1つの主要クラス・関数を配置

CSSファイル：コンポーネントや機能ごとに分割（例：modal.css、sidebar.css、editor.css）

バックエンドサービス：関心事の分離（ルート、ミドルウェア、データベース、ワーカー）

推奨ファイルサイズ：保守性のため500〜700行程度を目安とする

CLAUDE.mdの英訳

日本語文だけで記述するとToken消費が多くなります。約20行程度の日本語CLAUDE.mdファイルでも、英訳すると87-91%ものToken削減が可能です。

• CLAUDE.md（英語版）: 約81 tokens
• CLAUDE_ja.md（日本語版）: 約636-848 tokens

CLAUDE.mdを更新後、日本語に翻訳してCLAUDE_ja.mdを作成

後はTokenの利用量が少なくなる記述にするよう指示を入れておきましょう。文章ではなく単語での指示となりますが、案外問題なく動作してくれます。

日本語訳はAIではなく人用となるので、やや冗長な文章も許容しておくとよいでしょう。

参照用のログ出力

AIは動作修正のためにテストを独自に実行し、ログを確認することがあります。たとえ人があらかじめテスト用コマンドの末尾にteeを仕込み、事前にテストを実行していても、AIはそれを無視する傾向があります。

CLAUDE.mdでログフォルダを指定してテスト時に参照させるように指示しておきましょう。直近であれば読み込んでくれます。

なお、teeコマンドを含むテスト実行は、独自の名前を付けておくと安全です。例えば npm run test_tee 等。この対策を怠ると、AIが以下のような標準コマンドを実行した場合にテストファイル修復のためにTokenが過剰に消費されてしまいます。

npm run test — test/test.ts

あとがき

これらの対策を実施するだけで、作業中にToken関連のエラーに遭遇する頻度を大幅に減らせます。覚えておくべき重要な点は、CLAUDE.mdはAI向けの文書であり、人間が読むためのものではないということです。