Claude Code でトークンを燃やさずに Statnive を出荷する方法

初めて `/context` を実行したとき、残量は 12% でした

Statnive は、プライバシー重視の WordPress アナリティクスプラグインを出荷する小さなチームです。私たちのコードベースには 2 つの git submodule (プラグインとマーケティングサイト)、80 以上の Claude Code スキル、24 個の MCP コネクタ、そしてリリース前に 141 件のテストと 31 件のコンプライアンスチェックを実行するリリースゲートがあります。

最初の 2 か月は AI 支援開発が魔法のように感じました。やがてそれが高価に感じ始めました。セッションがタスク途中でタイムアウトしました。モデルは 5 分前に読んだことを忘れているように見えました。当社の Anthropic 請求はエンジニア 1 人で 1 日 $6 を超えました。

初めて /context を実行し、その理由を理解しました。プロンプトを 1 つも入力する前に、すでにコンテキストウィンドウの 88% を使用していたのです。実作業のために残っていたのは 12% でした。

本記事は、スキルもコネクタも 1 つも落とさずに、そのオーバーヘッドを概ね 3 分の 2 削減した方法と、現在すべてのリリースをゲートする 4 つの数字の話です。

ヘッドラインの数値: 〜54K トークンのベースラインオーバーヘッド (〜175K から低下)、実作業のための 〜73% のコンテキストウィンドウ、日次支出は 〜$6 から〜$2〜3 へ低下。

200K トークンに実際に何が住んでいるのか

Claude Code は 200K トークンのコンテキストウィンドウを提供します。最初のメッセージ前に何が消費しているかを理解するまでは、これは寛大に聞こえます。

コンポーネント	内容	未最適化	当社の目標
システムプロンプト	組み込みの Claude Code 命令	〜3,200	〜3,200
組み込みツール	Read、Write、Bash、Grep、Glob、Edit	〜11,600	〜11,600
ルート CLAUDE.md	プロジェクト命令、常時読み込み	8,000+	≤ 1,500
スキルメタデータ	`<available_skills>` エントリ	4,000+	≤ 2,500
MCP ツールスキーマ	24 コネクタ × 多数のツール	48,000〜120,000	≤ 3,000
自動コンパクトバッファ	予約ヘッドルーム	32,000	32,000

これらのうち 3 行が戦いのすべてです。常時読み込みの CLAUDE.md、スキルメタデータレジストリ、MCP ツールスキーマのダンプです。それ以外はハーネスによって固定されています。

裏のメカニズムは段階的開示です。Claude Code のスキルシステムは、起動時に各スキルの name と description フィールドだけ — スキルあたり 30〜50 トークン — を読み込み、完全な SKILL.md 本体はスキルが実際に呼び出されるまで遅延します。同じ仕掛けが、設定すれば MCP ツールスキーマと参照ドキュメントにも効きます。設定しなければ、すべてのツール定義、すべてのルール、すべての命令が永遠にコンテキストに座ります。

MCP ツールオーバーヘッドが最大の漏れだった

初めて /context を実行するのは謙虚になる体験です。何も触る前に見たものは:

MCP コネクタ	ツール数	消費トークン
GitHub	35	〜26,000
Playwright (ブラウザ自動化)	21	〜13,647
Slack	11	〜21,000
Context7 (ライブラリドキュメント)	〜15	〜8,000
その他 20 個のコネクタ	〜200	〜60,000+

これら 5 行だけで、ファイルを開く前にコンテキストウィンドウの概ね 60% を消費していました。問題はアーキテクチャです。すべての MCP ツールスキーマ — 名前、説明、完全な JSON パラメータ定義 — はデフォルトでセッション開始時にコンテキストへ注入されます。Docker の MCP サーバーは 135 ツールを出荷し、単独で〜126,000 トークンを消費します。

私たちのために 85% の仕事をした修正は、MCP Tool Search をオンにすることでした。Claude Code v2.1.7 で出荷されたもので、Tool Search はツール名と説明の軽量な〜5K トークンのインデックスを構築し、Claude が実際にツールを呼び出すときだけ完全なスキーマを読み込みます。Anthropic の内部テストでは 134K から〜5K トークンへ — 85% の削減を示しつつ、MCP 評価における精度は向上しました (Opus 4: 49% → 74%)。

有効化はツールの説明がコンテキストウィンドウの約 10% を超えると自動的に行われますが、私たちは /context 経由ですべてのセッションで有効であることを確認し、「tool search enabled」の行を確認します。

ビフォーアフターの数値と eager に保った 3 つのコネクタについては、MCP Tool Search の専用記事で詳しく書きました。

CLAUDE.md: 800 行ではなく、162 行

スキルや MCP ツールと違い、CLAUDE.md の 1 バイト残らずがすべてのセッション開始時にコンテキストへ読み込まれ、遅延読み込みは存在しません。これはルートファイル、@path/to/file 構文経由のすべてのインポート (再帰的に最大 5 レベル)、すべてのグローバル・エンタープライズファイルを含みます。

最初の CLAUDE.md は 820 行ありました。すべてのスキル、ワークフロー、コーディング標準、リリースゲート、WordPress Coding Standards 設定のすべてのニュアンスを文書化していました。徹底的でした。同時に、その大半とは関係のないセッションも含めて、すべてのセッションでコンテキストウィンドウの概ね 12% を消費していました。

プロトコルを移し、それらをトリガー表 — 冗長なスキル単位の散文を置き換える、コンパクトなスキル検索パターン — で置き換えることで、162 行へ絞りました。

## Skill triggers
| Trigger keywords | Skill | Domain |
|------------------|-------|--------|
| sprint, backlog, iteration | pm-sprint-plan | PM |
| deploy, release, ship | statnive-release | Dev |
| security, audit | sec-audit-remediate | Security |

このパターンは、冗長な文書化の 3,000 トークン以上に対して、〜800 トークンで済みます。詳細なプロトコルは個別の SKILL.md ファイル内に住み、Claude がそれにルーティングしたときだけ読み込まれます。.claude/rules/ 配下のパススコープルールは、Claude がマッチするファイルを扱うときだけドメイン固有の制約 (React 規約、PHP コーディング標準、リリースゲートルール) を拾い上げます。

完全なビフォーアフターは CLAUDE.md 再設計記事で文書化されていますが、削除した最大の単一アンチパターンは、ルート CLAUDE.md に大規模な参照ファイルを @-import することでした。すべての @import はすべてのセッションでターゲットファイル全体を読み込みます。私たちは 3 つ持っており、モデルがめったに必要としないコンテンツに対して概ね 6,000 トークンの恒久的なオーバーヘッドを追加していました。

スキル階層化: 4 つのバケット、1 つのルール

私たちはプロダクトマネジメント、バックエンドのスキャフォールド、QA、セキュリティ監査、WordPress 固有のパターン、リリースパッケージングなどを扱う 80 以上のスキルを持っています。素朴に読み込めば、80 スキル × メタデータ〜50 トークンで 4,000 トークンの恒久的なオーバーヘッドです。141 スキル (私たちが基盤としている jaan.to フレームワークの規模) まで成長すれば、それが 14,000 を超えます。

修正は Claude Code のスキルシステムが定義する 4 バケットの階層化モデルです。

バケット	フロントマター	メタデータコスト	いつ使うか
Always-on	(デフォルト)	〜40 トークン	モデルが自動でルーティングするコアワークフロー
Auto-invocable	(デフォルト、簡潔な説明)	〜40 トークン	強いトリガーキーワードを持つドメインスキル
Manual-only	`disable-model-invocation: true`	0 トークン	スラッシュコマンド専用スキル — まれ、または破壊的
Fork / subagent	`context: fork`	〜40 トークン	レビュー、監査、メインコンテキストを汚すべきでないマルチステップ解析

決定の単一の質問: メインの会話はスキルの出力を見る必要があるか? いいえなら — スキルが自己完結し、サマリーを返すなら — それは fork / subagent 候補で、内部のトークン使用はメインコンテキストから消えます。Anthropic は、内部作業 10,000 トークン以上から〜500〜1,000 トークンを返すサブエージェントを文書化しており、複雑なタスクではメインコンテキストを概ね 37% 削減します。

私たちは概ね半分のスキルを disable-model-invocation: true とマークしています。スラッシュコマンド経由でのみ到達可能です。これだけで概ね 2,000 トークンのベースラインメタデータが節約され、残りの auto-invocable スキルのルーティング品質も実際に向上しました。Claude が似た選択肢の間で迷うことがなくなったためです。

バケット別の完全な内訳 — Statnive の実際のスキルライブラリをどう分類しているかを含む — はスキル階層化記事にあります。

重い作業のためのサブエージェント分離

3 つのカテゴリの作業はもうメインコンテキストに触れません。コードレビュー、セキュリティ監査、探索的研究です。これらはサブエージェント — 独自の 200K トークンのコンテキストウィンドウを持つ別の Claude インスタンス — で実行され、サマリーメッセージを返します。

経済学は微妙です。サブエージェントセッションはインライン作業より多くの総トークンを消費します。Anthropic は、各エージェントが独自のシステムプロンプト読み込みとツール初期化オーバーヘッドを持つ新しい Claude インスタンスを生成するため、エージェントチームが概ね 7 倍のトークンを使うと文書化しています。

しかし、最適化対象は総トークン支出ではありません。最適化対象は次のとおりです。

メインコンテキストの清潔さ。 40 ファイルを読み 3 件の問題を見つけるセキュリティ監査は、600 トークンのサマリーを返します。分離なしでは、その全読み取りループは 40K のメインコンテキストを食い、検索品質が 15〜47% 低下する「lost in the middle」ゾーンへ私たちを押しやります。
モデルルーティング。 サブエージェントは Haiku 4.5 ($1/$5 per MTok) で動作させつつ、メインセッションは Sonnet または Opus を使えます。読み取り専用の探索にはトップモデルは不要です。Haiku の 3 倍のコスト優位性は、何百ものファイルを読む監査で素早く複合します。

通常のリリース日が今どう見えるか

典型的な Statnive のリリース日には、概ね 400K〜600K トークンの実作業を費やします。その内訳:

作業	モデル	パターン
朝の PR コードレビュー	Sonnet (メイン) + Haiku (フォークサブエージェント)	レビューをフォーク、サマリー返却
React ダッシュボードの新機能を書く	Sonnet (メイン)	Auto-invocable な `frontend-scaffold` スキル、参照はオンデマンド
リリースゲートの実行	Sonnet (メイン)	`statnive-release` スキル、bash ドリブン — 余分なコンテキストなし
こうしたブログ記事の執筆	Sonnet (メイン)	インラインで下書き、レビューパスをフォーク

残りはプロンプトキャッシュが処理します。Claude Code は安定プレフィックス — システムプロンプト、ツール定義、スキルメタデータ、ルートの CLAUDE.md — をキャッシュし、これはターンごとに繰り返されます。キャッシュ読み取りはベース価格の 0.1 倍で、その安定プレフィックスについて概ね 90% のコスト削減をもたらします。コンテンツを静的を先・動的を後にする並べ方でキャッシュヒットを最大化するため、ルート CLAUDE.md は注入される動的コンテキストの上に保ちます。

最適化しなかったもの

能力だけでなく、限界についての透明性です。

重いフックドリブンのコンテキストにはまだ移行していません。 研究は、SessionStart フックが動的コンテキスト (現在のブランチ、変更ファイル、実行中のサービス) を注入して静的な CLAUDE.md コンテンツを置き換えられると示唆しており、コミュニティのケーススタディはさらに〜62% の削減を示します。試してみて、戻しました。exit code 2 がエラーテキストをコンテキストに蓄積するリスクが恐ろしかったのです。Claude Code のフック診断が成熟したら再検討します。
アーキテクチャ的なタスクには Opus を依然として使っています。 研究は作業の 80% で Sonnet をデフォルトにし、複雑な推論には Opus を予約することを推奨しています。機能ではこれを行いますが、リリースに対しては Opus を使い過ぎています。壊れたリリースのコストは、Anthropic の限界請求を上回るためです。
トークン予算の CI ゲートはまだ作っていません。 研究のプレイブック — ルート CLAUDE.md が〜1,500 トークンを超えたら、スコープなしルールが 400 を超えたら、または任意の SKILL.md が 500 行を超えたら PR を失敗させる — は退化を防ぐでしょう。これはロードマップにあります。今のところ、すべてのセッションでの手動の /context チェックで強制しています。
当社の数値は自己報告です。 私たちは小さなチーム 1 つです。Anthropic の公開数値 (Tool Search で 134K → 5K、サブエージェント分離で 37%、プロンプトキャッシュで 90%) は当社の計測でも維持されますが、WordPress アナリティクスプラグインのパフォーマンスで行ったような厳密なベンチマークは公開していません。

複合効果は本物です

4 つの最適化 — プロンプトキャッシュ、モデルルーティング、サブエージェント分離、MCP ツール遅延 — は加算ではなく乗算です。それぞれ単独では控えめに見えます。重ねれば 200K のコンテキストウィンドウを窮屈から快適に変え、$6/日の習慣を〜$2〜3/日のツールに変えます。完全なコスト会計のウォークスルーは経済学の記事にあります。

これが Statnive のユーザーにとって意味することは: プライバシー重視のアナリティクスプラグインを出荷するのと同じチームが、テストカバレッジやコンプライアンスの厳密さを犠牲にせずに、はるかに大きなチームの規模で作業できるということです。すべてのリリースは依然として同じ 141 件のテストと 31 件のコンプライアンスチェックを通過します。AI ワークフローはスキャフォールディングであり、近道ではありません。

なぜこれを公開したのか

最速の WordPress トラッカーをどう作ったかやStatnive をどうテストするかのような記事を書いているのは、WordPress エコシステムがより正直なエンジニアリングナラティブに値すると考えているからです。同じことが AI 支援開発にも当てはまります。Claude Code がチームを変革すると主張するコンテンツは多く、トークン会計を示すものはほとんどありません。

WordPress プラグインチームや、規模で Claude Code を運用する小さなエンジニアリングチームの方は、今日 /context を実行してください。何がウィンドウを食べているかを見ましょう。当社のすべてのリリースをゲートする 4 つの数字は、ベースラインオーバーヘッド 30% 以下、ルート CLAUDE.md が 1,500 トークン以下、MCP Tool Search が有効で確認済み、ルート設定の @-imports がゼロです。これらは午後 1 つで達成可能です。

Statnive を試す

このワークフローで構築されたプライバシー重視の WordPress アナリティクスプラグインは、WordPress.org で無料です。完全なソースは GitHub にあります — 当社の CLAUDE.md、リリースゲートスキル、完全なテストスイートを含みます。あなたのデータはあなたのサーバーに留まります。当社のは当社のサーバーに留まります。