Claude Codeがプロジェクト全体を読み直す理由と、その解決方法

Ailootドキュメント：API、キー、接続。

Claude Codeはなぜ毎回プロジェクトを最初から読み直すのか？#

多くの人はこれをバグだと思っています。実際には、これがClaude Codeの設計です。独自のプロジェクトインデックスはありません。何かを修正するよう頼むと、すぐに使えるコードマップがないため、関連ファイルを探し、必要な文字列を検索し、ファイルをメモリに読み込んで、プロジェクトをもう一度調べます。

この方法には実際の利点があります。古くなったインデックスがないため、コードは常に最新です。設定も不要です。コードがデータベースに送信されることもありません。

ただし、欠点もあります。新しいタスクのたびに検索とファイル読み込みをやり直します。Claudeが前のセッションですでに把握した内容でも、どこに何があるかを再び調べるためにトークンを費やします。プロジェクトが大きいほど、この状況把握にはコストがかかります。そのため、エージェントが「全部読んでいる」ように感じられるのです。

実際にどれくらいのトークンを消費するのか？#

コストは、リクエストを送る前から発生しています。ある独立した単純な測定によると、Claude Codeはユーザーのメッセージの最初の1文字を読む前に、システムプロンプトとツールの説明だけで約33,000トークンを送信します。比較すると、OpenCodeは約7,000トークンから始まります。

次にファイルの読み直しが加わります。ファイルの検索や読み込みのたびに、コンテキストへトークンが追加されます。Claude Codeの公式ドキュメントも、コンテキスト使用量の大半をファイルの読み込みが占めると明言しています。2,400トークンのauth.tsを分析すると、その2,400トークンがClaudeに見られます。状況把握のために開くファイルすべてに同じことが当てはまります。

私たちの読者にとって、これはお金と利用上限の問題です。バイブコーディングを始めた人が最も恐れるのは、「課金したのに、何も得られないまま上限に達した」です。エージェントがタスクのたびにプロジェクトをスキャンし、ファイルを最初から読み直すと、コンテキストは2倍の速さで消費されます。まずシステムのオーバーヘッドに、次に状況把握に使われるからです。Claude Codeのトークンがどこに使われるのかを網羅したガイド「Claude Codeのトークンはどこに使われるのか」では、プロジェクトの読み直しを9つのパターンの1つとして取り上げました。

永続的なコードメモリとは？#

コードメモリは、Claudeがプロジェクトを読み直す原因となるギャップを埋めます。仕組みはシンプルです。何かにコードを一度すべてスキャンさせ、そこからマップを作り、すぐ参照できるように保管します。そうすれば、エージェントは毎回最初から検索せず、マップに問い合わせられます。

技術的には、次のように動作します。別のツールがプロジェクトをスキャンし、関数やクラス、呼び出し元と呼び出し先、関連するファイルなどの要素に分解します。この構造はディスクに保存されます。Claudeが支払いロジックの場所や、関数を編集すると何が壊れるかを知る必要があるときは、何十ものファイルを読む代わりに、マップへ的を絞って1回問い合わせます。

このマップはMCP経由で接続します。MCPはClaude Codeに外部ツールを接続する標準的な方法です（ほかのサーバーの接続方法は「Claude Code用MCPサーバー」で解説しました）。コードメモリツールは独自のマップ検索コマンドを追加し、Claudeはプロジェクトの状況を把握する必要があるときに、それを自分で使います。

実際の違いは、「1つの関数を探すためにフォルダー全体を読む」か、「その関数の場所をマップに尋ねる」かです。前者は数万トークン、後者は数百トークンを消費します。

コードメモリの2つの方法はどう違うのか？#

コードメモリツールは、プロジェクトから何を作るかによって異なります。分かりやすく言えば、1つは外科医のように正確に編集できる手段を与え、もう1つは意味で検索します。

GitHubスター数は2026年7月15日時点のものです（GitHub APIによる）。2つとも無料のオープンソースでClaude Codeに対応し、MCPサーバーとして接続できます。

プログラマーでない人向けに要点をまとめます。Serenaは外科医の手のようなツールです。プロジェクト内の同じ箇所を何度も編集し、正確さが大切なときに使います。claude-contextは意味ベースの検索です。説明からコードを探せますが、クラウドデータベースの設定とキーが必要です。

Serenaやclaude-contextを選ぶべきなのはどんなとき？#

2つのツールは、1つの賞を争っているわけではありません。それぞれ記憶する内容が違うため、選択はタスクによって変わります。

リファクタリングを頻繁に行うならSerenaを選びましょう。インテリジェントな開発環境のようなコードナビゲーション機能をエージェントに与えます。関数の定義と実際の呼び出し箇所をすべて見つけ、その後、関数の名前を変更したり本体をプロジェクト全体で置き換えたりします。作者はその利点を次のように説明しています。

Serenaは節約率を公表していないため、架空の数値を当てはめるつもりはありません。通常の検索ではコメントや文字列も含めて40件の一致が返され、そのあとClaudeがファイル全体を4つ読むような場合でも、Serenaなら少数の正確な問い合わせで答えられる点が利点です。呼び出し回数と誤一致が減り、エージェントが誤った箇所を編集するリスクも下がります。

意味ベースの検索が必要で、設定の手間も気にならないならclaude-contextを選びましょう。コードをベクトル（意味を数値化した指紋）に変換し、「支払いロジックがどこにあるか探して」のような説明で検索します。関数名を知らなくても見つけられます。この検索には追加の設定が必要です。

claude-contextには、外部ベクトルデータベース、埋め込みプロバイダーのキー、最近のバージョンのNodeが必要です。2つのうち設定がより複雑なので、初心者には別のものから始めることをおすすめします。

サードパーティ製ツールなしでClaude Code内からできることは？#

サードパーティ製ツールをインストールする前に、Claude Codeにすでに備わっている機能を活用しましょう。これらのコマンドは無料で、すぐに使えます。

1. /context—システムプロンプト、CLAUDE.md、メモリ、ツール、ファイルなど、ウィンドウを占めている内容の内訳をリアルタイムで表示します。/mcpコマンドでは接続済みの各サーバーのコストが、/memoryでは起動時に読み込まれた内容が分かります。
2. /compact—会話履歴を短い要約に圧縮し、同じタスクを続けます。保持したい内容を/compactに加えて、要約の焦点を指定できます。
3. /clear—履歴全体を消去します。公式の推奨では、関係のないタスクに切り替えるときに実行します。古い会話が必要なファイルを押しのけないようにするためです。
4. /doctor（/checkupとも呼ばれ、2026年7月8日に導入）—構成を診断し、修正を提案します。CLAUDE.mdの重複を削除し、未使用のツールやサーバーを見つけ、遅いハンドラーを検出します。

CLAUDE.mdについて補足します。このファイルは各セッションの開始時にコンテキストへ読み込まれ、すべてのメッセージに含まれます。大きすぎると、その分のコストを払い続けます。公式では、200行未満に保ち、参照用の詳細は必要なときに読み込むスキルへ移すことを推奨しています。CLAUDE.mdを適切に設定する方法は、別のガイド「CLAUDE.mdの設定方法」で解説しました。

組み込み機能には、もう1つサブエージェントがあります。独自のコンテキストを持つため、大量の読み込みや状況把握を任せても、メインのウィンドウを膨らませずに済みます。Anthropicは、エンジニアリング分析で一般原則を次のように述べています。

MCPサーバーを追加するとコンテキストはさらに大きくなる？#

「サーバーをもう1つ追加すればコンテキストのオーバーヘッドが増える」という考えは以前は正しかったものの、Claude Codeは変わりました。MCPツールの説明はデフォルトで後から読み込まれます。起動時にはサーバー名だけがコンテキストに含まれ、タスクで特定のツールが必要になったときに、説明全体が読み込まれます。ドキュメントにも明記されています。

コードメモリの計算は単純です。ツール名にかかるわずかな固定オーバーヘッドと、エージェントがファイルを読み直さなくなることで節約できる数千トークンを比べれば、インデックスを使うほうが明らかに有利です。

魔法のような効果を期待しないよう、正直な注意点もいくつかあります。インデックスはときどき再構築が必要です。マップにはスキャン時点のコードが反映されるため、大幅な編集後は更新が必要です（更新方法はツールによって異なり、自動で行うものもあれば、コマンドが必要なものもあります）。また、「トークンを120倍節約」といった大きな数字は、選ばれた質問での最良のケースを示すもので、どのタスクでも得られる結果ではありません。実際の節約幅はもっと控えめですが、それでも効果は感じられます。一般に利用上限に達しない方法を詳しく知りたい場合は、別の分析記事「Claude Codeの利用上限を使い切らない方法」をご覧ください。

今日から何を始めればよい？#

不要なものを省けば、今日やることはシンプルです。

1. /doctorを実行し、提案された内容を整理します。CLAUDE.mdの重複や未使用のツールなどです。
2. CLAUDE.mdを200行まで減らし、参照資料をスキルへ移します。

その後、必要に応じて選びましょう。リファクタリングを頻繁に行うなら、正確な編集ができるSerenaを追加します。意味ベースの検索が必要なら、claude-contextを設定します。コードメモリと整理されたコンテキストで、今日の主な問題は解決できます。

Ailoot経由でAIモデルを利用したい場合は、Ailootをご覧ください。