AI 도구 서버의 프로덕션 API 계약 버그가 한 개발자의 데모 스크립트를 통해 드러났다. 해당 서버는 Model Context Protocol을 사용해 'gemini-3.1-flash-lite-image' 모델을 래핑하고 있었으며, 당시 10개의 단위 테스트를 모두 통과한 상태였다. 하지만 데모 스크립트가 'minimal' 사고 수준으로 이미지 생성을 시도하자 HTTP 400 오류가 발생했다. 원인은 서버의 검증 로직이 4가지 수준('minimal', 'low', 'medium', 'high')을 허용하도록 설정된 반면, 실제 Gemini API는 'low'와 'high'만 지원했기 때문이다. 기본값 또한 'medium'으로 설정되어 있어, 기본값을 사용하는 모든 요청이 실패하고 있었다.

기존 단위 테스트는 입력값에 관계없이 성공 응답을 모방하는 방식으로 설계되어 이 문제를 포착하지 못했다. 테스트는 단순히 서버가 파라미터를 전달하는 기능만 확인했을 뿐, 실제 원격 API와의 계약 준수 여부를 검증하지 못했다. 또한 기존 사용자들은 대부분 기본값을 재정의하여 사용했기에, 이러한 설정 불일치가 정상 운영 중에는 발견되지 않았다. 결과적으로 코드상의 로컬 허용 목록과 API의 현재 요구사항 사이에 상당한 괴리가 발생한 것이다.

해당 버그를 해결하기 위해 개발자는 지원 수준을 'low'와 'high'로 제한하고 기본값을 'low'로 변경했다. 또한 'medium' 입력을 로컬에서 즉시 거부하도록 회귀 테스트를 추가해 API 요청 전 명확한 오류 메시지를 제공하도록 조치했다. 이후 수정사항을 검증하고 서버를 새로 빌드하여 Docker Hub에 배포했다. 개발자는 단위 테스트가 로컬 로직 확인에는 유용하나, 실제 API 자격 증명을 사용하는 엔드 투 엔드 테스트를 대체할 수는 없다고 강조했다. 특히 실제 워크플로우를 실행하는 단순한 데모 스크립트는 모의 테스트로 놓치기 쉬운 API 계약 불일치를 찾는 데 효과적이다.

AI 도구 서버의 프로덕션 API 계약 버그가 한 개발자의 데모 스크립트를 통해 드러났다. 해당 서버는 Model Context Protocol을 사용해 'gemini-3.1-flash-lite-image' 모델을 래핑하고 있었으며, 당시 10개의 단위 테스트를 모두 통과한 상태였다. 하지만 데모 스크립트가 'minimal' 사고 수준으로 이미지 생성을 시도하자 HTTP 400 오류가 발생했다. 원인은 서버의 검증 로직이 4가지 수준('minimal', 'low', 'medium', 'high')을 허용하도록 설정된 반면, 실제 Gemini API는 'low'와 'high'만 지원했기 때문이다. 기본값 또한 'medium'으로 설정되어 있어, 기본값을 사용하는 모든 요청이 실패하고 있었다.

기존 단위 테스트는 입력값에 관계없이 성공 응답을 모방하는 방식으로 설계되어 이 문제를 포착하지 못했다. 테스트는 단순히 서버가 파라미터를 전달하는 기능만 확인했을 뿐, 실제 원격 API와의 계약 준수 여부를 검증하지 못했다. 또한 기존 사용자들은 대부분 기본값을 재정의하여 사용했기에, 이러한 설정 불일치가 정상 운영 중에는 발견되지 않았다. 결과적으로 코드상의 로컬 허용 목록과 API의 현재 요구사항 사이에 상당한 괴리가 발생한 것이다.

해당 버그를 해결하기 위해 개발자는 지원 수준을 'low'와 'high'로 제한하고 기본값을 'low'로 변경했다. 또한 'medium' 입력을 로컬에서 즉시 거부하도록 회귀 테스트를 추가해 API 요청 전 명확한 오류 메시지를 제공하도록 조치했다. 이후 수정사항을 검증하고 서버를 새로 빌드하여 Docker Hub에 배포했다. 개발자는 단위 테스트가 로컬 로직 확인에는 유용하나, 실제 API 자격 증명을 사용하는 엔드 투 엔드 테스트를 대체할 수는 없다고 강조했다. 특히 실제 워크플로우를 실행하는 단순한 데모 스크립트는 모의 테스트로 놓치기 쉬운 API 계약 불일치를 찾는 데 효과적이다.