Claude Code의 두 가지 캐시 버그: API 비용을 10-20배 올리는 원인과 우회법

Who Should Read

Claude Code를 CLI나 자동화 스크립트에서 사용하는 개발자. 특히 --resume으로 대화를 이어가거나 CLAUDE.md에 내용을 많이 넣어두고 쓰는 사람.

Core Mechanics

• 버그 1: 스탠드얼론 바이너리에는 Anthropic의 커스텀 Bun 포크에 네이티브 레이어 문자열 치환 로직이 있는데, 대화 히스토리에 특정 sentinel 문자열이 포함되면 매 API 요청마다 메시지 내용이 바뀐다.
• sentinel 문자열은 CC 소스 코드를 읽었거나, 빌링 관련 헤더를 언급했거나, CLAUDE.md 파일에 관련 내용이 있을 때 대화에 포함될 수 있다.
• 메시지 내용이 매번 달라지면 캐시 prefix(이전 대화를 캐시해서 재사용하는 기능)가 깨져서 매 요청마다 전체 토큰을 다시 과금한다.
• 버그 1 우회법: 스탠드얼론 바이너리 대신 `npx claude` 방식으로 실행하면 이 치환 로직을 거치지 않아서 캐시가 정상 동작한다.
• 버그 2: v2.1.69부터 --resume 옵션을 쓰면 항상 캐시 미스가 발생한다. deferred_tools_delta의 순서가 fresh session과 resumed session 사이에 달라지는 게 원인이다.
• --resume 시 시스템 프롬프트만 캐시되고 전체 대화 히스토리는 매번 처음부터 다시 읽혀서, resume 요청 하나에 10-20배 비용이 발생할 수 있다.

Evidence

• 버그 2는 v2.1.69 이후 --resume 사용 시 항상 재현된다고 보고됨. 시스템 프롬프트를 제외한 전체 대화 히스토리가 캐시 미스 처리됨.
• 두 버그 모두 API 비용을 10-20배까지 증가시킬 수 있다고 명시됨. 대화가 길수록 손해가 커짐.
• 버그 1은 스탠드얼론 바이너리에만 존재하며, npx 실행 방식에서는 동일 증상이 재현되지 않음.

How to Apply

• 지금 당장: Claude Code를 스탠드얼론 바이너리로 실행 중이라면 `npx @anthropic-ai/claude-code` 방식으로 바꿔라. CLAUDE.md에 빌링/소스코드 관련 내용이 있는 경우 특히 중요하다.
• --resume을 자주 쓰는 자동화 스크립트가 있다면 v2.1.69 이전 버전으로 다운그레이드하거나, resume 없이 새 세션으로 시작하는 방식으로 임시 우회한다.
• Claude API 비용이 갑자기 치솟았는데 원인을 모르겠다면, Claude Code 버전과 실행 방식(standalone vs npx), --resume 사용 여부를 먼저 확인한다.

Code Example

# 버그 1 우회: 스탠드얼론 바이너리 대신 npx 사용
# Before (캐시 버그 있음)
claude "your prompt here"

# After (캐시 정상 동작)
npx @anthropic-ai/claude-code "your prompt here"

# 버그 2 확인: 현재 설치된 버전 체크
claude --version
# v2.1.69 이상이면 --resume 사용 시 캐시 미스 발생

# 임시 우회: resume 대신 새 세션 시작
# claude --resume <session-id>  <- 비용 폭탄 가능
claude  # 새 세션으로 시작

Terminology

관련 논문

• Claude Code는 프롬프트 읽기 전에 33k 토큰을 전송한다; OpenCode는 7k

  동일한 모델과 작업 환경에서 Claude Code와 OpenCode의 실제 토큰 사용량을 API 레벨에서 측정한 결과, Claude Code가 시스템 프롬프트 오버헤드만으로 OpenCode 대비 4.7배 더 많은 토큰을 소비한다는 것을 확인했다.

• Mesh LLM: iroh 기반 분산 AI 컴퓨팅

  사무실, 집, 클라우드에 흩어진 GPU들을 하나의 OpenAI 호환 API로 묶어주는 분산 LLM 실행 시스템으로, 비싼 API 비용 없이 큰 모델을 직접 운영할 수 있다.

• Frugon – LLM API 호출 로그를 분석해서 더 싼 모델로 대체 가능한 구간을 찾아주는 로컬 도구

  내 LLM API 비용이 어디서 새는지 로컬에서 분석해주는 오픈소스 CLI 도구로, 비싼 모델 대신 저렴한 모델로 전환 가능한 호출을 골라낸다.

• 로컬에서 SOTA LLM 실행하기 완전 가이드 (하드웨어부터 설정까지)

  2천 달러짜리 RTX 3090 한 장부터 4만 달러짜리 RTX PRO 6000 4장 셋업까지, 로컬에서 최신 LLM을 직접 돌리는 방법을 하드웨어 선택·구성·실행 설정까지 통째로 정리한 실전 가이드다.

• Manticore Search에서 ONNX 경로를 재설계해 임베딩 속도를 14배 높인 방법

  Manticore Search가 기존 SentenceTransformers/Candle 백엔드를 ONNX Runtime으로 교체해 텍스트 임베딩 생성 속도를 평균 14배 향상시켰다. 별도 모델 서비스 없이 DB 내부에서 직접 임베딩을 처리하는 구조에서 INSERT 속도가 곧 임베딩 속도이기 때문에 이 개선은 실질적인 ingest 처리량 향상으로 직결된다.

• Asymmetric Quantization: 97% 스토리지 절감으로 Late Interaction 검색 품질 유지하기

  멀티벡터 검색 모델의 문서 벡터를 1비트 이진값으로 압축하고 쿼리 벡터만 int8로 유지하는 비대칭 양자화 기법으로, 스토리지를 97% 줄이면서 검색 품질 손실을 0.61점(NDCG@10 기준)에 그치게 만든 실제 프로덕션 적용 사례다.