【Claude Code】ファイルが存在するのに参照できない原因と対処法を初心者向けに解説

Claude Codeで「ファイルが存在するのに参照できない…」という現象に悩んでいませんか？
本記事では、初心者でも理解できるように“原因3つ”と“確実に解決できる対処法”をわかりやすく解説します。
「@でファイルが出てこない」「インデックスされない」などのトラブルを最短で解決したい方に最適です。

【Claude Code】ファイルが存在するのに参照できない

はい、そのご認識は技術的に極めて鋭い視点です！

結論から言うと、「Claude Codeを起動した『後』に作成したファイルが即座にインデックス（認識）されない」というのは、実際に起こり得る現象です。

なぜそのようなことが起きるのか、主な原因を3つのポイントで整理しました。

---

1. ファイルシステムの監視（File Watching）の遅延

Claude Codeは起動時にディレクトリ構造をスキャンし、@で呼び出せるようにインデックスを作成します。 通常はファイルの変更を監視していますが、以下のような条件下では認識が漏れたり、反映に時間がかかったりすることがあります。

• OS側の制限: 大規模なプロジェクトだと、OSのファイル監視数（inotifyなど）の上限に達し、新規ファイルの検知が止まってしまうことがあります。
• エディタの保存ラグ: 外部のエディタ（VS Codeなど）で保存した直後は、まだ Claude Code 側に通知が届いていない瞬間があります。

2. インデックス更新のタイミング

Claude Codeは、ターミナルの「入力待ち」の状態の時にバックグラウンドでインデックスを更新しようとしますが、複雑な処理中やメモリ負荷が高い状態だと、新しいファイルの反映が後回しになる場合があります。

3. .gitignore や設定の影響

もし作成したファイルが .gitignore に含まれるディレクトリ内であったり、隠しフォルダに近い構成だったりすると、起動時のスキャン対象から外れる（あるいは意図的に除外される）ことがあります。

【Claude Code】ファイルを参照できない場合の対処法

認識されない時の「おまじない」

もし @ で出てこない場合は、以下のアクションを試すと解決することが多いです。

• パスを直接入力する: @ の後にファイル名の最初の数文字を打って少し待つか、相対パス（./new_file.py など）を直接打ち込むと、強制的に認識しにいくことがあります。
• 一度 ls を叩かせる: Claude Code内で /run ls（あるいは単に ls）を実行させ、現在のディレクトリにファイルが存在することをAIに視覚的に認識させると、その後のコンテキストに乗りやすくなります。
• /exit→claudeで再起動

生成AIの注意点