Claude Code 할루시네이션, 긴 프롬프트보다 검증 루프가 먼저다

프롬프트에 목적과 형식, 예시까지 빼곡히 넣으면 AI의 할루시네이션을 막을 수 있을까. 한 질문이 의학적 의미로 해석된 사례는 더 근본적인 답을 요구한다. Claude Code의 정확도를 가르는 기준은 프롬프트의 길이가 아니다. 맥락과 검증 수단을 얼마나 분명히 연결했느냐가 중요하다.

엉뚱한 답이 모두 할루시네이션은 아니다

‘할루시네이션 예방법’을 물었는데 스트레스 관리나 치료법이 나온 상황부터 구분해야 한다. 존재하지 않는 사실을 꾸몄다기보다 동음이의어의 의미 영역을 잘못 선택한 경우다. 질문에 AI나 LLM이라는 한정어가 없으면 의학적 의미로 해석될 수 있다.

NIST는 생성형 AI가 자신 있게 틀린 내용을 만드는 위험을 ‘confabulation’으로 분류한다. 반면 질문의 분야를 오인해 관련 없는 사실을 가져온 문제는 검색 의도와 맥락 설정의 실패에 가깝다. 두 오류를 한데 묶으면 처방도 흐려진다. (nvlpubs.nist.gov)

약물에 관한 농담을 위험한 요청으로 보고 선을 그은 반응도 정확성과는 별개다. 안전 정책이 작동했더라도 앞선 답의 분야 선택이 옳았다는 증거는 아니다. 안전한 답과 관련 있는 답, 사실인 답은 따로 점검해야 한다.

열 가지 프롬프트 항목은 출발점일 뿐이다

목적·맥락·제약·예시·형식·톤·길이·대상·검증 기준·수정 기준은 유용한 작성표다. 빠진 요구를 찾고 결과물의 모양을 안정시키는 데 도움이 된다. Anthropic도 프롬프트를 다듬기 전에 성공 기준과 평가 방법부터 정하라고 안내한다. (docs.anthropic.com)

하지만 체크리스트가 사실을 새로 공급해 주지는 않는다. ‘최신 라이브러리 사용법을 정확히 써라’고 요구해도 문서나 저장소를 읽지 않았다면 빈칸은 남는다. 형식을 세밀하게 지정할수록 근거 없는 답이 더 그럴듯하게 정돈될 수도 있다.

첫 문장에는 분야와 작업을 함께 잠그는 편이 낫다. ‘AI 언어모델의 사실 오류를 줄이는 방법을 Anthropic 공식 문서에서 찾아라’처럼 대상과 의미, 출처를 한 번에 지정한다. 의미가 여러 개인 용어라면 답하기 전에 해석을 한 문장으로 확인하라고 요구할 수 있다.

써본 사람들 사이에서는 긴 지침보다 현재 작업에 필요한 자료만 넣었을 때 결과가 안정됐다는 반응이 있다. 오래된 문서와 새 규칙을 함께 주면 모델이 어느 쪽을 따라야 할지 흔들린다는 불만도 나온다. 맥락의 양보다는 최신성과 충돌 여부가 중요하다.

Claude Code에서는 맥락을 파일과 경로로 고정한다

코딩 작업에서는 추상적인 역할극보다 읽어야 할 파일을 지정하는 편이 효과적이다. Anthropic의 Claude Code 모범 사례도 특정 파일과 제약 조건, 참고할 구현 패턴을 프롬프트에 적으라고 권한다. 복잡한 변경은 탐색, 계획, 구현으로 나누고 검증을 붙이도록 안내한다. (code.claude.com)

예를 들어 로그인 오류를 고칠 때는 src/auth/와 라우트 파일, 실패한 테스트 로그를 먼저 읽힌다. Plan mode에서 원인 후보와 변경 파일을 제시하게 한 뒤 계획을 검토한다. 승인 후 코드를 수정하고 기존 테스트와 새 회귀 테스트를 실행한다.

입력은 이슈 설명과 관련 파일, 재현 명령이다. 중간 산출물은 원인 분석과 변경 계획이며 최종 산출물은 diff와 테스트 결과다. ‘로그인 버그를 고쳐줘’라는 한 줄보다 다음처럼 완료 조건을 적으면 작업의 끝을 관찰할 수 있다.

목표: 로그아웃 사용자의 세션 오류를 재현하고 수정한다.
근거: src/auth와 기존 테스트만 먼저 읽는다.
제약: 공개 API와 DB 스키마는 바꾸지 않는다.
검증: 회귀 테스트를 추가하고 전체 테스트 결과를 제시한다.
실패 시: 원인을 추측하지 말고 부족한 로그를 요청한다.

반복되는 프로젝트 규칙은 저장소의 CLAUDE.md에 둔다. 빌드 명령과 디렉터리 역할, 코딩 규칙처럼 매 세션 필요한 사실이 적합하다. Anthropic 문서는 구체적이고 짧은 구성을 권하며 파일이 길어지면 준수율이 떨어질 수 있다고 설명한다. (code.claude.com)

CLAUDE.md도 진실의 원천은 아니다. 과거 제약을 계속 쌓거나 서로 모순된 규칙을 남기면 오래된 맥락이 오류를 재생산한다. 절차가 길다면 Skill로 분리한다. 특정 경로에만 필요한 지침은 .claude/rules/로 좁히는 편이 낫다.

답변이 아니라 증거를 출력하게 한다

Anthropic이 제시하는 기본적인 환각 완화법은 세 가지다. 모르면 모른다고 답할 권한을 주고 제공된 문서에서 관련 문장을 먼저 찾게 하며 각 주장에 근거를 연결한다. 뒷받침할 자료가 없으면 해당 주장을 철회하도록 만들 수도 있다. (docs.anthropic.com)

Claude Code에서는 같은 원칙을 실행 결과로 바꿀 수 있다. ‘수정 완료’라는 문장 대신 실행한 명령과 테스트 출력, 브라우저 화면, 변경된 파일 목록을 요구한다. Claude Code 팀의 최신 활용 지침도 한 가지만 도입한다면 검증 수단부터 제공하라고 강조한다. (support.claude.com)

여기서 검증 기준은 ‘스스로 다시 생각하라’가 아니다. npm test, 타입 검사, 린터, API 요청, 스크린숏 비교처럼 실패 여부가 밖으로 드러나는 장치여야 한다. 중요한 작업은 별도 리뷰 에이전트나 Stop hook으로 완료 조건을 다시 확인할 수 있다.

써본 사람들 사이에서는 ‘모르면 질문하라’는 문구가 억지 추측을 줄였다는 평가가 많다. 반대로 모든 단계에서 의심과 재검토를 요구하면 속도가 느려지고 사소한 작업도 지나치게 커진다는 반응도 있다. 검증 강도는 실수의 비용에 맞춰 달라져야 한다.

프롬프트보다 완료 조건을 먼저 설계한다

개인 개발자와 소규모 팀에는 거대한 프롬프트 체계가 필요하지 않다. 작업마다 ‘무엇을 읽을지, 무엇을 바꾸지 않을지, 무엇이 통과하면 끝인지’ 세 줄을 정하면 된다. 자주 반복되는 세 줄만 CLAUDE.md나 Skill로 옮긴다.

검색형 작업에는 공식 출처의 범위와 기준 날짜를 적는다. 코드 작업에는 재현 명령과 테스트를 붙인다. 문서 작성에는 허용된 자료와 주장별 근거를 남긴다. 근거가 없을 때 멈추는 조건까지 있어야 빈칸을 그럴듯한 문장으로 채우지 않는다.

프롬프트의 열 가지 요소는 요구사항을 잘 전달하는 문법이다. 할루시네이션을 줄이는 장치는 그 문법 뒤에 놓인 파일과 출처, 테스트, 실패 신호다. Claude Code를 믿을 만한 작업자로 만드는 것은 더 설득력 있는 지시문이 아니다. 틀렸을 때 스스로 멈출 수밖에 없는 실행 구조다.