Claude Codeは、CLI上で動くLLMによるAI開発支援ツールです。本連載は全4回を予定しています。実務経験1～3年程度のエンジニア向けに、対話モードでの会話の基本、コンテキストと＠記法、スラッシュコマンドとパーミッションの基本を解説し、最後に学んだ知識を総動員してアプリ開発をハンズオンで体験します。なお本連載は2026年9月刊行予定の『Claude Codeで作って学ぶ AI駆動アプリ開発入門』から一部、抜粋・編集してお届けします。

第2回目は、Claude Codeが情報を扱う仕組みである「コンテキスト」を説明した後、Claude Codeに指定したファイルを読み込ませる「@記法」について説明します。

コンテキストの正体を知ろう

ここからは、Claude Codeが情報を扱う仕組みの全体像を解説します。この仕組みを理解しておくと、Claude Codeの回答品質を高い状態に保つ判断がしやすくなります。「⁠コンテキスト」は、AIが参照する情報全体を指す概念です。このコンテキストを格納する領域がコンテキストウィンドウです。

イメージとしては、限られたスペースの「作業机」を思い浮かべてください。対話のたびに入力したテキストや、Claude Codeが読み込んだファイルの内容がこの机の上に積み上がっていきます。つまり、コンテキストは机の上の書類、コンテキストウィンドウはその机自体に相当します。

ここで重要なのは、コンテキストウィンドウには上限があるという点です。残りスペースを管理するには、容量がどのような単位で測られているかを知っておく必要があります。その単位が「トークン」です。

トークンとは、AIがテキストを処理する際の最小単位です。日本語の場合、ひらがな・カタカナは1文字1トークン程度、漢字は1文字で2〜3トークンになることもあります。なお、コンテキストウィンドウの容量はモデルによって異なりますが、目安は200k（20万）トークン程度です。日本語にしておよそ5万〜10万文字程度、書籍1冊分に近い分量に相当します。

一見すると十分なスペースに思えますが、対話を続けるほどコンテキストは増えていきます。いつの間にか上限に近づいていた、ということも珍しくありません。

コンテキストに何が含まれているかを知ろう

コンテキストウィンドウには上限があることがわかりました。次に把握しておきたいのは、コンテキストに実際に何が含まれているかです。自分が入力したテキストだけが含まれていると思いがちですが、実はそうではありません。コンテキストには、起動時から固定で含まれるものと、対話を重ねるうちに追加されるものがあります。代表的なものは以下のとおりです。

この4つが、どのセッションでもコンテキストに含まれる基本要素です。ほかにも設定内容に応じて追加の情報が含まれることがあります。特にツール情報やシステムプロンプトは、ユーザーが意識しないまま一定量を占めています。

対話のたびに入力テキストと応答が会話履歴に追加され、ファイルの読み込みやコマンドの実行結果も加わります。つまり、自分が入力したテキストはコンテキストのごく一部にすぎません。会話履歴・読み込んだファイル・システムプロンプト・ツール情報が積み重なり、気づかぬうちに多くのスペースを占めているのです。

コンテキストが上限に近づくとどうなるかを知ろう

ここまで見てきたとおり、ツール情報やシステムプロンプトがユーザーの見えないところでスペースを占めています。この限られたスペースが上限に近づくと、2つの変化が生じます。1つは応答精度の低下、もう1つは自動コンパクトの発動です。

応答精度の低下

情報が多すぎると、Claude Codeが重要なポイントを見落としやすくなります。たとえば、セッションの序盤に伝えたコーディングルールを忘れて別のスタイルでコードを生成する、指示と無関係なファイルを参照し始める、といった現象が起こり得ます。

Claude Codeはこの問題に対処するため、コンテキストが上限に近づくと自動的に情報を整理する仕組みを備えています。

自動コンパクトの発動

この仕組みが自動コンパクト（Auto compact）です。会話履歴を要約し、コンテキストのスペースを確保します。ただし、要約の過程で細かい情報が失われることがあります。

自動コンパクトの発動が近いかどうかは、画面の表示から判断できます。コンテキストが上限に近づくと、対話モードの画面右下に残り容量が表示されます。

この表示が出たら、まもなく自動コンパクトが発動するサインです。このまま会話や作業を続けてコンテキストの残りが0%に達すると、自動コンパクトが発動します。画面に「Compacting conversation...」と表示され、会話履歴の要約処理が進みます。

要約が完了すると、コンテキストが整理されて作業を続けられます。

/context でコンテキストの使用状況を確認しよう

自動コンパクトが発動する前に使用状況を把握しておくと、適切な判断ができます。/context コマンドを実行すると、コンテキストの使用状況と残りスペースを一目で確認できます。

> /context

実行すると、グリッド表示で使用率と内訳が出力されます。注目すべきはFree space（残りスペース）の割合です。

> /context

   Context Usage
   ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁    claude-opus-4-6 · 51k/200k tokens (25%)
   ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁
   ⛁ ⛁ ⛁ ⛁ ⛶ ⛶ ⛶ ⛶ ⛶    Estimated usage by category
   ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶     ⛁ System prompt: 2.8k tokens (1.4%)
   ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶     ⛁ System tools: 26.0k tokens (13.0%)
   ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶     ⛁ MCP tools: 5.5k tokens (2.8%)
   ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶     ⛁ Custom agents: 6.6k tokens (3.3%)
   ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶     ⛁ Memory files: 4.9k tokens (2.4%)
   ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶     ⛁ Skills: 4.9k tokens (2.4%)
   ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶     ⛁ Messages: 8 tokens (0.0%)
   ⛶ ⛶ ⛶ ⛛ ⛛ ⛛ ⛛ ⛛ ⛛     ⛶ Free space: 116k (58.1%)
   ⛛ ⛛ ⛛ ⛛ ⛛ ⛛ ⛛ ⛛ ⛛     ⛛ Autocompact buffer: 33.0k tokens (16.5%)
   ⛛ ⛛ ⛛ ⛛ ⛛ ⛛ ⛛ ⛛ ⛛

この例では使用率が25%で、まだ余裕がある状態です。対話を始めたばかりの時点でも、ツール情報やシステムプロンプトだけでコンテキストの1〜2割程度を占めていることがわかります。会話を続けるほどMessagesの割合が増え、Free spaceが減っていきます。

応答が遅くなったとき、精度が落ちたと感じたとき、長時間のセッションを続けているときに /contextを確認する習慣をつけておくとよいでしょう。

コンテキストの管理方法を押さえよう

残りスペースが少ないとわかったら、具体的な対処が必要です。Claude Codeには、コンテキストを管理するための/clearと/compactの2つのコマンドが用意されています。

/clear は「コンテキストをリセットする」

セッション内の会話履歴をリセットし、コンテキストを空の状態に戻すコマンドです。/clearコマンドを実行するまでのコンテキストを引き継がず、リセットした状態から作業を開始できます。なお、CLAUDE.mdなどの設定情報は自動で再読み込みされるため、プロジェクトのルールはそのまま引き継がれます。

使うタイミングはタスクが完了して別のタスクに移るときです。たとえば「認証機能の実装が終わったので、次は画面のデザイン修正に取りかかる」という場面です。前のタスクのコンテキストが残っていると、Claude Codeが無関係な文脈に引きずられることがあります。タスクの切り替え時に/clearを実行すると、新しいタスクに集中できます。

/compact は「整理しながら続ける」

コンテキストを整理・圧縮してスペースを確保するコマンドです。/clearとは異なり会話内容を部分的に引き継ぐため、長いタスクを継続したいときに適しています。

また、「⁠/compact 検索機能の実装内容にフォーカスして」のように、保持したい内容を指示として添えることもできます。特定のトピックを重点的に残しながら、それ以外の会話部分を圧縮したいときに便利です。

/clearと/compactの使い分け

「ここまでの会話の内容はもう不要で、新しいタスクに取りかかる」なら/clearを使います。会話の流れを引き継ぎながらコンテキストを整理したい場合は /compactを使います。

コンテキストウィンドウのまとめ

コンテキストウィンドウはClaude Codeの記憶領域で、会話履歴・読み込んだファイル・システムプロンプト・ツール情報が積み上がります。上限に近づくと自動コンパクトが発動し、細かい情報が失われることがあります。

/contextで使用状況を確認し、新しいタスクへ切り替えるときは /clearでリセット、会話の流れを引き継ぎながら圧縮したいときは /compactを使いましょう。

Claude Codeにファイルを「見せる」方法を知ろう

前半では、Claude Codeにはコンテキストウィンドウがあり、会話履歴や読み込んだファイルなどが蓄積されることを学びました。ここからは、ファイルの内容をコンテキストに読み込ませる方法を見ていきましょう。

Claude Codeはプロジェクトのファイルをすべて自動で読んでいるわけではありません。プロジェクトに100個のファイルがあっても、その中から必要なファイルを指示して、コンテキストに読み込ませる必要があります。

その手段が@記法です。@記法とは、対話中に「@ファイルパス」と入力することで、指定したファイルの内容をコンテキストに読み込ませる仕組みです。前半で学んだコンテキスト内の「読み込んだファイル」は、この@記法を使って自分の意思で追加できます。

@記法の基本的な使い方を試してみよう

@記法の使い方はシンプルです。対話中に@の後にファイルパスを入力するだけです。@に続けてファイルパスを途中まで入力すると候補が表示されます。

> @src/

  + src/
  + src/app.js
  + src/utils.js

ここで、候補の中から上下キーで対象のファイルを選択し、Enterキーで選択するとファイルの内容がコンテキストに読み込まれます。

> @src/app.js

続けて、そのファイルに関してのプロンプトを入力すると、そのファイルの内容がコンテキストに読み込まれた状態で回答してくれます。以下はsrc/app.jsというファイルの内容を説明させる例です。

> @src/app.js の内容を説明して

このように入力すると、src/app.jsの内容をすべてコンテキストに読み込んでから、その内容に基づいて回答してくれます。

> @src/app.js を読んで
    Read src/app.js (68 lines)

Claude Codeが思考を行う前に、68行分のファイルを読み込んでいることがわかります。

パスの指定方法

ファイルパスは、Claude Codeを起動したディレクトリ（プロジェクトルート）からの相対パスで指定します。絶対パスも使えますが、プロジェクト内のファイルを指定する場合は相対パスのほうが便利です。

例えば、以下のようなファイル構成のプロジェクトがあるとしましょう。

my-project/
├── src/
│   ├── app.js
│   └── components/
│       └── Header.tsx
├── package.json
└── README.md

この場合、src/components/Header.tsx を参照するには次のように指定します。

> @src/components/Header.tsx を確認して

@記法でファイルパスを入力すると候補が表示されますので、候補の中から選ぶ方法が確実です。

@記法と自然言語指示の違い

プロンプトで「src/app.jsを見て」と自然言語で指示しても、@記法を使わなくてもClaude Codeはファイルを探して読んでくれます。ただし、2つの方法には違いがあります。

@記法はプロンプトの送信時点でファイルの内容がコンテキストに入るため、より確実にファイルの内容を踏まえた回答が得られます。なお、@記法はファイル全体を読み込むため、大きなファイルではコンテキストの消費が大きくなります。

一方、自然言語での指示は、指示した範囲だけを読み込める点が特徴です。たとえば「src/app.jsの1〜20行目を読んで」と指示すると、Claude Codeは指定した行だけを読み込みます。

> src/app.js の1~20行目を読んで

● Read(src/app.js)
    Read 20 lines

「Read 20 lines」と表示されており、1〜20行目だけが読み込まれたことがわかります。

日常的にはどちらの方法でも問題ありませんが、ファイル全体を確実に読ませたいときは@記法、特定の行だけを読み込ませたいときは自然言語での指示と使い分けましょう[1]。

複数のファイルを一度に読み込ませよう

ヘッダーとフッターのコンポーネントを統一したい、APIクライアントとその型定義を合わせて確認したい。そのような場面では、複数のファイルを同時に指定することができます。スペース区切りで @記法を並べるだけです。

> @src/app.js と @src/utils.js を比較して

便利な一方で、読み込むファイルが増えるほどコンテキストを消費します。なお、@記法ではフォルダを指定することもできます。その場合はファイルの内容ではなく、フォルダ内のファイル一覧が読み込まれます。

コンテキストを意識したファイル参照のコツを押さえよう

@記法でファイルを読み込ませるのは簡単ですが、読み込ませればよいというわけではありません。闇雲にファイルを読み込ませると、会話の途中でClaude Codeの回答品質が下がったり、早い段階でコンテキストの整理が必要になったりします。これを防ぐための実践的なコツを2つ押さえておきましょう。

大きなファイルは部分読み込みを検討する

大きなファイルほどコンテキストを多く消費します。数千行あるファイルを丸ごと読み込ませると、それだけでコンテキストウィンドウの大部分が埋まり、その後の作業に必要な容量を確保できなくなります。

ファイル全体を参照する必要がない場合は、「⁠◯◯の関数だけ読んで」のように、読みたい箇所を自然言語で指定して部分的に読み込ませる方法が有効です。行番号がわからなくても、Claude Codeが該当箇所を探して必要な範囲だけを読み込みます。

必要なファイルだけを参照する

ファイルサイズに次いで意識したいのが、ファイルの数です。「⁠念のためこのファイルも」と追加したくなることがありますが、むやみに多くのファイルを読み込ませるよりも、質問に直接関係するファイルに絞ったほうが、Claude Codeはそのファイルに集中して正確な回答を返してくれます。

ファイルの読み込ませ方のまとめ

@記法（@ファイルパス）を使うと、対話中にファイルの内容をコンテキストに読み込ませることができます。パスはプロジェクトルートからの相対パスで指定し、複数ファイルの同時指定も可能です。

コンテキストウィンドウの容量は限られているため、参照するファイルのサイズと数を意識して活用しましょう。

次回は、Claude Codeの対話モード内の操作や設定を行う「スラッシュコマンド」を紹介します。