# Чому ваш ШІ-агент для коду галюцинує шляхи до файлів

Canonical source: https://maguyva.ai/uk/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

> ШІ-агенти для коду вигадують шляхи до файлів, коли в них немає справжньої карти репозиторію. Ось чому це відбувається і як обґрунтованість веде до меншої кількості галюцинованих правок.

Ознака — не неправильне тіло функції. Це впевнена правка файлу, якого не існує, або файлу, який існує, але не реалізує потрібну поведінку.

Ви попросили виправити закінчення сесії. Агент відкрив `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`). Обґрунтовані відповіді повертаються зі шляхами до файлів і номерами рядків, тож ви можете оцінювати їх за деревом перед вами.

[Документація](/uk/docs) описує найкоротший шлях: почати безкоштовно, проіндексувати репозиторій, який ви вже знаєте, підключити клієнта, потім поставити одне запитання, яке можна перевірити.

## Цикл, що змінює першу правку

Вам не потрібна нова релігія робочого процесу. Вам потрібен один додатковий крок перед першим записом.

1. Поставте запитання, яке ви вже можете оцінити. «Який код обробляє вхід і закінчення сесії?» краще, ніж «полагодь автентифікацію».
2. Вимагайте цитат. Шлях до файлу й номер рядка, а не переказ «модуля автентифікації».
3. Відкрийте процитовані файли. Простежте символ. Підтвердьте залежність, яку ви збираєтеся торкнутися.
4. Лише тоді дозвольте агенту пропатчити.

Якщо крок 2 не повертає нічого корисного, у агента немає права імпровізувати шлях. Він шукає знову, або ви йому вказуєте. Саме цей єдиний бар'єр виробляє менше галюцинованих правок. Модель — та сама модель. Змінилася карта.

Файли інструкцій досі важливі. Збережіть їх. Використовуйте їх для угод, правил рев'ю та того, чого не слід торкатися. Не просіть їх бути індексом. `CLAUDE.md`, що перелічує три важливі каталоги, застаріє через тиждень після поділу пакета. Запитувана карта оновлюється, коли оновлюється репозиторій.

Споріднений збій — майже правильний файл: агент відкриває `auth.ts`, коли поведінка живе в `auth-client.ts`, або патчить згенерований файл замість вихідного, або редагує копію в `packages/legacy`, бо ім'я збіглося. Цитати не роблять ці помилки неможливими. Вони роблять їх видимими до того, як diff приземлиться.

## Чого карта не виправить за вас

Будьте тверезі щодо того, що ви отримуєте. Обґрунтована карта не зробить кожну правку правильною — ваш агент усе одно може написати поганий патч у точно правильному файлі. Якщо ваша кодова база спирається на динамічну диспетчеризацію, рефлексію чи манкіпатчинг, деякі пошуки символів повертатимуться біднішими, ніж вам хотілося б, бо саме це робить рантайм-непрямість з будь-яким статичним індексом. І якщо ви сподіваєтеся на відсоток — «галюциновані шляхи скоротилися на X%» — ви його тут не знайдете, бо ніхто, крім вас самих, не може чесно виміряти цю цифру для вашого репозиторію.

Чого ви можете очікувати — вужче й корисніше: агент перестає починати правки з вгаданого шляху. Цей перший крок стає обґрунтованим справжньою картою, і саме звідси береться менше галюцинованих правок. Усе після цитати — читання diff, оцінка патча — і далі ваша робота, як і завжди.

Цей тест майже нічого вам не коштує: проіндексуйте репозиторій, який ви вже знаєте, і поставте одне запитання, яке можна перевірити. Почніть зі шляху, на якому вас уже обпікало. Якщо цитати неправильні, ви побачите це негайно. Якщо правильні, наступна правка вашого агента отримає краще місце для приземлення.

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