AI 코딩 에이전트가 확신에 찬, 약간 틀린 코드를 배포하는 이유 (그리고 왜 프롬프트를 다시 쓰는 것이 해결책이 아닌지)

당신의 AI 코딩 에이전트는 언뜻 보기에 맞는 것처럼 보이는 무언가를 작성합니다. 머릿속으로는 컴파일이 잘 되는 것 같습니다. 그러다 당신은 에이전트가 user.getProfileById()를 호출했다는 사실을 발견합니다. 당신의 코드베이스 어디에도 존재하지 않는 메서드입니다.

당신은 그것을 지어내라고 요청하지 않았습니다. 에이전트는 다른 부분은 괜찮은 코드 중간에 아주 확신에 차서 그것을 발명해 냈습니다. 그리고 이것은 최악의 종류의 오류입니다. 명백하게 망가진 것이 아니라, 당신이 직접 잡아내야 할 만큼 조용히 틀려 있는 방식이기 때문입니다.

만약 당신이 Claude Code, Cursor, 또는 실제 리포지토리(repo)에서 어떤 에이전트를 실행해 본 적이 있다면, 이 상황을 잘 알고 있을 것입니다. 왜 이런 일이 발생하는지, 그리고 왜 뻔한 해결책이 통하지 않는지 설명하겠습니다.

모두가 가장 먼저 시도하는 해결책 (그리고 그것이 실패하는 이유)

프롬프트(prompt)의 문구를 다시 작성합니다.

"함수를 지어내지 마세요."라는 문구를 추가합니다. 그러면 한 파일 정도는... 잘 작동합니다. 그러다 다시 똑같은 짓을 합니다. 그래서

이전 — 규칙의 더미:
당신은 숙련된 엔지니어입니다. 깨끗한 코드를 작성하세요.
우리의 컨벤션 (Conventions)을 따르세요. 함수를 지어내지 마세요.
존재하는 메서드만 사용하세요. 에러를 처리하세요.
TODO를 남기지 마세요. 테스트를 작성하세요. ...

이후 — 순서가 정해진 절차:

1. 먼저, 호출할 계획인 모든 메서드(Method)나 API를 나열하세요.
   각 항목에 대해, 그것이 정의된 파일과 줄 번호를 인용하세요.

2. 만약 무언가가 어디에 정의되어 있는지 찾을 수 없다면, 중단하고 나에게 알려주세요 — 그것을 사용하는 코드를 작성하지 마세요.

3. 그 목록이 완성된 후에만, 1단계에서 근거를 확인한 메서드만을 사용하여 코드를 작성하세요. 동일한 모델입니다. "환각 (Hallucination)을 일으키지 마세요"와 같은 새로운 규칙은 추가하지 않았습니다. 하지만 이제 에이전트는 getProfileById()를 지어낼 수 없습니다. 구조 자체가 호출을 작성하기 전에 실제 메서드를 찾도록 강제하기 때문입니다. 그리고 만약 메서드가 실제로 존재하지 않는다면, 2단계는 에이전트가 추측하는 대신 그렇게 말하도록 강제합니다.

문구 수정이 실패했을 때 이 방법이 통하는 이유

여기가 중요한 부분입니다.

문구를 수정했을 때, 당신은 단 하나의 사례 — 즉, 이 파일에 있는 이 지어낸 메서드 — 를 패치(Patch)한 것이었습니다. 다음 사례는 약간 다른 형태로 빠져나갑니다.

구조를 변경하면, 당신은 클래스 전체를 폐쇄하는 것입니다. 모든 파일에 있는 모든 지어낸 메서드에 대해 말이죠. 왜냐하면 모델이 먼저 근거를 확인하지 않고서는 "호출 작성" 단계에 도달할 수 없기 때문입니다. 당신은 증상을 고친 것이 아니라, 원인을 제거한 것입니다.

이것이 프롬프트 수정의 진정한 테스트입니다: 똑같은 실수가 다른 단어를 입고 다시 돌아오는가? 만약 그렇다면, 당신은 문구를 패치한 것입니다. 만약 그렇지 않다면, 당신은 구조를 고친 것입니다.

(한 가지 덧붙이자면, 원리는 같습니다: 이것이 프롬프트를 경직된 JSON 스키마 (JSON Schema)에 억지로 밀어 넣을 때 종종 품질이 저하되는 이유이기도 합니다. 모델에게 필드를 채우게 만들면, 모델은 추론(Reasoning)을 멈추고 양식 채우기(Form-filling)를 시작합니다. 산문(Prose)과 순서가 정해진 절차로 추론하게 하세요. 엄격한 JSON은 사고가 끝난 후, 최종 전달 단계를 위해 남겨두세요.)

당신의 다음 프롬프트를 위한 체크리스트

금지하기보다는 구조화하세요. 모든 "X를 하지 마세요"는 모델이 무시할 수 있는 규칙이 됩니다. 대신 모델이 반드시 수행해야 하는 단계로 바꾸세요.

검증을 희망 사항이 아닌 하나의 단계로 만드세요. "실제 메서드를 사용하세요"보다는 "이것이 정의된 부분을 인용하세요"가 훨씬 효과적입니다.

근거 제시(Grounding)를 앞단에 배치하세요. 쓰기 전에 읽게 하세요. 모델이 생성하기 전에 실제 사실을 먼저 수집하도록 만드세요.

근거를 찾을 수 없을 때는 멈추고 질문하게 해야 합니다. 질문을 던지는 것이 확신에 찬 오답을 내놓는 것보다 비용이 훨씬 적게 듭니다.

이 네 가지만 지켜도 추가적인 규칙을 하나도 더 만들지 않고도 "확신에 찬 오답" 문제의 대부분이 사라집니다.

이 내용을 재사용 가능한 형태로 원하신다면, 체크리스트와 함께 소형 자가 업데이트 스킬(사용자가 직접 규칙을 추가함에 따라 이 규칙들을 최신 상태로 유지해 줍니다)을 무료 다운로드로 패키징해 두었습니다 — [link]. 가져가세요. 그 자체로도 정말 유용합니다.

만약 계속해서 이런 문제를 일으키는 프롬프트가 있고, 이를 그냥 넘겨주고 싶다면 — 불안정한 프롬프트를 견고한 구조로 재구축하는 것이 제가 하는 일입니다. 도와드릴 준비가 되어 있습니다.