Claude Code 上級編：トークン最適化と大規模コードベースのコンテキスト攻略（2026）

- この記事のコマンドと数値は Anthropic の公式ドキュメント（2026-08-20 取得）に基づいています。Claude Code は非常に頻繁に更新されるため、claude --version を確認し、ご自身のマシンで /usage を再実行して比較してください。

なぜ Claude Code は大規模コードベースでトークンを消費するのか？

多くの開発者は「小さな質問を1つしただけなのに、使用量が一日中増え続ける」と苛立ちます。原因はその質問ではなく、言語モデルの仕組みにあります。すべてのリクエストは会話全体を再送信するのです（システムプロンプト、CLAUDE.md、履歴、読み込んだファイル、ツールの結果）を入力として。セッションが長くなるほど、後ろに連なるコンテキストが増え続けるため、1回のやり取りごとのコストが上がっていきます。

コストを押し上げる3つのメカニズムが複合的に効いてきます。

• 長いコンテキストの蓄積：コンテキストに引き込むファイルが多いほど、以降のターンはすべて重くなります。そのファイルに二度と触れなくてもです。
• コンテキストの劣化（context rot）：Anthropic の記事 Effective context engineering for AI agents（2025-09-29）によると、ウィンドウ内のトークン数が増えるほど、モデルが重要な情報を思い出す能力は実際に低下します。つまり肥大化したコンテキストは高くつくだけでなく、Claude の精度も下げてしまうのです。
• キャッシュミス：Claude Code はプロンプトの先頭部分をキャッシュするので、その分は再び課金されません。しかしキャッシュには有効期限があります。長く離席してから戻ると、コンテキストブロック全体がまた満額で課金されてしまいます。

基本コストについて、Anthropic の 「コストを効果的に管理する」ドキュメント（docs、2026年8月取得）は、アクティブな1日あたり平均およそ ~$13/開発者 と報告しており、多くの利用は 月$150〜250 あたりに収まり、ユーザーの90%が1日あたり~$30未満にとどまっています。大規模コードベースでこれを大きく超えているなら、いくつかの予測可能な箇所でトークンを無駄にしているのはほぼ間違いありません。プランと課金の仕組みを理解するには、Claude Code の料金とプランのガイドをご覧ください。まだ始めたばかりなら、まずClaude Code とは何かを読んで基礎を押さえてください。

最適化の前にまず計測 — /context、/usage、ステータスライン

手探りで最適化しないでください。どの手法に手をつける前にも、現状のスナップショットを取り、トークンがどこで消費されているかを把握しましょう。この2つのコマンドが出発点です。

/usage # token & cost overview: input, output, cache read/write, cost
/context # breaks down what is taking up your CURRENT context right now

/usage はお金の全体像を示します。入力トークンが何個、出力トークンが何個、キャッシュから読んだ量（安い）と新しいキャッシュに書き込んだ量（高い）はどれだけか。キャッシュ読み取りの比率が高いのは良い兆候です。最適化においては /context のほうが2つのうち価値があります。システムプロンプト、CLAUDE.md、宣言した MCP ツール、引き込んだファイルを切り分けて、何が容量を食っているかを正確に見せてくれます。

/usage には知っておく価値のある特定の出力フォーマットがあります。たとえば Session ブロックです。

Total cost:            $0.55
Usage by model:
   claude-sonnet-4-6:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)

Pro/Max/Team/Enterprise プランでは、/usage は Plan usage breakdown も表示します。Attribution は直近の使用量を skill、subagent、plugin、個々の MCP サーバーに割り当て、それぞれを全体に対する割合で示します。Behavior flags は、長いコンテキストやキャッシュミスが直近の使用量の10%以上を占めるときに警告します。d/w を押すと24時間表示と7日間表示を切り替えられます。

いくら使ったかではなくあなたの働き方について知るには、/insights を実行してください。このマシン上の直近200セッションまでを分析し、摩擦点と Claude Code をより効果的に使うための提案をまとめた HTML レポートを ~/.claude/usage-data/report.html に書き出します。/usage を置き換えるものではなく、補完するものです。

コマンドを打たずに継続的に監視できるよう、ステータスラインにコンテキスト表示を有効にしておくのもおすすめです。詳しくはClaude Code のステータスラインをカスタマイズするガイドをご覧ください。原則は、前後の数値だけがどの手法が本当に手間をかける価値があったかを教えてくれる、ということ。以下の各変更の直前と直後に /context を実行し、実際の差分を計測してください。

グループ1 — 能動的なコンテキスト管理（/clear、/compact、resume）

これは存在する中で最も安く、最も効果の高いレバーです。無駄なトークンのほとんどは、古く無関係なコンテキストを新しいタスクへ引きずり込むことから生まれます。

無関係なタスクの間には /clear。認証モジュールのバグ修正を終えて、これから支払いモジュールのテストを書こうとしていますか？/clear と打ちましょう。コンテキストが最初の状態にリセットされ、新しいタスクにとっての「会話のしっぽ」のコストがほぼ$0まで下がります。これは多くの人が飛ばしてしまう、最も重要なトークン節約の習慣です。

スレッドを続けたいときは /compact。同じ作業の流れを続けたいのにコンテキストが膨れ上がってきたら、/compact が会話を要約に圧縮します。重要なのは、必要なものを正確に失わないよう方向付きの compact を使うことです。

/compact Keep the database schema decisions and the files changed in the payment module; drop the long debug logs

CLAUDE.md に「Compact instructions」をあらかじめ設定しておけば、すべての compact で同じ優先順位が保たれます。Claude Code には自動 compact もあります。コンテキストが満杯に近づくと、セッションが壊れないよう自動で圧縮します。便利ですが正直な注意点として、自動 compact は詳細を落とすことがあります。重要なタスクでは運任せにせず、方向付きの手動 compact を実行してください。

要約から再開する。大きなセッションを再び開くときは、履歴全体を読み込み直すのではなく要約から再開することを選びましょう。数万トークンではなく数千トークンから始められます。この仕組みを深掘りするには、Claude Code のコンテキストとメモリ管理のガイドをお読みください。

グループ2 — 適切なモデルを選び、拡張思考（extended thinking）を調整する

すべてのタスクに最強のモデルが必要なわけではありません。コストで配分する方法は次のとおりです（参考 API 価格：Opus 5 は100万トークンの入力/出力あたり $5/$25、Sonnet 5 は $2/$10、Haiku 4.5 は $1/$5）。

• ほとんどのコーディングは Sonnet で。Sonnet 5 はコードの記述・編集の大多数を Opus のわずかなコストでこなします。
• Opus はアーキテクチャと難問のために温存。深い推論が必要な場面に来たら、セッション途中で /model で切り替え、終わったら Sonnet に戻します。
• 単純な subagent には Haiku。純粋に機械的な作業（grep、要約、整形）をする subagent には、その定義に model: haiku を設定します。

拡張思考（extended thinking）はトークンにとって諸刃の剣です。「思考」は出力トークンとして課金され、出力は入力の数倍のコストがかかります。単純で反復的なタスクで重い思考をするのは、ただお金を燃やしているだけです。制御の仕方は次のとおりです。

/effort # tune the reasoning effort to fit the task
MAX_THINKING_TOKENS=8000 # cap thinking tokens (environment variable)

/config で拡張思考をオフにすることもできます。正直な但し書き：思考をオフにすると深い推論を要するタスク（アルゴリズム設計、多層的なデバッグ）で品質が下がります。これはトレードオフであって、「節約のために常にオフ」という規則ではありません。タスクが本当に多くの推論を必要としないときにだけ、下げたりオフにしたりしてください。

グループ3 — MCP とツールのオーバーヘッドを削る

訂正：Claude Code は現在、デフォルトで MCP ツール定義を遅延読み込みします。最初はツールの名前だけがコンテキストに載り、完全な説明とパラメータスキーマは Claude が実際にそのツールを使ったときに初めて読み込まれます。したがって実際のコンテキスト「税」は2つです。(a) 古い Claude Code バージョンやツール検索が無効なセッションでは依然としてすべてが最初に読み込まれる。(b) 非常に多数のツールを持つサーバーは、名前だけでも積み上がり、加えてツールが初めて呼ばれるときに一度きりのコストがかかる。これを調べるには /context を使ってください。

• 使っていないサーバーは無効化する：/mcp で接続中のサーバーを表示・管理し、現在のセッションで不要なものはオフにします。
• 可能なら MCP より CLI を優先する。すでにコマンドラインツールがあるタスク — gh（GitHub）、aws、gcloud — では、同等の MCP サーバーを組むのではなく、Claude に Bash 経由で CLI を直接呼ばせましょう。CLI はコンテキストに常駐する「ツール一覧」コストを持ちません。
• 型付き言語にはコードインテリジェンス。TypeScript/Java/Go では、「定義へ移動」プラグインを使えば Claude が grep して大量のファイルを読む代わりに定義へ直接ジャンプでき、大規模コードベースでのファイル読み取りトークンを目に見えて削減できます。

MCP を理解し、いつ使うべきか使うべきでないかを知るには、次のグループにある Claude Code の hook についての記事を参照してください。この2つの仕組みはコンテキストを減らすためにしばしば連携します。

グループ4 — 重い処理を hook と skill に肩代わりさせる

これは最も見返りが大きいのに、活用している人が最も少ないグループです。考え方はこうです。かさばる出力を Claude のコンテキストへそのまま流し込ませない — スクリプト層でまずフィルタリングまたは要約するのです。

テスト出力をフィルタする hook。大きなテストスイートを1回走らせると数万行が出力されることがありますが、Claude が知る必要があるのは何が FAILED したかだけです。FAIL/ERROR 行だけを残す PreToolUse／後処理の hook は、トークン数を数万から数百へ引き下げられます（「コストを効果的に管理する」ドキュメントによる）。フィルタスクリプトの骨組みの例です。

#!/usr/bin/env bash
# filter-test-output.sh - keep only failing lines, cut the noisy log
npm test 2>&1 | grep -E "(FAIL|ERROR|✕|Error:|Expected|Received)" | head -n 100

「codebase-overview」skill。プロジェクト構造を理解するために毎回 Claude に20個のファイルを読ませる代わりに、アーキテクチャ、規約、主要モジュールの所在を記述した skill をパッケージ化します。skill は必要時に読み込まれるので、コンテキストに常駐しません。しかし必要になったときには、大量のファイル読み取りの代わりに即座にコンテキストを与えてくれます。

CLAUDE.md は簡潔に保つ。Anthropic のドキュメントは CLAUDE.md を ~200行未満に保つことを推奨しています。このファイルの内容はすべてのリクエストに読み込まれるため、詰め込みすぎは恒常的なトークン税になります。専門的な指示（デプロイ手順、あるモジュールの規約）は必要時読み込みの skill へ移し、CLAUDE.md には毎セッションで本当に使うものだけを残しましょう。

グループ5 — 大規模コードベースのための subagent とジャストインタイム取得

モノレポでの最大の敵は、単一のコンテキストにリポジトリ全体を「スキャン」させてしまうことです。解決策は、重い読み取りをメインのコンテキストから切り離すことです。

調査は subagent に委任する。「機能 X はどこに実装されているか」を調べる必要があるときは、それを subagent に渡します。subagent は自身のコンテキストで一連のファイルを読み、要約だけを返します。Anthropic のエンジニアリング記事によると、ファイルの中身全体をメインコンテキストに投げ込むのではなく、通常はわずか ~1,000〜2,000トークンです。詳しい手順はClaude Code の subagentガイドをご覧ください。

@ 参照によるジャストインタイム取得。Claude に当てずっぽうで grep させ回らせないでください。必要なものを、必要なときに、直接指し示しましょう。

@src/payment/checkout.ts # load exactly one file when needed
@src/payment/ # load exactly one directory

高くつくやり直しを避けるための Plan モード。Shift+Tab を押して plan モードに入ると、Claude は編集の前に計画を立てます。計画をレビューするほうが、大量のファイルを誤編集させてから作り直すよりずっと安上がりです。やり直しのループはどれもトークンを消費します。もし間違った方向に進んだら、すべてを一から説明し直す代わりに /rewind（または Esc を2回）で以前のチェックポイントに戻りましょう。

このグループ全体を貫く原則は、Anthropic から借りたものです。高シグナルのトークンを最小限に目指すこと — コンテキストに入れる量はできるだけ少なく、しかし最も価値ある部分だけを正確に入れる。これは記事冒頭で触れたコンテキスト劣化への処方箋でもあります。

グループ6 — Advisor：強力なモデルを一日中動かさずにセカンドオピニオンを得る

Advisor はメインのモデルを、通常はより強力な2つ目のモデルと組み合わせます。いつ相談するかは Claude が判断し、通常はアプローチを確定する前、繰り返し発生するエラーのとき、あるいはタスク完了を宣言する前であって、毎ターンではありません。これは正真正銘のトークン最適化手法です。強力なモデルをセッション全体で動かすより明確に安上がりだからです。

有効化するには /advisor opus（または別のモデル）を実行するか、設定で advisorModel を指定するか、単一セッション用に --advisor を渡します。オフにするには /advisor off です。

コストの仕組み：各呼び出しはadvisor モデルのレートで、メインモデルの使用量に上乗せして課金されます。サブスクリプションプランでは、advisor の使用量も他のすべてと同様にプラン上限にカウントされます。ただし Fable 5 の advisor は、それが適用されるプランでは使用クレジットに課金されます。セッション途中で advisor を切り替えても、メインモデルのプロンプトキャッシュは無効化されません（advisor 自身による会話の読み取りだけがキャッシュされないだけです）。

正直な但し書き：これは実験的機能で、Anthropic の直接 API 経由でのみ利用でき、Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry では使えません。挙動や価格は変わる可能性があります。

トークンの罠：エージェントチーム、動的ワークフロー、一日中のセッション

この2つは、気づきにくい形で静かに使用量を膨らませます。

エージェントチームは約7倍のトークン — ただしチームメンバーが plan モードで動くときだけ。多数のエージェントの「チーム」を並列で走らせるのは強力に聞こえますが、「コストを効果的に管理する」ドキュメントは、チームメンバーが plan モードで動くときには標準セッションのおよそ ~7倍のトークンを使うと警告しています。各メンバーが独自のコンテキストウィンドウを保持し、別々の Claude インスタンスとして動くからです。使うべきでないのは：逐次的なタスク、小さなスコープ、あるいはトークン予算が厳しいとき。どうしても使うなら、メンバーは Sonnet で走らせ、終わったらすぐにチームを閉じましょう。

動的ワークフローも、上限を設けないと使用量を膨らませ得ます。プロンプトにキーワード ultracode と打つ（または平易な言葉で「これにワークフローを使って」と頼む）と、Claude は多数の subagent をオーケストレーションする動的ワークフローを書いて実行します。1回の実行で最大 1,000エージェント、同時に最大 16 まで走ります。進行状況は /workflows で見られます。「Large workflow」警告は、実行が 25エージェントを超えてスケジュールするか、予測トークンが 150万を超えるときに表示されます（25エージェントのしきい値は、/config で設定したサイズガイドラインに置き換えられます。デフォルトは medium、15エージェント未満です）。これは助言的なものにすぎず、実行を止めません。正直に言うと、フルのワークフロー実行に公式なドル金額はありません。全体を走らせる前に小さな一部でテストしてください。詳しい仕組みは Claude Code の動的ワークフローをご覧ください。

一日中のセッション。単一のセッションを朝から晩まで走らせ続けるのはトークンを燃やすレシピです。長いコンテキストは膨張し、離席するたびにキャッシュがミスし続けます。キャッシュについて、ドキュメントは寿命をサブスクリプションプランでは1時間、使用クレジット/API では5分と記しています。1時間キャッシュは環境変数で有効にできます。

ENABLE_PROMPT_CACHING_1H=1

良い習慣：作業を切り替えるときは /clear、長い休憩のときはセッションを閉じ、戻ってきたら要約から再開する。（安心のための小さな注記：Claude Code の自動タスクのためのバックグラウンドトークンはとても安く、ドキュメントは < $0.04/セッションを挙げています。その部分は心配いりません。）

まとめ表 — 手法とトークン削減の対応

トークンの ROI 順（高レバレッジ／低労力が上）に並べています。「削減」列に Anthropic の出典があるものは検証済みの数値を引用しています。実際のコードベースで計測する部分は、Jasmine がテストセッションから埋める箇所です。

既製キット（AgentKit）で高速化する

上記の手法の多く — 「codebase-overview」skill、専門的な subagent、出力フィルタの hook — は効果的ですが、自分で組んで調整するには相応の手間がかかります。コンテキスト最適化済みの skill、subagent、hook のセットを既製で手に入れたいなら、Claude Code 向け AgentKit キットがこのツールセットをパッケージ化しているので、一から書く必要がありません。

混同を避けるための注記：ここでの AgentKit（agentkit.best、CLI ak）は Claude Code / Codex / Copilot 向けのキットで、OpenAI の AgentKit とはまったく別物です。AgentKit をチェック（リンク経由で20%オフ）してご自身で判断できます。これは任意の提案であって必須ではありません。この記事のすべての手法は手作業でも実行できます。

よくある質問（FAQ）

/compact と /clear はいつ使い分ける？

無関係なタスクに切り替えるときは /clear を使います。コンテキストをリセットし「会話のしっぽ」のコストをほぼゼロにします。同じ作業の流れを続けたいのにコンテキストが膨れたときは /compact を使います。スレッドを保ったまま履歴を要約に圧縮します。

Claude Code は自動で compact する？

はい。コンテキストが満杯に近づくと、セッションが壊れないよう Claude Code が自動 compact します。便利ですが詳細を落とすことがあるので、重要なタスクでは運任せにせず自分で方向付きの /compact を実行してください。

Opus を使うとかなり高くつく？

はい。参考 API 価格では、Opus 5（100万トークンの入力/出力あたり $5/$25）は Sonnet 5（$2/$10）より約2.5倍高価です。コーディングの大半は Sonnet に任せ、アーキテクチャや難問のときだけ /model で Opus に切り替えましょう。

使っているトークンを確認するには？

/usage と打つと、入出力トークンの合計、キャッシュの読み書き、コストが見られます。/context と打つと、現在のコンテキストをどのコンポーネントが占めているか（CLAUDE.md、MCP ツール、読み込んだファイル）が見られます。各変更の前後にこの2つで計測してください。

大規模コードベースでは、どこから最適化を始めるべき？

まず /context で計測し、次に最も安い2つのレバーを優先します。タスク間の /clear と、CLAUDE.md を~200行未満に削ること。その後、余分な MCP の削減、調査への subagent の活用、テスト出力をフィルタする hook へ進みます。

拡張思考をオフにするのは有害？

有害になり得ます。思考を無効化すると出力トークンは節約できますが、深い推論を要するタスク（アルゴリズム設計、多層的なデバッグ）で品質が下がります。単純なタスクでのみ /effort や MAX_THINKING_TOKENS=8000 で下げ、推論が必要な作業には思考を残しましょう。

advisor ツールは追加のトークンを消費する？

はい。各呼び出しは advisor モデルのレートでメインモデルの使用量に上乗せして課金され、他のものと同様に /usage にカウントされます。ただし Claude は判断ポイント（アプローチの確定、繰り返すエラー、完了宣言の前）でしか advisor を呼ばず、毎ターンではないので、強力なモデルをセッション全体で動かすより通常はまだ安上がりです。

動的ワークフローはどれくらいのトークンを使う？

公式なドル金額はありません。ランタイムには暴走するコストを抑えるためのハード上限があります — 合計最大1,000エージェント、同時に最大16まで。25エージェント／150万トークンでの「Large workflow」警告は助言的なだけで、実行を止めません。全体を走らせる前に小さな一部でテストしてください。

結論と次のステップ

Claude Code のトークン最適化の公式は1本の連鎖に収まります。計測 → コンテキストを削る → モデルを選ぶ → hook/skill に肩代わりさせる → 大規模コードベースには subagent → セッション全体でモデルを切り替える代わりに advisor。すべてを一度にやらないこと。/context と /usage で計測し、表から ROI の高い2〜3のレバーを選び、適用して、また計測する。削減はあなたのコードベースと習慣次第だということを忘れずに — ご自身のマシンで計測してください。

次に読む：compaction をさらに深掘りするならコンテキストとメモリの管理、使い方に合ったプランを選ぶならClaude Code の料金とプラン、大きなタスクで多数のエージェントをオーケストレーションする必要があるならClaude Code の動的ワークフロー。手作業で最適化するより既製のツールセットを使いたいなら、Claude Code 向け AgentKit レビューをチェックしてください。