환각된 API가 AI 생성 코드에서 가장 흔한 버그 유형인 이유

AI 코딩 어시스턴트 (AI coding assistant)를 도입하는 모든 팀은 첫 달에 동일한 놀라운 경험을 하게 됩니다. AI가 생성한 코드에 포함된 버그 중 상당 부분이 단순히 존재하지 않는 API, 함수, 패키지 및 파라미터 (parameters)에서 발생한다는 사실입니다. 코드는 합리적으로 보입니다. 동일한 계열의 실제 코드와 패턴이 일치합니다. 다만 해당 언어, 라이브러리 (library), 또는 프레임워크 (framework)에 실제로 존재하지 않는 것들을 참조할 뿐입니다.

이것이 바로 환각된 API (hallucinated API) 문제입니다. 이는 찾아내는 법을 익혔을 때 가장 높은 효율을 낼 수 있는 버그 유형입니다. 왜냐하면 검증이 빠르고, AI 출력물의 상당 부분이 이 문제를 나타내기 때문입니다.

Photo by Nemuel Sereti on Pexels

환각된 API의 모습

전형적인 예시는 클래스 (class)에 존재할 법한 이름을 가진 메서드 (method)를 사용하는 Python 함수 호출입니다. 어시스턴트는 실제 메서드가 안전한 래퍼 (wrapper)가 없는 response.json()임에도 불구하고 response.json_safe()를 생성합니다. 또는 실제 메서드가 명시적인 how 파라미터를 사용하는 dataframe.merge()임에도 불구하고 dataframe.merge_smart()를 생성하기도 합니다.

다른 흔한 형태들은 다음과 같습니다:

• PyPI에 존재하지 않는 패키지 (packages) 임포트 (Imports). 유사한 이름을 가진 패키지가 많은 Python에서 흔히 발생하며 (예: "pydantic-extras", "requests-helpers"), 어시스턴트는 이를 그럴듯하게 들리는 이름으로 합쳐버립니다.
• 올바르게 보이지만 오타이거나 완전히 만들어낸 npm 패키지들. 종종 올바른 스코프 (scope) ("@vue/", "@react/")와 실제 패키지와 일치하지 않는 그럴듯한 접미사 (suffix)를 가지고 있습니다.
• API의 패턴에는 부합하지만 존재하지 않는 함수 파라미터 (Function parameters). requests.get(url, retries=3, backoff=2)는 합리적으로 보이지만, 실제 requests 라이브러리는 retries나 backoff를 허용하지 않습니다.
• 라이브러리의 관례 (conventions)처럼 보이지만 스키마 (schema)에는 없는 설정 키 (Configuration keys).

이것이 매우 흔하게 발생하는 이유는 구조적입니다. 어시스턴트(Assistant)는 학습 과정에서 보았던 패턴과 일치하는 토큰(Tokens)을 생성합니다. 특정 패턴은 존재하지만 유사한 라이브러리 간에 구체적인 함수 이름(Function name)이 달라지는 API는 특히 융합(Fusion) 현상이 일어나기 쉽습니다.

왜 이것이 가장 먼저 확인해야 할 고수익(High-yield) 버그 클래스인가

두 가지 이유가 있습니다:

검증이 빠릅니다. 공식 문서(Official documentation)를 여세요. 함수 이름을 검색하세요. 확인 한 번에 5초면 충분합니다. 20개의 명명된 함수 호출(Function calls)이 포함된 100줄의 생성된 코드를 검증하는 데는 약 2분 정도의 작업이 소요됩니다.

"작동해야 하는데 작동하지 않는" 상황의 가장 가능성 높은 원인입니다. 예외 케이스(Edge cases)나 버전 불일치(Version mismatches)는 찾아내기 위해 더 많은 디버깅 컨텍스트(Debugging context)가 필요합니다. 반면, 환각된 함수(Hallucinated function)는 코드를 처음 실행할 때 깔끔한 임포트 에러(Import error)나 속성 에러(Attribute error)로 나타납니다. 에러 메시지는 정확히 어떤 이름을 확인해야 하는지 알려줍니다.

간단한 규칙: AI가 생성한 코드가 첫 실행에서 실패한다면, 가장 먼저 확인해야 할 것은 명명된 함수, 패키지(Packages), 그리고 파라미터(Parameters)가 실제로 모두 존재하는지 여부입니다. 이를 통해 거의 아무런 노력 없이도 실패 사례의 상당 부분을 잡아낼 수 있습니다.

구체적인 검증 워크플로우 (Verification workflow)

137Foundry가 프로덕션(Production) 사용을 위해 AI 생성 코드를 검토할 때, 첫 번째 단계는 정확히 이 확인 작업입니다. 워크플로우는 다음과 같습니다:

1. 모든 import 문을 찾습니다. 임포트된 각 모듈에 대해 해당 모듈이 실제로 존재하는지 확인합니다. Python의 경우 PyPI가 신뢰할 수 있는 원천(Source of truth)입니다. Node의 경우 npm registry가 신뢰할 수 있는 원천입니다. Go의 경우 모듈 경로가 해결(resolve)되어야 합니다. 그렇지 않은 모든 항목은 플래그(flag)를 표시합니다.

2. 즉시 인식할 수 없는 이름을 사용하는 모든 함수 호출(function call) 또는 메서드 호출(method call)을 찾습니다. 해당 라이브러리의 문서(documentation)를 열고 그 이름을 검색합니다. 만약 나타나지 않는다면, 플래그를 표시합니다.

3. 키워드 인자(keyword arguments)를 받는 함수에 전달되는 모든 파라미터(parameter)를 찾습니다. 각 파라미터 이름이 문서화된 시그니처(signature)에 있는지 확인합니다. 만약 파라미터가 문서화되어 있지 않다면, 그것은 지어낸 것이거나 **kwargs를 통해 다른 곳으로 전달되고 있는 것입니다 (이 또한 검증할 가치가 있습니다).

4. 외부 시스템을 참조하는 모든 설정 키(configuration key), 환경 변수(environment variable) 이름, 그리고 문자열 상수(string constant)를 찾습니다. 각각이 실제 존재하는지 확인합니다. 이를 통해 어시스턴트(assistant)가 실제 라이브러리에는 존재하지 않지만 그럴듯하게 들리는 설정을 지어내는 경우를 잡아낼 수 있습니다.

평균적으로 검토당 5분이 소요됩니다. 코드가 실행되기 전에 의미 있는 비율의 버그를 잡아낼 수 있습니다.

다른 실패 카테고리(엣지 케이스(edge cases), 버전 불일치(version mismatches), 조용히 틀린 로직(silently wrong logic))를 포함한 전체 디버깅 워크플로우는 137Foundry의 AI 생성 코드 디버깅에 관한 더 자세한 가이드를 참조하세요.

왜 "임포트가 잘 되었다"가 "실제로 존재한다"와 같지 않은가

특정한 주의 사항(gotcha): Python과 JavaScript 모두 사용자가 기대하는 메서드(method)가 없는 항목을 임포트할 때 성공합니다. 임포트 문은 성공하지만, 호출(call)에서 실패합니다. 이는 무심코 "실행해 봤는데 임포트는 잘 되더라"라고 말하는 것이 실제로는 의존성(dependencies)이 실재한다는 증거가 되지 못함을 의미합니다.

검증은 한 단계 더 깊게 들어가야 합니다: 모듈을 임포트한 다음, 특정 함수를 호출해 보십시오. 또는 더 확실하게는, 소스 코드(source code)를 살펴보고 해당 함수가 정의되어 있는지 확인하십시오.

Python에서의 실패 예시:

import requests
response = requests.get_safe("https://api.example.com")
# 임포트는 정상적으로 됩니다. 하지만 requests에 get_safe가 없기 때문에 런타임(runtime)에서 실패합니다.

해결책은 호출 부분을 try-except로 감싸는 것이 아닙니다. 해결책은 requests.get을 사용하고 오류를 올바르게 처리하는 것입니다. 어시스턴트는 특정 패턴을 기반으로 get_safe를 만들어냈습니다. 패턴 자체는 괜찮지만, 해당 함수는 존재하지 않습니다.

이것이 팀 차원에서 의미하는 바

몇 가지 관행을 통해 팀은 환각 비용(hallucination tax)을 반복해서 지불하지 않고도 AI 코딩 어시스턴트를 도입할 수 있습니다:

• AI 어시스턴트의 컨텍스트(context)를 실제 사용하는 라이브러리 버전으로 고정하십시오. 많은 어시스턴트가 학습 데이터에서 가장 흔했던 버전을 사용할 것입니다. 만약 당신이 라이브러리 버전 2.x를 사용하고 있는데 어시스턴트 학습 데이터에서 가장 흔한 버전이 1.x라면, 생성된 코드는 다른 버전에 대해서는 맞을지 몰라도 현재 버전에서는 틀려 보일 것입니다.

• 검증(verification)을 리뷰 체크리스트의 일부로 만드십시오. "임포트된 모든 패키지, 호출된 함수, 그리고 지정된 매개변수(parameters)가 설치된 라이브러리 버전에 존재하는지 확인했는가"라는 항목 하나만으로도 대부분의 환각 문제를 프로덕션(production)에 반영되기 전에 잡아낼 수 있습니다.

• 어시스턴트가 어떤 API를 자주 틀리는지 추적하십시오. 어떤 라이브러리는 다른 라이브러리보다 융합(fusion) 현상이 일어나기 더 쉽습니다. 만약 팀에서 그러한 라이브러리 중 하나를 집중적으로 사용한다면, 해당 영역에 대해 특별히 추가적인 리뷰 단계를 추가할 수 있습니다.

실제 클라이언트 프로젝트에서 이러한 팀 관행을 구축하는 것에 대한 실질적인 맥락을 확인하려면, 137Foundry의 작업이 AI 어시스턴트의 출력물과 프로덕션 엔지니어링 규율(production engineering discipline) 사이의 바로 이러한 통합을 중심으로 이루어져 있음을 참고하십시오. 일관되게 작동하는 패턴은 다음과 같습니다: 첫 번째 초안 작성에는 속도를 위해 AI를 사용하고, 코드가 반영되기 전에는 검증을 위해 신중한 인간의 리뷰를 거치는 것입니다.

더 큰 그림

환각된 API (Hallucinated APIs)는 다음 릴리스에서 수정될 무언가라는 의미에서의 AI 어시스턴트의 "버그"가 아닙니다. 이는 언어 모델 (Language Models)이 출력을 생성하는 방식의 구조적 특징입니다. 모델은 유사한 코드의 패턴에 부합하는 토큰 (Tokens)을 생성합니다. 라이브러리 전반에 걸쳐 패턴에 미세한 변형이 있을 때, 모델은 가끔 패턴에는 부합하지만 특정 라이브러리와는 일치하지 않는 출력을 생성합니다.

해결책은 익숙하지 않은 코드에 대해 항상 작동해 왔던 방식과 동일합니다. 코드를 읽고, 주장을 검증하고, 실행하고, 특정 방식으로 실패하는 것을 관찰한 뒤, 구체적인 문제들을 수정하는 것입니다. 어시스턴트는 초안 작성의 속도는 변화시키지만, 검증의 규율을 변화시키지는 않습니다.

환각 현상과 다른 AI 생성 코드 실패 모드 (Failure Modes)를 모두 다루는 전체 디버깅 워크플로우(Debugging Workflow)에 대해서는, 137Foundry의 AI 코드 디버깅에 관한 포스트에서 전체 체크리스트를 살펴볼 수 있습니다. 팀에서 AI 코딩 어시스턴트를 처음으로 통합하고 있다면 북마크할 가치가 있습니다.

곁에 두고 사용할 짧은 체크리스트

AI가 생성한 코드를 처음 실행하기 전에:

• 모든 임포트된 모듈 (Imported Modules)이 실제 존재하며 설치되어 있는가.
• 모든 명명된 함수 호출 (Named Function Call)이 라이브러리의 문서화된 인터페이스 (Documented Surface)에 존재하는가.
• 모든 키워드 인자 (Keyword Argument)가 해당 함수에 대해 문서화되어 있는가.
• 모든 설정 키 (Configuration Key), 환경 변수 이름 (Environment Variable Name), 그리고 외부 문자열 상수 (External String Constant)가 실제 요소와 매핑되는가.
• 각 라이브러리의 버전이 어시스턴트가 가정한 것과 일치하는가 (사용된 API 인터페이스를 살펴보고 특정 버전과 일치하는지 확인하십시오).

다섯 가지 확인 사항. 파일당 2분. AI 생성 코드에서 얻을 수 있는 가장 빠른 디버깅 승리입니다.

언어 모델 (Language Model)의 일반적인 동작에 관한 배경 지식을 얻으려면, OpenAI의 언어 모델 사용에 관한 문서와 Anthropic Claude 문서에서 모델 제공업체의 공식 가이드를 확인할 수 있습니다. 어시스턴트 (Assistant)의 출력물을 디버깅하는 것과 관련하여 가장 깔끔한 관행은 이 포스트에서 설명한 '검증 우선 (verification-first)' 원칙을 지키는 것입니다. 어시스턴트가 구조를 빠르게 생성하도록 신뢰하되, 세부 사항을 확인하는 데에는 본인의 검증을 신뢰하십시오.