Dlaczego twój agent AI do kodowania halucynuje ścieżki plików

Sygnałem nie jest błędne ciało funkcji. To pewna siebie edycja pliku, który nie istnieje, albo pliku, który istnieje, ale nie jest tym, który implementuje dane zachowanie.

Poprosiłeś o naprawę wygasania sesji. Agent otworzył src/auth/session.ts. Ta ścieżka jest wiarygodna. Jest też błędna. Prawdziwy handler żyje w apps/api/src/middleware/expiry.ts, przemianowanym dwa refaktoringi temu. Agent cię nie okłamał. Uzupełnił łańcuch w kształcie ścieżki na podstawie wiedzy wyniesionej z treningu plus tego, co już było w oknie kontekstu.

To powszechny wzorzec porażki na prawdziwym repozytorium. Model potrafi pisać kod. Błędem jest wybór złego miejsca, żeby go napisać.

Dlaczego agenci wymyślają ścieżki

Agent kodujący to model przewidywania następnego tokena wyposażony w narzędzia. Gdy mówisz „napraw wygasanie sesji”, musi wskazać plik, zanim będzie mógł cokolwiek przeczytać lub załatać. Jeśli nie ma jeszcze ugruntowanej mapy, konstruuje ścieżkę z:

1. Konwencji nazewnictwa, które widział w innych repozytoriach. src/auth/session.ts to częsty kształt.
2. Plików już obecnych w rozmowie, które mogą być tymi, które wkleiłeś w zeszłym tygodniu, a nie tymi, które liczą się teraz.
3. Listingów katalogów, które przypadkiem uruchomił, niekompletnych na dużym drzewie.
4. Plików instrukcji. CLAUDE.md i AGENTS.md mówią agentowi, jak się zachowywać. Nie są żywym indeksem symboli, wywołujących ani aktualnych ścieżek.

Żadne z tych źródeł nie jest mapą tego repozytorium, dzisiaj. Model wypełnia lukę tak samo, jak wypełnia każdą lukę: kontynuacją o wysokim prawdopodobieństwie. Ta kontynuacja często wygląda jak prawdziwa ścieżka. Czasem plik istnieje i leży obok właściwego. Czasem istniał na branchu scalonym w zeszłym miesiącu. Czasem nigdy nie istniał.

Grep cię tu nie uratuje, jeśli agent w ogóle nie szuka właściwego ciągu znaków. Agent zgadł ścieżkę, potem przeczytał, co ta ścieżka zwróciła, potem ją edytował. Pierwszym błędnym krokiem była ścieżka, nie łatka.

Czytanie plików to też nie to samo, co znajdowanie właściwych. Claude Code, Cursor, Codex i podobne narzędzia mogą otworzyć wszystko, na co je skierujesz. Pytanie brzmi, czy niezawodnie znajdują właściwe pliki, ważne symbole, zależności, testy i zasięg wpływu, zanim zaczną edytować. Dostęp do plików bez mapy nadal zaczyna się od zgadywania.

Edycja złego pliku to problem wyszukiwania

Traktuj wymyśloną ścieżkę jako chybienie wyszukiwania, nie jako wadę charakteru.

Gdyby agent musiał zwrócić path/file.ext:line, zanim pozwolono by mu edytować, wydarzyłyby się dwie rzeczy. Po pierwsze, mógłbyś otworzyć cytat i odrzucić pracę w dziesięć sekund. Po drugie, agent musiałby odpytać coś, co rzeczywiście zna to drzewo.

To jest praca warstwy kontekstu bazy kodu. Samo wyszukiwanie semantyczne to za mało. Fragment, który „brzmi jak wygasanie sesji”, i tak może wylądować w wycofanym pakiecie. Potrzebujesz też dokładnego tekstu, gdy znasz ciąg znaków, wyszukiwania symboli, gdy znasz nazwę, wyszukiwania strukturalnego, gdy znasz kształt, oraz grafu zależności, gdy potrzebujesz wywołujących i zasięgu wpływu.

Maguyva jest tą warstwą dla agentów kodujących zgodnych z MCP. To nie jest edytor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf i inni klienci MCP zostają tam, gdzie są. Agent odpytuje uszeregowaną mapę, zanim dotknie linijki.

Twierdzenie jest celowo skromne: mniej zhalucynowanych edycji. Maguyva nie odbiera modelowi zdolności do zgadywania. Zmienia domyślny pierwszy krok z „wymyśl wiarygodną ścieżkę” na „poproś o uszeregowane, zacytowane lokalizacje”.

Jak wygląda ugruntowana odpowiedź

Użyteczna odpowiedź na pytanie „gdzie obsługiwane jest wygasanie sesji” to nie akapit. To krótka lista lokalizacji:

• apps/api/src/middleware/expiry.ts:48 - handler
• apps/web/src/lib/auth-client.ts:112 - wywołujący
• apps/api/tests/expiry.test.ts:20 - test, który zawiedzie, jeśli zmiana jest błędna

Możesz otworzyć te linie. Jeśli są błędne, zatrzymujesz się. Jeśli są poprawne, agent może edytować. Chodzi o weryfikację, nie o hasło.

Maguyva udostępnia 11 skierowanych do klienta narzędzi MCP w zakresie wyszukiwania, symboli, analizy zależności, pobierania plików, kontekstu repozytorium i deterministycznych przepływów narzędziowych. Cztery tryby wyszukiwania (semantyczny, strukturalny, grafowy/zależnościowy i tekstowy) łączą się w uszeregowane wyniki; wyszukiwanie symboli to osobne narzędzie MCP (find_symbol). Ugruntowane odpowiedzi wracają ze ścieżkami plików i numerami linii, więc możesz je oceniać na tle drzewa przed tobą.

Dokumentacja opisuje najkrótszą ścieżkę: zacznij za darmo, zindeksuj repozytorium, które już znasz, połącz klienta, potem zadaj jedno pytanie, które możesz sprawdzić.

Pętla, która zmienia pierwszą edycję

Nie potrzebujesz nowej religii przepływu pracy. Potrzebujesz jednego dodatkowego kroku przed pierwszym zapisem.

1. Zadaj pytanie, które już możesz ocenić. „Jaki kod obsługuje logowanie i wygasanie sesji?” jest lepsze niż „napraw uwierzytelnianie”.
2. Wymagaj cytatów. Ścieżki pliku i numeru linii, nie streszczenia „modułu uwierzytelniania”.
3. Otwórz zacytowane pliki. Podążaj za symbolem. Potwierdź zależność, której zamierzasz dotknąć.
4. Dopiero wtedy pozwól agentowi załatać.

Jeśli krok 2 nie zwraca niczego użytecznego, agent nie ma prawa improwizować ścieżki. Szuka ponownie albo ty mu wskazujesz. Właśnie ta jedna bramka wytwarza mniej zhalucynowanych edycji. Model jest tym samym modelem. To, co się zmieniło, to mapa.

Pliki instrukcji nadal mają znaczenie. Zachowaj je. Używaj ich do konwencji, reguł przeglądu i tego, czego nie dotykać. Nie proś ich, żeby były indeksem. CLAUDE.md wymieniający trzy ważne katalogi zdezaktualizuje się tydzień po podziale pakietu. Przeszukiwalna mapa aktualizuje się, gdy aktualizuje się repozytorium.

Pokrewną porażką jest plik prawie trafiony: agent otwiera auth.ts, gdy zachowanie żyje w auth-client.ts, albo łata wygenerowany plik zamiast źródła, albo edytuje kopię w packages/legacy, bo nazwa pasowała. Cytaty nie sprawiają, że te pomyłki stają się niemożliwe. Sprawiają, że stają się widoczne, zanim diff wyląduje.

Czego mapa za ciebie nie naprawi

Bądź trzeźwy co do tego, co dostajesz. Ugruntowana mapa nie sprawi, że każda edycja będzie poprawna — twój agent nadal może napisać złą łatkę dokładnie we właściwym pliku. Jeśli twoja baza kodu opiera się na dynamicznym dispatchu, refleksji albo monkey-patchingu, niektóre wyszukiwania symboli będą wracać skromniejsze, niż byś chciał, bo to właśnie robi z każdym statycznym indeksem pośredniość w czasie działania. A jeśli liczysz na procent — „ścieżki halucynowane zredukowane o X%” — nie znajdziesz go tutaj, bo nikt poza tobą nie może uczciwie zmierzyć tej liczby dla twojego repozytorium.

To, czego możesz oczekiwać, jest węższe i bardziej użyteczne: agent przestaje zaczynać edycje od zgadniętej ścieżki. Ten pierwszy krok staje się ugruntowany w prawdziwej mapie, i stąd bierze się mniej zhalucynowanych edycji. Wszystko po cytacie — czytanie diffa, ocena łatki — nadal jest twoją pracą, tak jak zawsze było.

Ten test kosztuje cię niemal nic: zindeksuj repozytorium, które już znasz, i zadaj jedno pytanie, które możesz sprawdzić. Zacznij od ścieżki, na której już się kiedyś sparzyłeś. Jeśli cytaty są błędne, zobaczysz to od razu. Jeśli są poprawne, kolejna edycja twojego agenta będzie miała lepsze miejsce, żeby wylądować.

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