入力コスト90%減を維持する5分ルール。Claude Codeのコンテキスト最適化。

5分で消えるキャッシュとコストの罠

AIエージェントの入力コストを90%オフにする条件がある。

それは5分以内に次の指示を出すことだ。

エージェントの提案に対して人間が考え込むと、コストは12.5倍に跳ね上がる。

無駄なやり取りでコンテキストが肥大化すると、AIは記憶を圧縮し始め、キャッシュが壊れ、再び課金メーターが回り出す。

コーディングエージェントの性能を引き出すには、プロンプトの工夫だけでは足りない。

エージェントが読み込む「コンテキストの質と量」を設計する技術が求められる。

※この記事は、Claude Codeで1人SaaS開発しているしんたろーが、海外AI最新情報を開発者目線で解説する「AI活用Tips」です。

分断された3つのニュースが示すコンテキストの最適化

コンテキスト管理に関する3つの重要な検証とツールが、同時期に報告された。

これらは別々の話題に見えて、実は「エージェントのコンテキストをどう最適化するか」という共通の課題に向き合っている。

5 分以内に返事しよう は、プロンプトキャッシングの過酷な仕様を暴いた。

Claude Codeはデフォルトでキャッシングが自動的に有効になっている。

キャッシュにヒットすれば、入力コストは0.1倍で済む。

しかし、キャッシュの有効期限（TTL）はわずか5分だ。

人間がコードの確認で5分間フリーズすると、キャッシュは消滅する。

次のリクエストで全トークンが書き込み直しとなり、コストは1.25倍かかる。

さらに厄介なのが、コンテキストの肥大化によるキャッシュの破壊だ。

会話が長引いてコンテキストウィンドウの上限に近づくと、自動要約（compaction）が走る。

メッセージ履歴が書き換えられるため、キャッシュの照合に失敗し、再び大量のトークン消費が発生する。

このコンテキスト肥大化を防ぐアプローチとして、入力データの圧縮が注目されている。

PeopleXのブログ JSONよりトークン効率の良いTOONというフォーマットがあるらしい では、新しいデータ表現TOONの検証が行われた。

TOONは、JSONの無駄を削ぎ落としたシリアライゼーションフォーマットだ。

JSONでは配列内のオブジェクトごとに同じキー名が何度も繰り返される。

TOONでは最初にヘッダとしてキー名を一度だけ宣言し、以降はCSVのように値だけをカンマ区切りで並べる。

この構造により、JSONと比較してトークン消費を約40%削減できる。

ネストされたデータも、YAMLのようなインデント表記とテーブル形式を自動で使い分けてコンパクトに表現する。

そして3つ目のピースが、外部知識の正確な注入だ。

Andrew NgのチームがContext Hubを公開した。

これはコーディングエージェント専用の、最新APIドキュメントレジストリだ。

LLMの学習データは過去のものであり、最新のAPI仕様を知らない。

古いパラメータを幻覚（ハルシネーション）してエラーを繰り返す現象は「Agent Drift」と呼ばれている。

Context Hubは、エージェントがウェブを彷徨う代わりに、軽量なCLIを通じて正確なマークダウンドキュメントを直接取得できる仕組みを提供する。

これら3つの情報を並べると、次世代のコーディング作法の輪郭が見えてくる。

トークンを削り、正確な仕様を渡し、テンポ良く対話する。

開発者目線で読み解くコンテキスト管理

AIエージェントとのペアプログラミングは、新しいフェーズに入った。

「コードを書かせる」段階から、「エージェントの脳内メモリを管理する」段階への移行だ。

Claude Codeのプロンプトキャッシングは、プレフィックス一致で動作する。

照合順序は、ツール定義、システムプロンプト、そしてメッセージ履歴の順番だ。

途中で内容が1文字でも変わると、それ以降のキャッシュはすべて無効化される。

Claude Codeを立ち上げたままコーヒーを淹れに行くと、戻ってきた時のリクエストでAPI代が跳ね上がるらしい。人間側のレスポンス速度がコストに直結する仕様、完全にAIのペースに巻き込まれている。コーヒーメーカーの前で「5分以内に戻れるか」を計算する日が来るとは思わなかった。

システムプロンプトの一部として読み込まれる「CLAUDE.md」の扱いもシビアだ。

セッションの途中でこのファイルを編集すると、システムレベル以降のキャッシュが吹き飛ぶ。

プロジェクトのルールを書き足しただけで、次のリクエストのコストが12.5倍になる。

だからこそ、コンテキストに「何を入れないか」が問われる。

TOONフォーマットの登場は、この文脈において極めて合理的だ。

LLMに渡すデータ構造や要件定義をJSONで書くと、無駄なトークンでコンテキストが埋め尽くされる。

TOONを使って入力を約40%削減できれば、自動要約（compaction）が発生するまでの猶予が延びる。

キャッシュが長持ちすれば、ランニングコストは下がる。

ただし、TOONには明確なトレードオフが存在する。

現在の主要なLLMは、事前学習データにTOONの構文を含んでいない。

出力フォーマットとして指定するには、Few-shotプロンプトで構文を教え込む必要があり、かえってコンテキストを消費する。

入力用フォーマットと割り切るのが正解だ。

人間が用意した固定のデータ定義や初期設定ファイルをTOONに変換して渡す。

エージェントからの出力は、扱い慣れたJSONのまま受け取る。

JSONだと無駄なキー名でコンテキストが埋まるのが気になっていた。TOONの記法なら人間もギリギリ読める構造で、入力用フォーマットと割り切るアプローチはトークン節約の観点で理にかなっている。ただし自分でTOONを書き始めると、結局JSONに戻りたくなる未来が見える。

そして、コンテキストの質を担保するのがContext Hubだ。

エージェントが古いAPI仕様に基づいてコードを書き、エラーを吐き、修正を試みる。

この無駄な試行錯誤のループこそが、コンテキスト肥大化の最大の原因だ。

エラーログと修正案でメッセージ履歴が埋め尽くされると、すぐに自動要約が走る。

キャッシュが壊れ、コストがかさみ、最終的にエージェントは文脈を見失う。

Context Hubの「chub」コマンドを使えば、エージェントは最新の仕様をピンポイントで引き出せる。

さらに強力なのが、ローカルへのアノテーション機能だ。

特定のAPIでバグを回避する独自の実装を見つけたとする。

エージェントは「chub annotate」コマンドを使って、そのノウハウをローカルのレジストリにメモとして保存できる。

次回以降、そのAPIのドキュメントを取得する際、保存したメモが自動的に追記される。

Stripeのような頻繁に仕様が変わるAPIを触る時、エージェントが古いパラメータでエラーを出し続ける挙動が気になっている。公式ドキュメントをその都度コピペする手間が省けるなら、ローカルのドキュメントレジストリという概念は手放せなくなりそうだ。ただし「chub annotate」を使いこなせる前に、自分がAnnotateされそうな気もする。

エージェントに長期記憶を持たせることで、同じエラーによるコンテキストの浪費を防ぐ。

トークンを圧縮し、正確な知識を与え、迷走をなくす。

エージェント開発における具体的なアクション

これらの仕様を踏まえ、日々の開発フローをどう変えるか。

コンテキスト最適化の実務的なアプローチは以下のようになる。

まず、Claude Codeとの対話リズムを変える。

エージェントがコードの修正案を提示してきたら、5分以内に判断を下す。

迷った時は、空の返信や「続けて」という短い指示を投げてキャッシュの有効期限をリセットする。

人間がじっくりコードを読みたい時は、別のエディタで確認作業を行う。

その間、ターミナル上のエージェントは待機状態になるが、5分経過する前に何らかのコマンドを打つ。

この小さな意識の差が、月末のAPI利用料に直結する。

次に、プロジェクトの前提知識の渡し方を見直す。

「CLAUDE.md」には、プロジェクト全体の不変のルールだけを記述する。

ここに特定のライブラリの細かい仕様や一時的なタスクを書き込むと、コンテキストが急速に圧迫される。

データ構造の定義や初期データの注入には、TOONフォーマットを活用する。

既存のJSONファイルを変換スクリプトでTOONに変換し、それをエージェントに読み込ませる。

これだけで入力トークンを約40%削減でき、キャッシュの寿命を延ばせる。

APIの仕様確認は、エージェントのウェブ検索に頼らない。

Context Hubを導入し、エージェントに「chub」コマンド経由でドキュメントを取得させる。

古い知識による幻覚（ハルシネーション）を防ぎ、一発で正しいコードを生成させる環境を整える。

タスクの切り替えも見逃せない。

関連性のない新しい機能を実装する時は、必ずクリアコマンド（/clear）を実行する。

メッセージ履歴だけをリセットすることで、ツール定義とシステムプロンプトのキャッシュは維持したまま、肥大化したコンテキストを掃除できる。

エージェントに「考えさせる」のではなく、「正しい文脈を与える」ことにリソースを割く。

入力データを圧縮し、最新の仕様を注入し、テンポ良く対話する。

コンテキストのコントロール権を人間が握り続ける。

AI活用Tips FAQ

Q1: Claude Codeのプロンプトキャッシングを有効にするには設定が必要ですか？

いいえ、Claude Codeではプロンプトキャッシングがデフォルトで自動的に有効になっている。

ユーザー側での特別な環境変数の設定やコマンドラインオプションの追加は一切不要だ。

ただし、キャッシュの有効期限（TTL）は5分間に固定されている。

5分以内に次の指示を出し続けることで、キャッシュヒットによる入力コスト90%オフの恩恵を継続して受けることができる。

Q2: TOONフォーマットはLLMに出力させることも可能ですか？

技術的には可能だが、基本的には「LLMへの入力用フォーマット」として使用することが推奨される。

現在の主要なLLM（Claude、ChatGPT、Geminiなど）の事前学習データにはTOONの構文が含まれていない。

そのため、出力させるにはFew-shotプロンプトなどで構文ルールを詳細に教え込む必要があり、かえってトークンを消費する原因になる。

出力フォーマットとしては、モデルが扱い慣れているJSONを指定する方が動作が安定する。

Q3: Context Hub (chub) はどのようにしてエージェントに長期記憶を持たせるのですか？

Context Hubには「chub annotate」という強力なコマンドが用意されている。

エージェントが特定のAPIのバグ回避策や仕様の癖を発見した際、それをローカルのドキュメントレジストリにメモとして保存できる。

次回以降、エージェントがそのAPIのドキュメントを「chub get」で取得する際、保存したメモが自動的に追記されて出力される。

これにより、セッションを跨いでも過去の知見が引き継がれ、同じ問題で再びつまずくのを防ぐ仕組みだ。

コンテキストを制する者がAI開発を制する

キャッシュの寿命を意識し、トークンを削り、正確な仕様を注入する泥臭い管理が開発速度を決める。

👉 ThreadPostでSNS運用を自動化する