Claude Code 버그로 인한 API 비용 10-20배 폭등: 반드시 알아야 할 사항

Hero

개발자들이 워크플로우를 가속화하기 위해 AI 기반 코딩 도구에 점점 더 의존함에 따라, 이러한 도구를 유지하는 데 드는 근본적인 경제성이 중요한 고려 사항으로 떠오르고 있습니다. 생산성 향상은 체감할 수 있지만, 대규모 언어 모델(LLM)을 개발 환경에 직접 통합하면서 발생하는 숨겨진 비용은 때때로 우리를 당황하게 만듭니다.

최근 Anthropic의 CLI 기반 AI 코딩 어시스턴트인 Claude Code와 관련하여 심각한 문제가 수면 위로 드러났습니다. API 비용을 무려 10배에서 20배까지 조용히 부풀릴 수 있는 두 가지 캐싱 버그에 대한 보고가 잇따르고 있습니다. 자동화된 워크플로우나 심층적인 코드베이스 분석을 실행하는 팀에게 이는 단순한 불편함을 넘어 개발 예산을 순식간에 고갈시키는 치명적인 문제입니다.

이 글에서는 정확히 어떤 일이 발생했는지, 이러한 캐싱 메커니즘이 실패한 이유, 개발 스택에 미치는 기술적 영향, 그리고 예상치 못한 API 청구서 폭탄의 위험을 완화할 수 있는 방법을 자세히 분석해 보겠습니다.

#어떤 일이 발생했는가: 두 가지 캐시 버그

이 문제의 핵심은 Claude Code가 Anthropic의 API 캐싱 계층과 상호 작용하는 방식에서 비롯됩니다. 프롬프트 캐싱은 대규모 코드베이스를 반복적으로 분석해야 하는 도구에 있어 필수적인 기능입니다. 이 기능을 통해 API는 이전에 계산된 컨텍스트를 재사용하여 지연 시간과 토큰 비용을 모두 획기적으로 줄일 수 있습니다.

커뮤니티 보고에 따르면, Claude Code는 이 캐싱 메커니즘과 관련된 두 가지 별개의 버그를 겪고 있었습니다.

사소한 변경 시 캐시 무효화: 첫 번째 버그는 전체 캐시된 컨텍스트가 너무 공격적으로 무효화되는 현상을 일으켰습니다. 변경 사항을 효율적으로 비교(diff)하거나 코드베이스 컨텍스트의 대부분을 유지하는 대신, 사소한 파일 저장이나 가벼운 업데이트만으로도 전체 캐시 미스(cache miss)가 발생했습니다. 이로 인해 CLI는 이후의 모든 프롬프트에 대해 전체 작업 공간 컨텍스트를 다시 업로드하고 처리해야 했습니다.
캐시되지 않은 요청으로의 조용한 폴백: 첫 번째 문제를 더욱 악화시킨 것은, 캐시가 실패하거나 무효화되었을 때 도구가 사용자에게 경고하거나 요청을 제한(throttle)하려고 시도하지 않았다는 점입니다. 대신 일반적인 캐시되지 않은 API 호출로 조용히 전환(fallback)되었습니다. Claude Code는 정확한 답변을 제공하기 위해 일상적으로 방대한 양의 컨텍스트(종종 수십만 개의 토큰)를 전달하므로, 각각의 프롬프트는 갑자기 어떠한 할인도 적용되지 않은 온전한 비용을 발생시켰습니다.

그 결과는 어땠을까요? 질문을 하고, 간단한 리팩토링을 요청하고, 테스트를 실행하는 등 일상적이고 반복적인 코딩 세션을 수행하던 개발자들은 대화가 오고 갈 때마다 자신도 모르는 사이에 엄청난 토큰 수를 소모하게 되었습니다.

#왜 중요한가: 컨텍스트 윈도우의 경제성

이 문제의 심각성을 이해하려면 최신 LLM의 경제성을 살펴보아야 합니다. Claude 3.5 Sonnet과 같은 모델은 최대 20만 토큰에 달하는 방대한 컨텍스트 윈도우를 제공합니다. 이는 코드베이스를 깊이 있게 이해하는 데는 엄청난 이점을 주지만, 그만큼 높은 비용이 따릅니다.

비용이 어떻게 눈덩이처럼 불어날 수 있는지 간단히 요약해 보았습니다.

정상적인(캐시된) 작동: 10만 토큰 규모의 코드베이스를 로드합니다. 초기 로드 비용은 $0.30입니다(입력 토큰 100만 개당 $3 가정). 캐시에 적중하는 후속 쿼리 비용은 그보다 훨씬 적은, 턴당 약 $0.03가 될 수 있습니다. 20번의 턴으로 구성된 세션의 총 비용은 $0.90입니다.
버그가 발생한(캐시되지 않은) 작동: 10만 토큰 코드베이스가 매 턴마다 다시 처리됩니다. 질문을 할 때마다 입력 컨텍스트에만 $0.30의 비용이 청구됩니다. 이제 20번의 턴으로 구성된 세션 비용은 $6.00가 됩니다.

만약 1인 개발자라면 6배에서 20배의 증가는 $5가 아니라 $50의 청구서를 의미할 수 있습니다. 하지만 수십 명의 개발자가 동시에 Claude Code를 실행하는 엔터프라이즈 팀의 경우, 이 버그는 다음 청구 알림이 울리기도 전에 며칠 만에 수천 달러를 조용히 태워버릴 수 있습니다. 청구 금액을 예측할 수 없게 되면 AI 도구에 대한 예산 책정은 사실상 불가능해집니다.

#기술적 영향: 프롬프트 캐싱의 취약성

이 사건은 우리가 AI 도구를 구축하고 소비하는 방식에 있어 보다 광범위한 아키텍처의 취약성을 보여줍니다. LLM API의 프롬프트 캐싱은 아직 초기 단계의 기술입니다. 이는 접두사(prefix) 토큰의 정확한 일치 여부에 의존합니다.

#접두사 캐싱의 작동 원리

Anthropic과 같이 캐싱을 지원하는 API에 요청을 보내면, 시스템은 프롬프트의 시작 부분(접두사)을 해시 처리합니다. 후속 요청이 정확히 동일한 접두사를 공유하는 경우, 시스템은 어텐션 상태(attention states)를 다시 계산하지 않고 메모리에서 미리 계산된 상태를 검색합니다.

#문제가 발생하는 지점

코딩 어시스턴트 시나리오에서 접두사는 일반적으로 시스템 프롬프트와 그 뒤에 오는 코드베이스의 내용으로 구성됩니다.

// Simplified payload structure
{
  "system": "You are a senior developer...",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<file name='app.js'>...</file>" }, // Cached
        { "type": "text", "text": "Fix the bug in line 42." } // Dynamic
      ]
    }
  ]
}

도구가 파일을 재정렬하거나, <file> 블록 중간의 단일 문자를 수정하거나, 접두사 중첩을 최대화하도록 요청을 제대로 구성하지 못하면 캐시가 깨집니다. Claude Code 버그는 빠르게 변화하고 변형이 잦은 환경(활발하게 개발 중인 로컬 파일 시스템)에서 이 섬세한 상태 머신(state machine)을 유지하는 것이 얼마나 극도로 어려운지를 보여줍니다. 상태 머신이 실패할 때, 폴백 메커니즘은 비용 폭탄을 맞지 않는 안전한(fail-safe) 방향으로 작동해야 합니다.

#향후 대책: 완화 방법 및 모범 사례

Anthropic은 의심할 여지 없이 Claude Code의 이러한 특정 캐싱 동작을 해결하기 위한 패치 작업을 진행 중일 것입니다. 하지만 이번 사건은 고도화된 컨텍스트 AI 도구에 의존하는 개발자들에게 경각심을 일깨워 줍니다.

당장의 API 예산을 보호하기 위해 취할 수 있는 실행 가능한 단계는 다음과 같습니다.

엄격한 청구 한도 설정: 가장 중요한 단계입니다. Anthropic 콘솔로 이동하여 월별 지출 한도를 엄격하게 설정하십시오. API 사용량 폭증은 이메일 편지함을 확인하는 것보다 훨씬 빠르게 발생할 수 있으므로 이메일 알림에만 의존해서는 안 됩니다.
로컬 토큰 사용량 모니터링: 맞춤형 도구를 구축하거나 Claude Code를 래핑(wrapping)하는 경우 토큰 사용량에 대한 로깅을 구현하십시오. cache_creation_input_tokens와 cache_read_input_tokens의 비율을 추적하는 것이 좋습니다. 읽기 토큰(read tokens)의 갑작스러운 감소는 조기 경고 신호입니다.
컨텍스트 범위 제한: 절대적으로 필요한 경우가 아니라면 전체 리포지토리를 컨텍스트 윈도우에 전달하려는 유혹을 피하십시오. 현재 작업과 관련된 파일이나 디렉터리만 구체적으로 지정할 수 있는 도구를 활용하십시오.
업데이트 주시: CLI 도구를 최신 상태로 유지하십시오. 커뮤니티에 의해 이러한 유형의 버그가 식별되면 일반적으로 신속하게 수정 사항이 배포됩니다.

#결론

거대한 컨텍스트 윈도우를 로컬 개발 환경에 통합하는 것은 판도를 바꾸는 혁신이지만, 이를 안전하게 지원하기 위해서는 성숙한 인프라가 필요합니다. 이번 Claude Code 캐싱 버그는 AI 도구가 코드를 작성해 줄 수는 있어도, 이를 구동하는 인프라와 비용 청구 관리는 여전히 우리의 몫이라는 사실을 뼈저리게 일깨워 줍니다. 개발자로서 우리는 항상 경계를 늦추지 않고, 사용량을 모니터링하며, 워크플로우에 강력한 안전장치(fail-safes)를 구축하여 생산성 도구가 재정적인 골칫거리로 전락하지 않도록 해야 합니다.