Почему ваш ИИ-агент для кода галлюцинирует пути к файлам

Признак — не неверное тело функции. Это уверенная правка файла, который не существует, или файла, который существует, но не реализует нужное поведение.

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

Документация описывает кратчайший путь: начать бесплатно, проиндексировать репозиторий, который вы уже знаете, подключить клиента, затем задать один вопрос, который можно проверить.

Цикл, который меняет первую правку

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

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.