token-optimization

トークン最適化 — Claude Code

概要

Claude Code でトークンを過剰に消費する主な原因は、次の4つです。

1. キャッシュミス — キャッシュされていないリクエスト、または無効化されたリクエスト
2. コンテキストの肥大化 — コンテキストウィンドウが不必要に拡大すること
3. 不適切なモデル／推論レベル — 推論の過剰な使用
4. 冗長な入力形式 — コンテキストに挿入されるデータが冗長すぎること

---

フェーズ 1：初回セッションの監査

作業を始める前に、次の2つのコマンドを実行してください。

/context   # Shows loaded MCPs and tokens already consumed
/plugin    # Lists active plugins

体系的な対策：

• 現在のプロジェクトに不要な MCP をすべて無効にします
• 使用していないプラグインをすべて無効にします
• 1つのプロジェクトに1つのグローバル設定を使うのではなく、プロジェクトごとにカスタマイズします

実例：Canva、Gmail、Google Calendar の MCP を読み込んだ空のセッションでは、最初のキー入力前に 23,000トークンを消費します。

確認すべき危険信号：

• 読み込まれている MCP が3つを超えている
• 現在の作業に関係のないプラグインがある
• 空のセッションでベースのトークン数が10,000を超えている

---

フェーズ 2：キャッシュ管理

原則

Claude Code は、システム指示（CLAUDE.md）、ツール／MCP の一覧、メッセージ履歴をキャッシュします。セッション中に変更を加えると、このキャッシュが無効になり、影響を受けるトークンがすべて再課金されます。

必須ルール

• セッション中にツール、MCP、モデルを追加しないでください。 すべての設定は開始前、または専用のセットアップセッションで行ってください。
• セッション中に重大な追加（大きなスキル、MCP、重要なコマンド）が必要になった場合：
  1. セッションを圧縮します（/compact）
  2. 圧縮された要約を出発点として、新しいセッションを開始します
• キャッシュはHTTP キャッシュのように扱ってください。ヘッダーを変更すると、その下流にあるものがすべて無効になります。

キャッシュ無効化の階層

┌─────────────────────────────────────────────┐
│ BASE SYSTEM INSTRUCTIONS (CLAUDE.md + tools)│  ← Invalidated if tool added
├─────────────────────────────────────────────┤
│ SESSION STATE (project files, memory)       │  ← Invalidated if file changes
├─────────────────────────────────────────────┤
│ MESSAGE HISTORY                             │  ← Invalidated if message edited
│  msg 1 → msg 2 → msg 3 → ...                │     (invalidates everything after)
└─────────────────────────────────────────────┘

キャッシュを無効にする操作：

操作	無効になる層	影響
セッション中に MCP を追加する	ベースの指示	非常に大きい
ツールを追加する（ツール呼び出し）	ベースの指示	非常に大きい
CLAUDE.md を変更する	ベースの指示	非常に大きい
履歴の途中にあるメッセージを編集する	メッセージ履歴（その時点以降）	中程度
新しいファイルをコンテキストに読み込む	セッションの状態	中程度

最適なセッション戦略：

1. Full configuration (MCP, tools, CLAUDE.md) → BEFORE starting
2. Work session → NEVER modify configuration
3. If modification needed → /compact → new session
4. Agents → context fork → isolated work → result only

キャッシュの問題に関する技術的な詳細は、references/cache-deep-dive.md を参照してください。

---

フェーズ 3：コンテキストウィンドウの最適化

デフォルトのコンテキストウィンドウを小さくする

100万トークンのウィンドウは魅力的ですが、危険でもあります。好ましくない習慣を招き、子エージェントに過剰な負荷をかけます。

条件付きの推奨事項：

• 小規模／中規模のコードベース → settings.json で約200,000トークンに制限します。

  { "contextWindow": 200000 }
  

  (デフォルトではコミットされません — ローカルファイルを使用してください)

• 非常に大規模なコードベース → 100万トークンを維持しつつ、以下のプラクティスをさらに徹底します。

RAM のたとえ：RAM が32GBあっても、メモリ管理をおろそかにしてよいわけではありません。ウィンドウを制限することで、より適切な管理が促されます。

コンテキストの分岐と独立したエージェント

エージェントは起動時に親のコンテキストを引き継ぎます。起動が遅いほど、開始時の負荷が大きくなります。

目標とする動作：

• 各スキルやエージェントを分岐したコンテキストで呼び出します（パラメーターに context: fork を指定）
• エージェントは独自のウィンドウで作業します。完了時には、全履歴ではなく結果のみを返します
• エージェントを破棄しても、メインコンテキストは変化しません

サブエージェントに分離する体系的なユースケース：

タスク	分離する理由
ウェブ検索	訪問したページの Markdown 履歴がメインウィンドウを汚染します
PDF／音声の文字起こし	出力の量が多く、メインコンテキストに含める必要がありません
計画／テスト生成	作業が長くなるため、コンテキストをクリーンに保てます
コードベースの調査	組み込みの explore エージェントは（IQ を使用し）、すでにこの用途に最適化されています

CLAUDE.md に追加するプロンプト：

For any web search, systematically delegate to isolated subagent.
Return only extracted relevant information, not full history.

圧縮と巻き戻し

• 自動圧縮：エージェントがウィンドウの約80%に達すると実行されます。エージェントには望ましい動作ですが、メインセッションには望ましくありません。
• 巻き戻し（Esc を2回）：以前の会話に戻り、不要なコンテキスト分岐を削除できます。誤った方向に進み始めたら、すぐに使用してください。

---

フェーズ 4：モデルと推論レベルの選択

推論にかける労力

労力システムは、回答の品質を確認するためにプロンプトを繰り返します。ループごとにトークンが追加されます。

状況	推奨される労力
明確で定義されたタスク	中（デフォルト）
複雑な推論、アーキテクチャ、設計	高
簡単なタスク、既知のコマンド	低／なし（think は不要）

ルール：答えが頭の中で明確なら、medium を使います。Claude には、自分の代わりに考えてもらうのではなく、一緒に考えてもらいましょう。

モデルの選択

• Claude Code サブスクリプション → Anthropic のネイティブモデル（Sonnet／Opus）を使います。プロキシは不要です。
  • Opus：レイテンシーが高くても、複雑なタスクでは優先します
  • Sonnet：高速なタスク、一般的なコード生成に適しています
• 他の LLM（GLM、Kimi など）へのプロキシ：SDK／API を直接使う場合にのみ関係し、標準の Claude Code では該当しません。プロキシは不安定で、最適化されていません。

CLAUDE.md に追加します：

## Reasoning effort
- Simple task / known command → minimal effort, no `think`
- Design / architecture task → medium effort
- Complex unsolved problem → high effort only on explicit request
Never over-reason a simple task.

---

フェーズ 5：入力形式の最適化

ブラウザーの自動化：スクリーンショットより DOM

Claude Code のネイティブブラウザーエージェントは各ステップでスクリーンショットを取得するため、トークンと時間を大幅に消費します。

推奨される代替手段：Stagehand / Agent Browser（Vercel）

• DOM を直接操作します（画面には表示されず、スクリーンショットもありません）
• インストール：Claude Code の新しいインスタンスを開く → Install [stagehand URL]
• 結果：10 倍高速になり、トークンを大幅に削減できます

冗長な CLI 出力をフィルタリングする

git status や git diff などのコマンドは、コンテキストに取り込まれると非常に冗長になります。

推奨ツール：RTK（フランスの開発者が開発）

• コンテキストウィンドウに取り込む前に、コマンド出力をフィルタリングします

• 例：git status の出力が約 50 行から重要な約 5 行になり、このコマンドで約 80％削減できます

• グローバルインストール：

  # Run in Claude Code
  npx rtk init --global
  

簡潔な回答：Caveman Skill／CLAUDE.md

デフォルトでは、Claude Code の回答は非常に冗長です。回答の量を大幅に減らします。

CLAUDE.md に追加する指示：

## Response style
Ultra-concise responses. Remove articles, politeness phrases, reformulations.
Get to the point. Format: short bullet points. No intro, no conclusion.

Caveman Skill（GitHub で利用可能、約 50k スター）：CLAUDE.md に直接組み込める、すぐに使える指示です。例については references/claude-md-templates.md を参照してください。

ファイルパスを明示的に指定する

コマンド内で Claude にファイルを独自に探させないでください。

# ❌ Costly: Claude will list, explore, read
"Update project memory"

# ✅ Optimal: explicit paths in command
"Update ./docs/memory.md and ./CLAUDE.md with following items: ..."

メモリーコマンドのテンプレート：

## Memory/Learning commands
`/learn` command: updates ONLY the following files:
- ./docs/project-memory.md
- ./CLAUDE.md (section "Project Context")
Do not scan other files unless explicitly instructed.

---

フェーズ 6：検証とモニタリング

コンテキストの消費量を確認する

最適化を実装した後、次の点を確認します。

/context    # Check current token count

成功基準：

• 基本セッションが 5,000 トークン未満（必要な MCP のみを使用）
• 10 回のやり取り後：30,000 トークン未満
• 独立したタスクで 50,000 トークンを超えるエージェントがいないこと

チームのモニタリング

消費量の追跡が必要なチーム向け：

• ローカルダッシュボードツール（参考記事の著者が作成）：セッション、呼び出されたモデル、セッションごとのトークン数を表示します
• 個人開発者よりもマネージャーやリードに役立ちます
• リンクについては、以下の参考資料を参照してください

記録されている具体的な結果： これらの最適化により、月額 750 ドルから 100 ドルに削減されました（出典：参考動画でリンクされている記事）。

---

トラブルシューティング

最適化してもトークン数が多い

診断手順：

1. /context を実行して、読み込まれている MCP を特定します
2. settings.json を確認して、contextWindow の設定を検証します
3. 最近のコマンドを確認して、冗長な出力を特定します
4. エージェントの起動を確認して、コンテキストのフォークを検証します

よくある解決策：

• 使用していない MCP を無効にします
• git コマンドに RTK フィルタリングを追加します
• 調査タスクにはサブエージェントを使います
• コードベースで問題がなければ contextWindow を減らします

キャッシュの無効化が頻繁に発生する

診断：

1. セッション中にスキルが読み込まれているか確認します
2. CLAUDE.md が変更されていないか確認します
3. セッション中にツールが追加されていないか確認します

解決策：

• セッション開始時に必要なスキルをすべて事前に読み込みます
• CLAUDE.md の設定を固定します
• 設定変更には専用のセットアップセッションを使います

エージェントがトークンを使いすぎる

診断：

1. エージェントが肥大化した親コンテキストを引き継いでいないか確認します
2. エージェントが不要な MCP を読み込んでいないか確認します
3. エージェントの履歴に冗長なツール出力がないか確認します

修正方法：

• エージェントを早い段階で起動します（親コンテキストを軽くします）
• context: fork パラメーターを使用します
• エージェントの履歴全体ではなく、結果のみを返します

---

例

例 1：トークンを最適化したプロジェクトのセットアップ

ユーザーの発言：「最適なトークン設定で新しいプロジェクトをセットアップして」

アクション：

1. 簡潔な応答指示を記載した最小限の CLAUDE.md を作成します
2. コードベースのサイズに基づいて contextWindow を設定します
3. プロジェクトの種類に必要な MCP のみを有効にします
4. git コマンドに対する RTK フィルタリングを追加します
5. サブエージェントへの委任ルールを定義します
6. ベースセッションが 5,000 トークン未満であることを確認します

期待される結果： 最適化されたセッション設定がプロジェクトの CLAUDE.md に記録されます

例 2：トークン消費量が多い原因の診断

ユーザーの発言：「セッションでトークンを使いすぎています。原因を調べてください」

アクション：

1. /context を実行して現在の状態を監査します
2. 読み込まれている MCP とプラグインを確認します
3. 最近のコマンド出力が冗長でないか確認します
4. キャッシュ無効化のパターンを特定します
5. 最適化の推奨事項を作成します
6. 影響の大きいものから優先して修正を実施します

期待される結果： 根本原因が特定され、修正が実施され、トークン消費量が 50～80％削減されます

例 3：ウェブ調査タスク

ユーザーの発言：「React Server Components のベストプラクティスを調査して」

アクション：

1. コンテキストをフォークして、分離されたサブエージェントを起動します
2. サブエージェントがウェブ検索を実行します
3. サブエージェントが重要な調査結果のみを抽出します
4. 検索履歴全体ではなく、要約をメインコンテキストに返します
5. メインコンテキストが受け取るのは約 5,000 トークンではなく約 500 トークンです

期待される結果： 直接検索する場合と比べてトークンを 90％節約しながら、調査を完了できます

---

参考資料

詳細な技術情報については、以下をご覧ください。

• references/cache-deep-dive.md — キャッシュの動作と無効化のパターン
• references/claude-md-templates.md — すぐに使える CLAUDE.md 設定ブロック
• references/tools.md — 外部ツール（Stagehand、RTK）のセットアップガイド

外部リソース：

• Anthropic Prompt Caching Documentation
• Stagehand Browser Automation
• RTK CLI Output Filter

---

品質チェックリスト

最適化を完了する前に、以下を確認します。

• ベースセッションが 5,000 トークン未満
• 必要な MCP のみを読み込み済み
• CLAUDE.md に簡潔な応答指示を記載済み
• 調査タスク用のコンテキストフォークを設定済み
• 冗長なコマンド用の RTK または同等のフィルタリングをインストール済み
• contextWindow をコードベースのサイズに合わせて設定済み
• チームメンバーがキャッシュ無効化のルールについてトレーニング済み（該当する場合）