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를 반드시 반환해야 한다면, 두 가지 일이 일어날 것입니다. 첫째, 여러분은 인용을 열고 10초 안에 작업을 거부할 수 있습니다. 둘째, 에이전트는 실제로 트리를 아는 무언가를 질의해야 할 것입니다.

그것이 코드베이스 컨텍스트 레이어의 일입니다. 시맨틱 검색만으로는 충분하지 않습니다. “세션 만료처럼 들리는” 조각도 여전히 폐기된 패키지에 착륙할 수 있습니다. 문자열을 알 때는 정확한 텍스트도, 이름을 알 때는 심볼 조회도, 형태를 알 때는 구조적 검색도, 호출자와 영향 범위이 필요할 때는 의존성 그래프도 필요합니다.

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-client.ts에 있는데 에이전트가 auth.ts을 열거나, 소스 대신 생성된 파일을 패치하거나, 이름이 일치한다는 이유로 packages/legacy의 사본을 편집합니다. 인용이 그런 실수를 불가능하게 만들지는 않습니다. diff가 착륙하기 전에 그것들을 눈에 보이게 만들 뿐입니다.

지도가 여러분을 위해 고쳐주지 않는 것

무엇을 얻는지에 대해 냉정해지세요. 근거 있는 지도가 모든 편집을 옳게 만들지는 않습니다 — 에이전트는 여전히 정확히 올바른 파일에서 나쁜 패치를 쓸 수 있습니다. 코드베이스가 동적 디스패치, 리플렉션, 몽키패칭에 의존한다면, 일부 심볼 조회는 원하는 것보다 빈약하게 돌아올 것입니다. 런타임 간접성이 어떤 정적 인덱스에게든 그런 짓을 하기 때문입니다. 그리고 백분율을 바라고 있다면 — “환각 경로 X% 감소” — 여기서는 찾지 못할 것입니다. 여러분 자신 말고는 아무도 여러분의 저장소에 대한 그 숫자를 정직하게 측정할 수 없기 때문입니다.

기대할 수 있는 것은 더 좁고 더 유용합니다: 에이전트는 추측된 경로로 편집을 시작하는 것을 멈춥니다. 그 첫 단계가 진짜 지도에 근거를 두게 되고, 더 적은 환각 편집은 거기서 나옵니다. 인용 이후의 모든 것 — diff를 읽는 것, 패치를 판단하는 것 — 은 여전히 항상 그래왔듯 여러분의 일입니다.

이 테스트는 거의 아무것도 들지 않습니다: 이미 아는 저장소를 색인하고 검증할 수 있는 질문을 하세요. 예전에 당했던 경로부터 시작하세요. 인용이 틀렸다면, 즉시 보일 것입니다. 맞다면, 여러분 에이전트의 다음 편집은 착륙할 더 나은 자리를 갖게 됩니다.

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