「Claude Code」は、CLI上で動くLLMによるAIエージェントツールです。この記事は12月5日に発売された『Claude CodeによるAI駆動開発入門』に書ききれなかった応用的な内容や最新のアップデートについて解説します。書籍をあわせて読むとさらに理解が深まることでしょう。

コンテキストウィンドウを制するものは開発を制する

Claude Codeの「コンテキストウィンドウ」とはなんでしょうか。

Anthropicの公式ドキュメントから答えると「LLMが新しいテキストを生成する際に参照できるテキストの全体量と、生成する新しいテキストを合わせたもの」です[1]。

簡単に言うと、コンテキストウィンドウの中身は、セッションの中のユーザーのメッセージ（プロンプト）とClaudeのレスポンスを合わせたものです。

下記のコンテキストウィンドウの概念図をご覧ください。

一番左の「Turn1」が会話の一番最初です。

黄土色の「Input」の領域にユーザーのメッセージ、灰色のOutputの領域に「Claude」のメッセージが入っていることが示されています。

その次の「Turn2」をご覧ください。

注目すべきはこのTurn2のInputとして、Turn1のInputとOutputが入っている、ということです。

そしてTurn2で生成されたClaudeの新しいレスポンスが次の「Turn3」の内容として引き継がれます。

このように数珠繋ぎでコンテキストウィンドウが成り立ってることが分かります。

この連なりが最大で20万トークン、ということになります。ちなみに20万トークンとは大体小説一冊程度の文字数になります[2]。

Claude Codeがコンテキストウィンドウを使って開発を行うために、ここに何が入ってどう動作しているのかをエンジニアは理解する必要があります。

今回は、このコンテキストウィンドウの中身を掘り下げていきます。

拡張思考モードの際のコンテキストウィンドウ

Anthropicのブログで言及されている知見として、Ultrathinkなどで拡張思考モードで動作した際、その会話のOutputの中に拡張思考モード分のトークンが入りますが、次のTurnには引き継がれません[3]。

おそらく拡張思考モードは基本的に思考するための手順を一旦アウトプットして、Claudeの推論の精度を上げるためのものなので、その手順自体は次の会話には不要だと判断しているのだと考えられます。

コンテキストウィンドウの中身

上述のコンテキストウィンドウの概念図のInputの中にClaude Codeが動作するためのシステムプロンプトやツールが入っていたり、Outputの中にはClaudeが生成したコードなども入っています。

具体的な中身を見るために/contextコマンドを入力してみましょう。

左上にある碁盤の目のようになっているのがコンテキストウィンドウの占有を視覚的に表したものです。

10マス✖10マスのアイコンになっており、何がどこまで占めて、どれだけ空いてるかがわかるようになっています。

Claude Codeが動くための30%の領域

まず注目すべきは動かせないシステムプロンプトとシステムツール（以下、ツール）で約10%占められていることです。

⛁ System prompt: 2.9k tokens (1.4%)
⛁ System tools: 19.4k tokens (9.7%)

システムプロンプト

「システムプロンプト」とはClaude Codeを動かすためにAnthropicが埋め込んだデフォルトのプロンプトです。具体的にどのようなものかは公開されていませんが、Claude Codeの振る舞いを決め、ガイドラインやルールなどがここに記載されています。

ツール

「ツール」とはClaudeが持っている機能群で、ファイル操作やWebアクセス、スラッシュコマンドなど、Claudeが動作する際に行う処理群がここに格納されています。

「ツール」というキーワードが日本語のイメージと離れているため、やや分かりづらいのですが、Anthropicのドキュメントの中では頻繁に出てくるため理解しておく必要があります。

ツールにはBash（シェルコマンド実行⁠）⁠、Edit（ファイル編集⁠）⁠、WebFetch（URLからコンテンツ取得）など、Claude Codeが行う操作が入っています。

これはClaude Codeの設定ファイルであるsettings(.local).jsonのpermission設定と対応しています。

  "permissions": {
    "allow": [
      "Bash(mkdir:*)",
      "Bash(npm init:*)",
      "Read(//Users/user/other_project/**)",
    ]
  }

詳しくは以下の公式ドキュメントをご覧ください。

https://code.claude.com/docs/ja/settings#claude-が利用できるツール

なお、ツールのpermissionを「deny」に設定することで、システムツールが占めるコンテキストのデフォルトの領域を削減できるようです[4]。

Auto Compactの領域

次に注目すべきはAuto Compact（自動圧縮）を行うためのバッファが22.5%も占めている、ということです。

⛁ Autocompact buffer: 45.0k tokens (22.5%)

コンテキストウィンドウ自体が逼迫してきた際に、この領域を使ってこれまでの会話や出力内容を圧縮して収めるためのバッファです。

つまり余力を維持するために常に確保されていて、これが22.5%も占めているということになります。

Auto Compactの正体

Compact=「圧縮」というと何か物事をギュッと詰め込んでいるようなイメージですが、実際のところ行っているのは会話の「要約」です。

詳しい仕様は公開されていませんが、重要なコンテキストとして判断した会話の履歴の概要をまとめて次のInputの中に入力しています。

またあまり活用している例をみませんが、CLAUDE.mdに以下のように Summary instructionsという項目を作るとその指示に応じて圧縮を行ってくれます。

# Summary instructions

コンパクトを使用する時は、コードの変更内容についてフォーカスしてください。

コンテキストウィンドウに常駐するもの

ここまで見て、20万トークンのうちすでに約30％がシステム側で使用されていることがわかりました。

ユーザーが利用できるのは残りの70％程度となりますが、もう少し詳細に見ていくとコンテキストウィンドウに常駐しているものの存在が明らかになってきます。

CLAUDE.md

まず、Claudeがセッション間で受け継ぐための記憶として機能する「CLAUDE.md」の存在です。

これはセッション開始時に常に読み込まれてコンテキストに含まれます。

なので記憶を引き継がせるために仕様を入れすぎると、必然的に大きくなります。

CLAUDE.mdが大きすぎるとパフォーマンスに影響が出るため、以下のような警告が表示されるようになります。

 ⚠ Large CLAUDE.md will impact performance (93.7k chars > 40.0k) • /memory to edit

MCPサーバー

次はMCPサーバーです。

「MCPサーバー」は様々な外部サービスと接続することで、便利な機能をClaude Codeに実装できるため、うっかり何でもかんでも入れてしまいがちです。

使わないスキーマ定義まで全部保持するため、たとえばGetメソッドだけ使いたいのに、PostメソッドやPutメソッドもずっと保持し続けてしまう、というような非効率な側面があります。

さらに、便利なのでいつでも呼び出したいからといって、ユーザー定義側にMCPサーバーを追加しすると無駄なコンテキストを占有し続けます。

また、Git連携のためにGitHubのMCPサーバーを使っている方も多いようですが、筆者としては、ghコマンドをインストールしClaudeには都度、

> ghコマンドでリポジトリを作って

などと指示した方が効率が良いと考えています。

カスタムエージェント

「カスタムエージェント」も意識する必要があります。

カスタムエージェントを活用して、たとえばテストやフロントエンド、バックエンドやインフラの専門家といった様々な特色を持ったエージェントを独立した形で作ることが可能です。

カスタムエージェントはユーザーが指示しなくてもClaude Codeが自由に自己判断で呼び出して使えるようになっているため、常駐します。

ただし、カスタムエージェント自体の中身は単なるプロンプトであるため、占有率自体は大きくないことが多いです。

カスタムスラッシュコマンド

これは筆者も意外だったのですが、カスタムスラッシュコマンドも常駐します。

ただしカスタムエージェントと同じく中身はプロンプトであるため、占有は小さいことが多いです。

コンテキストウィンドウを占有しないもの

HooksやAgent Skillsは後述するようにコンテキストウィンドウを占有しません。

Hooks

任意のタイミングでコードを実行できる「Hooks」は基本的には常駐しないようです。

おそらくHooksはシステムプロンプト内で発火のための記載はあると思われますが、そのコードの中身自体をClaudeが知っておく必要がないため、記載されていません。

本当にそうなのか、筆者が試しにsettings.local.jsonの設定ファイルの中に『坊ちゃん』の本文を入れてClaude Codeを再起動してみました。

しかし、以下のようにコンテキストウィンドウが変わることはありませんでした。

Agent Skills

鳴物入りで登場したAgent Skillsですが、コンテキスト効率が高い設計になっているのもAnthropicが薦める理由です。

先述のMCPは呼び出すつもりがない定義も全て常時読み込んでしまうのに対して、常駐するのはSKILL.mdにある最上部のディレクティブのみです。

たとえば、筆者は「TypeScriptファイルを作成した際に、Lintチェックを行ってくれるスキル」をClaudeに指示して作ってもらったことがありますが、その設定ファイルである、SKILL.mdは下記のようになっていました。

---
name: lint-checker
description: エージェントがTypeScriptやJavaScriptファイルを編集・作成した後に、ESLintで構文チェックを行い、エラーがあれば自動修正を試みます。編集完了後のコード品質チェックに使用してください。
---

# Lint Checker Skill

このスキルは、ファイル編集後のコード品質を自動的にチェックし、問題があれば修正します。

## 使用タイミング

以下の状況で自動的に使用されます：
（省略）

SKILL.mdの上部にそのスキルについて説明するnameとdescriptionがあります。その下に概要や手順、実行すべきコマンド、期待するアウトプットなどが並びます。

要点としてはこの最初のディレクティブ部分だけがClaudeには読み込まれている、というのと、このnameとdescriptionには文字数の制約があり、nameは英数字のみ使用可能で最大64文字、descriptionは最大1024文字としなければなりません[5]。

ClaudeはSKILL.mdの見出しの部分だけを保持することで、100トークン以下の占有で済むように設計されています。

そして、このnameとdescriptionを元に、いつ何のスキルを発動させるかを判断し、必要に応じてその下の手順の内容を読み込み、スキルを使用します。

このように非常にトークン効率の良い設計となっています。

IDE連携

もう一つお伝えしたいのはIDE連携で読み込まれるコンテキストです。

/ideコマンドを使ってIDE連携を行うと、VS CodeやCursorでユーザーが開いている内容やカーソルで選択している箇所が自動でClaudeに送られます。

そのため、うっかり何か別のファイルを開いている場合、全く関係ないコンテキストを送ることになります。

対話モードの右下に青文字でファイル名が出ていたら、コンテキストに含まれます。

筆者がなんとなく開いたNext.jsのpage.tsxで計測してみると2,000トークンほどありました。

もしこのページと関係ない処理をClaudeが行なっている場合、無駄に2,000トークンをClaudeに保持させ続けることになります。

また、IDE連携では、うっかり.envなどの秘匿情報も開いた状態にしておくと、それもコンテキストに含めてしまうことになりますので、セキュリティ上の注意が必要です。

このような事態を避けるため/ideコマンドを使ってIDEとの連携を切ってる方もいます。

ただ、もちろん便利な側面もあって、容易にファイル情報をClaudeに送れるのみならず、IDEからのTypeCheckエラーやLintエラー、型エラーなどもClaudeが必要に応じて取得できるようになります。

使い方をしっかりと理解して使うことが大事だと思います。

まとめ

今回は「コンテキストウィンドウを理解する」というテーマでした。

LLM時代になって「コンテキストウィンドウという制限の中でいかにエンジニアリングを行うか」ということが本格的に問われてきているように思います。

今回はその内容を噛み砕いて掘り下げることで、皆さんの今後のClaude Codeの開発に生かしてもらえれば幸いです。

下記にカスタムツール群とコンテキスト占有について筆者なりにまとめてみました。

コンテキストの占有を意識しながら、これらのツールを適切に使い分けるようにしましょう。

次回はCLAUDE.mdについて深堀りして解説したいと思います。　お楽しみに！