Claude Code의 두 가지 캐시 버그: API 비용을 10-20배 올리는 원인과 우회법
PSA: Claude Code has two cache bugs that can silently 10-20x your API costs — here's the root cause and workarounds
TL;DR Highlight
Claude Code 스탠드얼론 바이너리와 --resume 옵션에 숨어있는 캐시 버그 두 개가 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
snippet
# 버그 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
cache prefix이전에 API에 보낸 메시지를 서버가 기억해뒀다가 재사용하는 기능. 같은 내용을 또 보내면 할인된 가격으로 처리된다. 캐시가 깨지면 매번 전체 금액을 냄.
sentinel코드 안에 숨겨놓은 특별한 표시용 문자열. 여기서는 Anthropic이 내부적으로 문자열 치환 위치를 표시하는 데 쓰는 숨겨진 마커.
deferred_tools_delta스트리밍 API 응답에서 도구 호출 결과가 지연되어 전달될 때의 메시지 형식. 순서가 달라지면 같은 대화라도 다른 내용으로 인식됨.
캐시 미스(cache miss)캐시에 저장된 내용을 재사용하려 했는데 못 찾는 상황. 이 경우 처음부터 다시 계산(과금)해야 함.
BunJavaScript 런타임 환경 중 하나. Node.js처럼 JS 코드를 실행하는데, 여기서는 Anthropic이 자체 수정한 포크(변형 버전)를 Claude Code 바이너리에 내장했음.
standalone binary별도 설치 없이 바로 실행 가능한 단일 실행 파일. Claude Code를 직접 다운로드해서 쓸 때의 형태.
npxnpm 패키지를 설치하지 않고 바로 실행하는 명령어. `npx claude`는 매번 최신 패키지를 받아 실행함.