AI 코딩 에이전트가 환각 (Hallucination)을 일으키는 이유와 해결 방법

제가 함께 협업하는 대부분의 엔지니어들은 AI 코딩 에이전트가 환각 (Hallucination)을 일으킬 때 이를 즉시 알아차릴 수 있습니다. AI가 존재하지 않는 API를 만들어내거나, 더 이상 사용되지 않는 (deprecated) 라이브러리를 호출하거나, 혹은 건드리지 말라고 명시적으로 말한 함수를 다시 작성해 버리기도 합니다. 그들은 이를 인지하고, 짜증을 느끼며, 그냥 넘어가 버립니다. 제가 관찰한 바에 따르면, 이에 대해 무언가 조치를 취하려는 본능을 기른 엔지니어는 점점 줄어들고 있습니다. 단순히 출력값 (output)을 수정하는 것이 아니라, 입력값 (input)을 수정하는 것 말입니다. 제가 같은 방식으로 두 번 환각을 일으킨다면, 제 환경의 무언가가 잘못된 것이며 그것을 찾아내야 합니다. 저는 대화의 구조 (anatomy)나 컨텍스트 제한 (context limits)이 왜 중요한지에 대해서는 다시 다루지 않겠습니다. Dex Horthy는 복잡한 코드베이스 (codebases)에서 어려운 문제를 해결하는 방법에 관한 그의 강연에서 "덤 존 (dumb zone)" 개념을 잘 설명했습니다. 그 핵심은 컨텍스트 윈도우 (context window)가 채워짐에 따라, 대략 40% 지점을 넘어서면 LLM의 성능이 저하된다는 것입니다. 이러한 개념들은 여전히 유효합니다. 대신 제가 공유하고 싶은 것은, 제가 귀 기울여 주는 누구에게나 가르치려 노력해 온 피드백 사이클 (feedback cycle)과 이를 적용하며 배운 구체적인 사항들입니다. 우리 대부분은 AI의 환각에 반응 (react)만 합니다. 조사 (investigate)하는 사람은 거의 없습니다. 에이전트가 궤도를 벗어날 때 저는 다양한 반응을 보았습니다. 어떤 이들은 즐거워하고, 어떤 이들은 짜증을 냅니다. 극단적인 경우, 제가 아는 한 엔지니어는 대화가 잘못된 방향으로 흐르는 순간 바로 ctrl+c를 눌러 대화를 중단하는데, 이는 타당한 행동입니다. 에이전트가 잘못된 방향으로 가고 있다면, 멈추는 것이 토큰 (tokens)과 시간을 아끼는 길이기 때문입니다. 하지만 제가 덜 자주 보는 반응은 다음 실행 시 에이전트를 실제로 개선할 수 있는 반응입니다. 즉, 왜 그런 일이 발생했는지 파악하기 위해 잠시 멈추고, 다시는 그런 일이 발생하지 않도록 변화를 주는 것입니다. 이는 단순히 개인의 워크플로우 (workflow)를 넘어선 문제입니다. 환각 (Hallucinations)은 회의적인 엔지니어들이 계속해서 회의적인 태도를 유지하게 만드는 가장 큰 이유 중 하나입니다. 팀원이 AI가 존재하지 않는 함수를 자신 있게 만들어내는 것을 볼 때마다, "이 도구들은 아직 준비되지 않았다"라는 서사가 강화됩니다.

환각 (Hallucination)을 줄일 수 있는 실제적인 조절 장치(knobs and levers)가 있다는 점을 누군가에게 이해시킬 수 있다면(완전히 제거하는 것이 아니라 줄이는 것입니다), 당신은 이 접근 방식 전체에 대한 상대방의 신뢰를 강화하고 있는 것입니다. 분명히 말씀드리자면, 환각은 결코 완전히 사라지지 않을 것입니다. 환각은 이러한 모델들이 작동하는 방식, 즉 모델이 계산하는 방식에 뿌리를 둔 근본적인 속성이라는 강력한 이론적 근거가 있습니다. 목표는 환각을 제로(0)로 만드는 것이 아닙니다. 환각을 줄이고, 환각이 발생했을 때 더 빠르게 회복하는 것입니다.

저의 팁은 간단합니다. 실제로 어떤 일이 일어났는지 되짚어보는 것입니다. 저를 짜증 나게 하는 환각을 마주할 때, 저는 잠시 멈추고 짧은 체크리스트를 실행하도록 스스로를 훈련해 왔습니다. 정교한 방법은 아니지만, 이를 일관되게 수행하는 습관이 효과를 발휘하게 합니다.

AI 코딩 에이전트가 실제로 무엇을 환각했는가? 이는 당연하게 들리지만, 대부분의 사람들이 진단 과정을 건너뛴다는 것을 알게 되었습니다. 그들은 잘못된 출력을 보면 즉시 다시 프롬프트를 입력하거나 대화를 재시작합니다. 대신, 저는 대화 기록을 살펴보고 추론 과정을 추적하려고 노력합니다. 에이전트가 무엇을 하려고 했는가? 내가 에이전트에게 무엇을 원했는가? 그 두 가지가 어디에서 갈라졌는가?

때로는 제 지시사항을 진심으로 오해한 경우도 있습니다. 때로는 제가 범위(scope) 안에 있다는 사실을 잊고 있었던 파일에서 에이전트가 컨텍스트 (Context)를 가져오기도 합니다. 때로는 단순히 모델이 라이브러리 API에 대해 자신 있게 틀린 답을 내놓기도 하는데, 이는 무엇을 수정해야 하는지에 대해 저에게 다른 시사점을 줍니다. 마지막 사례는 이해할 가치가 있습니다. OpenAI의 연구진은 LLM이 불확실성을 인정하기보다 추측하는 것에 보상을 주는 방식으로 학습된다는 논문을 발표했습니다. 이는 마치 시험 문제에서 빈칸을 남겨두기보다 모든 문제에 답을 채워 넣는 학생과 같습니다. 이를 아는 것은 제가 조사하는 방식을 바꿉니다. 저는 버그를 찾는 것이 아닙니다. 추측을 올바른 방향으로 이끌 수 있었던 누락된 컨텍스트 (Context)를 찾고 있는 것입니다.

그 컨텍스트 (Context)는 어디에서 왔는가? 이것이 핵심입니다. 수정할 가치가 있는 환각을 식별했다면, 질문은 다음과 같이 바뀝니다. 에이전트가 그 잘못된 결정을 내리기 위해 어떤 정보를 사용했는가?

먼저, 에이전트가 소비하는 컨텍스트 (Context)의 출처를 숙지해야 합니다. Claude Code의 경우, CLAUDE.md 파일, ~/.claude/projects/ 에 저장된 프로젝트 수준의 메모리 (Memory), 현재 세션에서 읽은 모든 파일, 그리고 대화 기록 (Conversation history) 그 자체입니다. Cursor의 경우, 규칙 파일 (Rules files), 저장소 곳곳에 흩어져 있는 AGENTS.md 파일 계층 구조, 인덱싱된 문서 (Indexed docs), 그리고 열려 있거나 참조된 모든 파일들입니다. 각 도구는 저마다의 구조 (Anatomy)를 가지고 있으므로, 에이전트가 정보를 어디에서 가져오는지 파악하는 데에만 오후 시간을 할애할 가치가 있습니다. 일단 그 구조를 알게 되면, 환각 (Hallucination)으로부터 역추적할 수 있습니다. 에이전트가 라이브러리 X를 사용해야 한다고 생각했나요? 규칙 파일에 오래된 참조 (Stale reference)가 있는지 확인하십시오. 당신이 더 이상 사용하지 않는 스타일로 계속 테스트를 작성하려고 하나요? 어딘가에 업데이트를 잊어버린 오래된 컨벤션 (Convention)이 문서화되어 있을지도 모릅니다. API 엔드포인트를 지어냈나요? 스키마 문서 (Schema docs)가 최신 상태가 아니거나, 혹은 스키마 문서 자체가 없어서 에이전트가 추측하고 있는 것일 수 있습니다.

스스로 해결할 수 없을 때는 에이전트에게 직접 따져 물으십시오. 다음과 같이 말입니다: "여기서 환각을 일으킨 것 같습니다. 저는 $X를 원했지만, 당신은 $Y를 했습니다. 왜 이런 일이 발생했나요? 이 결정을 내리는 데 어떤 컨텍스트를 사용했나요? 그리고 앞으로 이런 일을 방지하기 위해 제가 규칙 파일을 어떻게 수정해야 할까요?" 직접적이고, 구체적이며, 명확하게 말하십시오. 에이전트는 놀라울 정도로 자기 진단 (Self-diagnosing)을 잘할 때가 많습니다. 자신이 너무 넓게 해석한 규칙을 지목하거나, 오해의 소지가 있는 정보가 포함된 파일을 읽었다고 말할 것입니다. 에이전트가 제안한 변경 사항을 시도해 보십시오. 그것들은 종종 효과가 있습니다. 항상 그렇지는 않지만, 물어보는 데 30초를 쓰는 것이 가치 있을 만큼 자주 효과를 발휘합니다.

이 "환각"이 수정할 만큼 충분히 큰 문제인가요? 문제를 해결하는 데 더 많은 시간을 쓰기 전에, 저는 직관적으로 판단합니다. 제가 그 방식에 동의하지 않는 것뿐인가요, 아니면 실제로 틀린 것인가요? 에이전트가 결국에는 올바른 결과에 도달할 수 있을까요? 사이드바: 친구와 이야기하던 중, 그는 여기서 "환각"이라는 용어가 항상 적절한 것은 아니라고 지적했습니다. 사실 제가 말하는 것은 "에이전트와 의견이 일치하지 않는 모든 것"을 의미합니다.

환각 (Hallucination)은 별개의 문제이지만, 이 조언은 더 광범위한 문제 집합에도 적용됩니다. 저는 환각을 대리 용어 (proxy term)로 사용하고 있습니다. 이는 AI로부터 배우기보다는 관리자 (manager) 역할을 수행하며 배우기가 더 쉬운 것 중 하나입니다. 관리자로서 당신은 모든 사람이 일을 다르게 한다는 것을 깨닫게 됩니다. 때때로 엔지니어가 당신이 선택하지 않았을 경로를 택할 수도 있지만, 그 결과가 괜찮을 때도 있습니다. 심지어 당신이 생각했던 것보다 더 나은 결과가 나오기도 합니다. 저는 AI 에이전트 (AI agents)에도 동일한 사고방식을 적용하기 시작했습니다. 만약 접근 방식이 단지 제가 예상했던 것과 다를 뿐이라면, 잠시 그대로 실행하도록 둡니다. 경로가 원래 의도했던 것과 다르더라도, 증가된 자율성 (autonomy)이 추가적인 시간을 들일 가치가 있을 수 있기 때문입니다. 하지만 만약 API를 발명하거나, 함수 시그니처 (function signatures)를 조작하거나, 존재하지 않는 라이브러리를 가져오는 등 사실 관계를 환각하고 있다면, 그것은 다른 범주입니다. 그때가 바로 제가 멈춰서 조사해야 하는 시점입니다.

당신의 컨텍스트 (context)가 너무 비대해진 것은 아닌가요? 작을수록 좋습니다. 이것은 직관에 어긋나는 일이며, 저도 고생하며 배워야 했습니다. 에이전트에게 더 많은 지침을 주면 더 똑똑해질 것이라고 생각할 것입니다. 데이터베이스 스키마 (database schemas), API 컨벤션 (API conventions), 테스트 선호도, 배포 파이프라인 (deployment pipeline)에 대한 더 많은 컨텍스트... 분명 더 많은 정보가 더 나은 결정으로 이어질 것이라고 생각하지 않습니까? 하지만 실제로는 상황이 반전되는 지점이 있습니다. 저는 무언가 잘못될 때마다 CLAUDE.md 파일에 내용을 계속 추가하던 시기를 겪었습니다. 데이터베이스 스키마, 모델 설계, 상호작용 패턴, 명명 규칙 (naming conventions) 등 말이죠. 파일은 계속 커졌고 (두 달째가 되었을 때는 문서라기보다 선언문 (manifesto)에 가까워졌습니다), 어느 시점부터 에이전트의 성능이 나빠지기 시작했습니다. 에이전트는 서로 충돌하는 지침을 가져오거나, 어떤 컨벤션이 어디에 적용되는지 혼란스러워했고, 때로는 특정 섹션을 완전히 무시하기도 했습니다. 매번 이 컨텍스트가 필요한가요? 아니면 가끔만 필요한가요? 이 컨텍스트를 추출하여 스킬 (Skill)이나 서브 에이전트 (Subagent)로 패키징한 다음, 필요할 때 트리거할 수 있습니까? 이것이 바로 "컨텍스트 격리 (context isolation)"가 필요한 이유입니다.

모든 것을 메인 규칙 파일에 쑤셔 넣는 대신, 니치(niche)하거나 복잡한 유스케이스(use case)를 별도의 메커니즘으로 추출하는 것입니다. 핵심적인 통찰은 특히 서브에이전트(subagents)가 더 높은 수준의 컨텍스트 격리 (context isolation)를 가진다는 점인데, 이는 지침(instructions)이 부모 스레드의 컨텍스트로 로드되지 않기 때문입니다. 필요할 때만 명시적으로 이들을 트리거하며, 그 외의 시간에는 에이전트의 작업 메모리 (working memory) 내에서 주의력(attention)을 두고 경쟁하지 않습니다. 저는 결국 메인 CLAUDE.md 파일을 약 500줄에서 약 280줄 정도로 줄였고(더 짧아져야 마땅합니다), 전문적인 내용들은 관련이 있을 때 호출되는 스킬(skills)로 옮겼습니다. 개선 효과는 한두 세션 내에 눈에 띄게 나타났습니다.

자동 메모리 (automatic memory)가 오히려 방해가 되고 있나요? 현재 대부분의 코딩 및 채팅 도구들은 사용자를 위해 메모리 스레드를 관리해 줍니다. Claude Code는 ~/.claude/projects/$yourProject/memory/ 에 메모리를 보관합니다. Cursor는 자체 시스템을 가지고 있습니다. ChatGPT는 메모리 패널을 보유하고 있습니다. 이 아이디어는 좋습니다. 에이전트가 사용자와의 상호작용으로부터 학습하고 시간이 지남에 따라 적응하기 때문입니다. 문제는 에이전트가 항상 올바른 것을 학습하지는 않는다는 점입니다. Andrej Karpathy는 얼마 전 X에서 이 문제를 지적했습니다. 모델이 현재 수행 중인 작업과 완전히 무관한 2개월 전의 사소한 세부 사항에 집착할 수 있다는 것입니다. 저도 제 작업 중에 이런 현상을 목격했습니다. 에이전트가 제가 특정 엣지 케이스 (edge case)를 위해 한 번 사용했던 특정 테스트 패턴에 매달려, 더 이상 적용할 필요가 없어진 지 한참이 지난 후에도 관련 없는 프로젝트에서 계속해서 이를 호출하는 일이 있었습니다.

Claude Code에서는 메모리 디렉토리에서 주의를 분산시키는 메모리를 찾아 삭제하거나, Claude에게 직접 정리해 달라고 요청할 수 있습니다. Claude의 채팅 인터페이스에서는 UI를 사용하여 저장된 내용을 검사하고 무엇을 변경할지 알려줘야 합니다. (메모리를 직접 편집할 수 없다는 점은 약간 번거로운 부분입니다.) 더 넓은 관점에서 보자면, 자동 메모리는 컨텍스트의 또 다른 소스이며, 다른 소스들과 마찬가지로 드리프트 (drift, 편향/이탈)가 발생할 수 있습니다. 만약 에이전트가 규칙 파일이나 현재 대화에서 추적할 수 없는 이상한 행동을 하기 시작한다면, 메모리를 확인해 보십시오.

에이전트가 당신이 잊어버리길 바라는 무언가를 계속 붙잡고 있을 수도 있습니다. AI와 함께 지속적으로 학습하되, 반드시 트리거(Trigger)를 작동시켜야 합니다. 저의 바이브 코딩 (Vibe Coding) 레퍼토리(Repertoire)에 이 트리거를 추가한 것은 에이전트의 정확도를 반복적으로 개선하는 데 도움이 되었습니다. AI 작업은 종종 다소 무작위적으로 느껴지기도 하지만, 저는 문제 목록을 계속 작성해 둡니다. 어떤 문제가 반복된다면, 그것은 제가 성찰하고 이를 수정해야 한다는 신호입니다. 저는 잠시 멈추고 에이전트에게 향후 실행 시 해당 문제를 방지할 수 있도록 자신의 컨텍스트 (Context)를 수정할 것을 제안하도록 요청합니다. 그런 다음, 그 수정 사항이 유지되는지 확인하기 위해 통제된 작업 (Controlled task)에서 테스트합니다. 복잡한 습관은 아니지만, 매우 가치 있는 습관입니다. 환각 (Hallucination)은 시간을 낭비하게 만들며, 팀 단위로 작업할 경우 그 비용은 배가됩니다. 만약 팀원들이 아직 특정 문제에 직면하지 않았다면, 당신이 그들의 시간을 아껴줄 수 있습니다. 그리고 아마 그들은 아직 이러한 정신적 트리거를 개발하지 못했을 수도 있습니다. 당신이 컨텍스트 파일에서 수정한 내용을 공유하는 것은 AI 코딩 도구를 도입하는 팀을 위해 할 수 있는 '힘을 증폭시키는 (Force-multiplying)' 일 중 하나입니다. 제가 대화하는 대부분의 엔지니어들은 에이전트 컨텍스트를 한 번 설정하면 잊어버리는 (Set-and-forget) 것으로 취급합니다. AGENTS.md를 한 번 작성하고, 무언가 정말 잘못되었을 때만 약간 수정하는 식입니다. 하지만 컨텍스트는 살아있는 시스템입니다. 컨텍스트는 표류하고, 비대해지며, 오래된 가설들을 축적합니다. 이러한 도구로부터 가장 많은 이득을 얻는 엔지니어들은 컨텍스트를 코드처럼 취급하는 사람들입니다. 즉, 정기적인 검토, 리팩토링 (Refactoring), 그리고 테스트가 필요한 대상으로 보는 것입니다. AGENTS.md 파일과 기타 컨텍스트를 이렇게 미세 조정하는 것이, 제가 '매니저로서 AI 도입을 측정하기'라는 글에서 '도입의 구체적인 지표 (Concrete metrics of adoption)'를 살펴보라고 제안했을 때 언급했던 내용입니다. 만약 당신만의 에이전트 컨텍스트 관리 시스템을 개발했거나, 환각을 디버깅하는 방식에서 패턴을 발견했다면, 저에게 알려주세요. LinkedIn으로 DM을 보내주시기 바랍니다. 원래 ashu.co 에서 게시되었습니다.