9月4日、Spotify Engineering Blogが「Portal by Spotify cut my Claude Code token usage by 90%」と題した記事を公開した。AIコーディングエージェントのトークン消費を大幅に削減するモデルルーティング手法を、Spotifyの内製ツール「Portal by Spotify」を使った実装例とともに詳しく解説している。
AIコーディングコストの深刻さは数字が示している。エンジニアリングリーダーの4分の1がすでに開発者1人あたり月200〜500ドルをトークンに費やしており、2,000ドルを超えているケースも存在する。Gartnerの予測では2028年までにAIコーディングコストが平均的な開発者の給与を超えるとされており、コスト最適化は多くのチームにとって喫緊の課題となっている。
問題の核心：トークンを食い潰しているのは「思考」ではなく「I/O」だ
Claude Codeに限らず、AIコーディングエージェントの仕事の大半は推論ではない。1つのメソッドについて質問に答えるために5ファイルを読む、隣接する20のテストファイルと同じパターンでテストを生成する——そうした「単純なI/O作業」に大量のトークンが消えている。
解決策として記事が提示するのは「フロンティアモデル（Claude）に全作業をやらせず、安価なモデルに委譲できる作業を振り分ける」というモデルルーティングだ。Spotifyが開発する開発者ポータルツール「Portal by Spotify」の機能「AiKA Modes」を使えば、これをコードゼロで実現できる。
Portal by Spotifyは、SpotifyがOSSとして公開している開発者ポータルフレームワーク「Backstage」をベースに構築された内製ツールで、外部にも提供されている。AiKAはPortalに組み込まれたAIエージェント機能群の総称で、ここではエージェントの動作を宣言的に定義する「Modes」という仕組みを活用する。
AiKA Modesとは
AiKA Modesは、宣言的に定義するエージェントだ。AWS Lambdaのようなエフェメラルなランタイム上で動作し、指示・モデル・temperatureパラメータ・MCPツールを設定ファイルに記述するだけで動く。インフラ管理不要、APIキー管理不要、長時間稼働するサーバーも不要。Portal CLIまたはAPIから呼び出せ、全社共有（public）またはプライベートで運用できる。
2つのModeで90%削減を実現
記事では、Javaモノレポを対象に測定した結果、Claudeが直接ファイルを読む場合と比較して**平均トークン削減率は約90%**だったと報告している。ワーカーモデルにはいずれも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層構造になっている。
Layer 1: Hooks（強制的な介入）
Claude Codeのツール呼び出し前にフックを発火させる。check-file-sizeは読み取り対象が設定行数（デフォルト350行）を超えると読み取りをブロックし、/bulk-readerスキルを使うよう指示する。cat file | grepのようなパイプコマンドはターゲットを絞った読み取りなので通過させる。
Layer 2: Scripts（Portal CLIのラッパー）
Claudeが名前付き引数でスクリプトを呼び出す。リクエストの構築からエラー処理、stderrへのトークン使用量レポートまでスクリプトが一括処理する。
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
code-writeを使うと生成されたコードをClaudeのコンテキストに載せずに直接ディスクに書き込める。これがコード生成でのトークン削減の核心だ。
Layer 3: Skills（いつ・どう呼ぶかの説明）
Claudeに呼び出しタイミングと構文を教えるmarkdownファイル。フックが読み取りをブロックしたとき、ブロックメッセージがClaudeを/bulk-readerスキルに誘導する。Claudeがスキルの説明を読まなくても、フックが高コストな読み取りをブロックするためシステムはグレースフルに機能低下する。
委譲できないこと
記事は限界についても率直に書いている。
- 編集の委譲は不可：ワーカーモデルのサマリーには信頼できる行番号が含まれないため、編集が必要な場合はClaudeが直接ファイルを読む必要がある
- 推論の委譲は不可：テスト中、ワーカーモデルは表面的なパターンを検出したが、微妙なスレッドセーフティのバグを見逃した。デバッグ・アーキテクチャ判断・安全性の高いコードは明示的にルーティング対象外とする
- レイテンシのオーバーヘッド：各委譲はネットワークの往復を伴い、応答に通常10〜30秒かかる。Portal側の単一呼び出し上限も30秒で、非常に大きな生成は複数回に分ける必要がある。行数閾値が存在するのはこのためだ
導入方法
インストールは3コマンドで完了する。
claude plugin marketplace add spotify/portal-ai-plugins
claude plugin install portal@portal
claude plugin install shunt@portal
インストール後、新しいClaude Codeセッションで/portal:setupを実行してPortalインスタンスに対してCLIを認証する。bulk-readerとcode-writerはすでにパブリックModeとして公開されているので自分で作成する必要はなく、カスタマイズしたい場合はPortalでフォークすれば自動的に自分のバージョンが優先される。
詳細はPortal by Spotify cut my Claude Code token usage by 90%を参照していただきたい。
