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

관련 논문

• 로컬에서 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 기준)에 그치게 만든 실제 프로덕션 적용 사례다.

• Bash4LLM+ – 의존성 없는 경량 Bash LLM API 래퍼

  Python이나 Node.js 없이 순수 Bash만으로 Groq 등 OpenAI 호환 LLM API를 호출할 수 있는 단일 스크립트 도구로, Termux(Android)를 포함한 모든 Unix 환경에서 동작한다.

• Wayfinder Router: 로컬과 hosted LLM 간 deterministic 쿼리 라우팅 도구

  프롬프트의 복잡도를 모델 호출 없이 오프라인으로 점수화해서 간단한 쿼리는 로컬 모델로, 어려운 쿼리는 유료 모델로 자동 라우팅하는 CLI 도구다. LLM 비용을 줄이면서도 응답 품질을 유지하고 싶은 개발자에게 유용하다.

• Apple Neural Engine: 아키텍처, 프로그래밍, 성능 (리버스 엔지니어링 가이드)

  Apple 기기에 내장된 AI 전용 칩인 ANE(Apple Neural Engine)를 리버스 엔지니어링으로 분석한 302페이지짜리 기술 문서로, Core ML 아래 숨겨진 내부 구조와 직접 접근 경로를 처음으로 공개한다.