# AIコーディングエージェントがファイルパスを幻覚する理由

Canonical source: https://maguyva.ai/ja/blog/why-ai-coding-agents-hallucinate-file-paths

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-08-14 · Author: Maguyva Team

> AIコーディングエージェントは、リポジトリの本物のマップを持っていないとき、ファイルパスを捏造します。なぜそれが起きるのか、そして根拠を持たせることがどのように幻覚編集の減少につながるのかを説明します。

その兆候は、間違った関数本体ではありません。存在しないファイル、あるいは存在してもその振る舞いを実装していないファイルに対する、自信満々の編集です。

あなたはセッション有効期限の修正を依頼しました。エージェントは`src/auth/session.ts`を開きました。そのパスはもっともらしい。そして間違ってもいます。本物のハンドラーは`apps/api/src/middleware/expiry.ts`にあり、二回のリファクタリング前に名前が変わりました。エージェントはあなたに嘘をついたわけではありません。訓練事前知識と、すでにコンテキストウィンドウにあったものを組み合わせて、パス形状の文字列を補完しただけです。

これは実際のリポジトリでよくある失敗パターンです。モデルはコードを書けます。ミスは、書く場所を間違えることにあります。

## エージェントがパスを捏造する理由

コーディングエージェントは、ツールを持った次トークン予測モデルです。「セッション有効期限を直して」と言うと、何かを読んだりパッチしたりする前に、まずファイルを一つ名指ししなければなりません。まだ根拠のあるマップを持っていない場合、次のものからパスを構築します。

1. 他のリポジトリで見た命名規則。`src/auth/session.ts`はよくある形です。
2. すでに会話にあるファイル。それは今重要なものではなく、先週貼り付けたものかもしれません。
3. たまたま実行したディレクトリ一覧。大きなツリーでは不完全です。
4. 指示ファイル。`CLAUDE.md`と`AGENTS.md`はエージェントにどう振る舞うべきかを伝えます。それらはシンボルや呼び出し元、現在のパスの生きたインデックスではありません。

これらの出典のどれも、今日のこのリポジトリのマップではありません。モデルは、どんな空白でも埋めるのと同じ方法で、この空白を埋めます。確率の高い続きでです。その続きは、しばしば本物のパスのように見えます。ファイルが存在していて、正しいファイルの隣にあることもあります。先月マージされたブランチに存在していたこともあります。一度も存在しなかったこともあります。

エージェントが正しい文字列をそもそも検索していないなら、ここではgrepもあなたを救いません。エージェントはパスを推測し、そのパスが返したものを読み、それを編集しました。最初の誤ったステップはパスであり、パッチではありませんでした。

ファイルを読むことも、正しいファイルを見つけることと同じではありません。Claude Code、Cursor、Codex、そして似たようなツールは、あなたが指し示すものなら何でも開けます。問題は、編集する前に、正しいファイル、重要なシンボル、依存関係、テスト、そして影響範囲を確実に見つけられるかどうかです。マップのないファイルアクセスは、依然として推測から始まります。

## 間違ったファイルの編集は検索の問題である

捏造されたパスを、性格上の欠陥としてではなく、検索の見当違いとして扱ってください。

エージェントが編集を許可される前に`path/file.ext:line`を返さなければならないとしたら、二つのことが起きます。第一に、あなたはその引用を開いて、十秒でその作業を却下できます。第二に、エージェントは実際にツリーを知っている何かに問い合わせなければならなくなります。

それがコードベース・コンテキストレイヤーの仕事です。セマンティック検索だけでは十分ではありません。「セッション有効期限っぽく聞こえる」断片が、それでも廃止されたパッケージに着地することがあります。文字列を知っているときには正確なテキストも、名前を知っているときにはシンボル検索も、形を知っているときには構造検索も、呼び出し元と影響範囲が必要なときには依存関係グラフも必要です。

Maguyvaは、MCP互換のコーディングエージェント向けのそのレイヤーです。エディタではありません。Claude Code、Cursor、Codex CLI、VS Code、Windsurf、そして他のMCPクライアントは、それぞれいた場所に留まります。エージェントは、一行に触れる前にランク付けされたマップに問い合わせます。

その主張は意図的に控えめです。幻覚編集が減ること。Maguyvaはモデルから推測する能力を奪いません。デフォルトの最初のステップを、「もっともらしいパスを捏造する」ことから、「ランク付けされ引用された場所を要求する」ことへと変えるだけです。

## 根拠のある答えとはどんなものか

「セッション有効期限はどこで処理されているか」に対する有用な答えは、一つの段落ではありません。短い場所のリストです。

- `apps/api/src/middleware/expiry.ts:48` - ハンドラー
- `apps/web/src/lib/auth-client.ts:112` - 呼び出し元
- `apps/api/tests/expiry.test.ts:20` - 変更が間違っていれば失敗するテスト

あなたはこれらの行を開けます。間違っていれば、そこで止まります。正しければ、エージェントは編集してもかまいません。ポイントは検証であって、スローガンではありません。

Maguyvaは、検索、シンボル、依存関係分析、ファイル取得、リポジトリコンテキスト、決定論的なユーティリティワークフローにまたがる11の顧客向けMCPツールを提供します。四つの検索モード(セマンティック、構造、グラフ/依存関係、テキスト)がランク付けされた結果に融合され、シンボル検索は独立したMCPツール(`find_symbol`)です。根拠のある答えはファイルパスと行番号とともに返ってくるため、目の前のツリーと照らし合わせて評価できます。

[ドキュメント](/ja/docs)は最短経路を説明しています。無料で始め、すでに知っているリポジトリをインデックスし、クライアントを接続し、それから確認できる質問を尋ねる。

## 最初の編集を変えるループ

新しいワークフローの信条は必要ありません。最初に書く前に、もう一つのステップが必要なだけです。

1. すでに評価できる質問をしてください。「ログインとセッション有効期限を扱うコードは何か」は「認証を直して」よりも優れています。
2. 引用を要求してください。「認証モジュール」の要約ではなく、ファイルパスと行番号を。
3. 引用されたファイルを開いてください。シンボルをたどってください。今から触れようとしている依存関係を確認してください。
4. そのときになって初めて、エージェントにパッチさせてください。

ステップ2が何も有用なものを返さない場合、エージェントにはパスを即興で作る資格がありません。もう一度検索するか、あなたが指し示します。この一つの関門こそが、幻覚編集の減少を生み出します。モデルは同じモデルです。変わったのはマップのほうです。

指示ファイルは依然として重要です。維持してください。慣習、レビュールール、触れてはいけないもののために使ってください。それらにインデックスであることを求めないでください。三つの重要なディレクトリを列挙した`CLAUDE.md`は、パッケージ分割の翌週には古くなります。問い合わせ可能なマップは、リポジトリが更新されれば更新されます。

関連する失敗は、惜しいファイルです。振る舞いが`auth-client.ts`にあるのに、エージェントが`auth.ts`を開く。ソースの代わりに生成されたファイルにパッチを当てる。あるいは、名前が一致したという理由で`packages/legacy`のコピーを編集する。引用は、そうしたミスを不可能にするわけではありません。diffが着地する前に、それらを見えるようにするだけです。

## マップがあなたのために解決してくれないこと

何を得ているのかについて、冷静でいてください。根拠のあるマップは、すべての編集を正しくしてくれるわけではありません──あなたのエージェントは、まさに正しいファイルの中で、それでも悪いパッチを書くことがあります。あなたのコードベースが動的ディスパッチ、リフレクション、モンキーパッチに依存しているなら、一部のシンボル検索は、あなたが望むよりも薄い結果を返すでしょう。実行時の間接性が、どんな静的インデックスにもそうさせるからです。そして、もしあなたがパーセンテージを期待しているなら──「幻覚パスがX%減少」──ここではそれを見つけられません。あなた自身以外の誰も、あなたのリポジトリについてのその数字を正直に測定できないからです。

あなたが期待できるのは、もっと狭く、もっと役に立つものです。エージェントは、推測したパスで編集を始めることをやめます。その最初のステップが本物のマップに根拠を持つようになり、幻覚編集の減少はそこから生まれます。引用の後のすべて──diffを読むこと、パッチを判断すること──は、これまでずっとそうであったように、依然としてあなたの仕事です。

このテストはほとんど何も費やしません。すでに知っているリポジトリをインデックスし、確認できる質問を尋ねてください。以前に痛い目にあったパスから始めてください。引用が間違っていれば、すぐにそれが分かります。正しければ、あなたのエージェントの次の編集には、より良い着地場所ができます。

`// it doesn't know the file. it knows how to find it.`