Claude Codeのトークン消費を平均90%削減（bulk-read処理対象）— SpotifyがI/O処理を安価なモデルに委譲する仕組みを公開

9月5日、Spotify Engineeringが「Portal by Spotify cut my Claude Code token usage by 90%」と題した記事を公開した。AIコーディングエージェントのコスト急騰が現場のエンジニアリングリーダーにとって無視できない問題となる中、SpotifyはPortalに組み込まれたAiKA Modesを活用し、**bulk-read処理に限定した計測で平均約90%**のトークン削減を実現した手法を詳しく解説している。

AIコーディングエージェントのコストが急騰している。Gartnerの予測によれば、2028年までにAIコーディングコストは開発者の平均年収を超える見通しだ。すでにエンジニアリングリーダーの4分の1が、開発者1人あたり月200〜500ドルをトークン代として費やしており、2,000ドルを超えるケースもある。

問題の本質は、Claude Codeが「考える必要のない作業」に高コストのフロンティアモデルを使い続けることにある。複数ファイルの読み込み、既存パターンに倣ったテスト生成、ドキュメント更新――これらはすべてI/O処理であり、推論をほとんど必要としない。にもかかわらず、大量のトークンが消費される。

解決策：2つのモード、コード変更ゼロ

Spotify EngineeringはPortalのAiKA Modesを使い、この問題を解決した。PortalはSpotifyが開発・運用する社内向けAIエージェントプラットフォームで、複数のAIモデルやツールを統合管理する基盤として機能している。その上で動くAiKA Modesとは、宣言的に定義できるエージェント単位のことで、エフェメラルなランタイム（AWS Lambdaに近い概念）上で動作する。モデルの選択、温度パラメータ、MCPツールの接続などをYAML形式で記述するだけで動き、インフラ管理もAPIキーの管理も不要だ。

今回作成したモードは2つ。どちらもワーカーモデルとしてGemini 2.5 Flashを使用する。

Mode 1: bulk-reader

複数の大きなファイルを読んで1つの質問に答える、という作業を肩代わりするモード。

name: bulk-reader
description: Bulk file reader for code analysis - delegates I/O from Claude Code
instructions: You are a precise code analyst. Read the provided files and answer
  the question concisely. Output structured bullets only. No greetings, no prose,
  no preambles. Lead every bullet with the exact name, type, or line number. Use
  nested bullets for details. Skip anything the caller did not ask for.
visibility: public
model: gemini-2.5-flash
resourceLimits:
  temperature: 0.2
tags:
  - coding
  - delegation

Mode 2: code-writer

テストファイル、設定のスキャフォールディング、型スタブなど、既存パターンから予測可能な出力を生成するモード。

name: code-writer
description: Boilerplate code generator - delegates output-heavy work from Claude Code
instructions: You generate code files based on a spec and reference files. Match
  the existing patterns, conventions, naming, and style exactly. Output only the
  code — no explanations, no markdown fences unless asked. If the spec is ambiguous,
  make reasonable choices that match the reference code's patterns.
visibility: public
model: gemini-2.5-flash
resourceLimits:
  temperature: 0.2
tags:
  - coding
  - delegation

Output only the code という指示が重要で、これがないとモデルがMarkdownのコードフェンスや説明文を付与し、Claudeがそれをパースする余計なコストが発生する。

3層構造のルーティング

最初のバージョンはCLAUDE.mdにルーティングルールを書く方式だったが、「Claudeがルールを無視できる」「プロジェクトごとにコピーが必要」という問題があった。現在の実装はshuntというClaude Codeプラグインで、3層構造になっている。なお、shuntプラグインのリポジトリURLについては元記事内のリンクを参照されたい。

Layer 1: Hooks　Claude Codeのツール呼び出し前にフックが発火する。check-file-sizeは閾値（デフォルト350行）を超えるファイルの読み込みをブロックし、/bulk-readerスキルの使用を指示する。check-bash-readはcat、head、tailなどで大きなファイルを読む操作をキャッチする。閾値は環境変数SHUNT_MIN_LINESで調整可能だ。

{
  "env": {
    "SHUNT_MIN_LINES": "500"
  }
}

Layer 2: Scripts　Portal CLIをラップするbashスクリプト2本。bulk-readはファイルをXMLタグで囲んで送信し、code-writeは生成コードを直接ディスクに書き出す。Claudeは生成されたコードを一切参照しない。

bulk-read --question "What does this service do?" --paths src/Service.java src/Handler.java
code-write --spec "Write tests for UserService" --reference tests/OrderTest.java --target tests/UserTest.java

Layer 3: Skills　ClaudeにいつどうスクリプトをCallするかを伝えるMarkdownファイル。フックがリードをブロックした際、ブロックメッセージが/bulk-readerスキルの正確な呼び出し方法を指示する。スキルが読まれなくてもフックはブロックを続けるため、システムはグレースフルデグレードする。

実測：bulk-readで平均90%削減

Javaモノレポを対象に4シナリオでテストした結果、**bulk-readによるトークン削減量は平均約90%**。この数値はbulk-read処理のみを対象にした計測であり、code-writeを含む全体のトークン消費量の削減率とは異なる点に注意が必要だ。code-writeはClaudeが参照ファイルを読む+出力トークンを消費するコストを丸ごとなくすため、トークン換算が難しいが削減効果は同等以上とされている。

委譲できないこと

記事は限界も正直に書いている。編集は委譲できない。ワーカーモデルのサマリーに信頼できる行番号が含まれないためだ。推論も委譲できない。テスト中、ワーカーモデルは表面的なパターンしか見つけられず、微妙なスレッドセーフティのバグを見落とした。Claudeは適切なコンテキストを与えると数秒で発見している。レイテンシも無視できない。1回の委譲はネットワークのラウンドトリップが発生し、応答に10〜30秒かかる。このためライン閾値が存在する――小さいファイルでは委譲のオーバーヘッドが削減効果を上回る。

試し方

spotify/portal-ai-pluginsマーケットプレイスから2つのプラグインをインストール
新しいClaude Codeセッションで/portal:setupを実行し、Portal CLIを認証する。Portal CLIのインストール方法については元記事内の手順を参照されたい
複数ファイルにまたがる質問を投げかけるだけ

bulk-readerとcode-writerのモードはすでにパブリックで公開済みのため、自分で作成する必要はない。カスタマイズしたい場合はPortal上でフォークすると、自動的に自分のバージョンが優先される。

詳細はPortal by Spotify cut my Claude Code token usage by 90%を参照していただきたい。