Claude Code 캐시 버그 패치 가이드 · 토큰 낭비 줄이는 방법
개인 경험으로 시작
제 Claude Code 사용량도 정말 이상했어요.
지난 3개월간 같은 프로젝트에서 계속 일했는데, 세션을 재개할 때마다 토큰이 줄줄 새고 있었거든요. 처음엔 “어? 이게 맞나?” 싶었어요. 근데 나중에 알고 보니 버그였더라고요.
Reddit 개발자 커뮤니티에서 누군가가 정확한 원인을 찾아냈어요. 캐시 문제였습니다. 이 글에서는 그 버그가 정확히 뭐고, 어떻게 고칠 수 있는지 정리해 봤습니다.
Claude Code 토큰 드레인, 뭐가 문제였나
Claude Code를 쓸 때마다 느낀 건데, 세션을 새로 시작할 때보다 이전 세션을 이어갈 때 토큰이 훨씬 더 빨리 떨어진다는 거였어요.
같은 대화를 하는데도 말이죠.
구체적으로는 이렇습니다:
- 새 세션: 캐시 읽기 비율 67%
- 5번 대화 후: 캐시 읽기 비율 48%
- 15번 대화 후: 캐시 읽기 비율 26%
캐시가 제대로 작동하지 않아서 계속 새로운 토큰을 쓰고 있었던 거예요. Claude Code 토큰 사용량 최적화가 전혀 안 되고 있었던 셈입니다.
캐시 버그의 정체 · 왜 계속 재발표가 될까
원인은 db8이라는 필터 함수 때문이었어요.
세션 파일(JSONL)을 저장할 때, 이 함수가 특정 메시지 타입을 지워버리고 있었습니다. 특히 deferred_tools_delta 기록이 사라졌어요. 이건 “어떤 도구들을 이미 발표했는지” 추적하는 기록이거든요.
세션을 재개하면 Claude Code가 “어? 발표한 도구 기록이 없네?”라고 생각하고 모든 도구를 다시 발표합니다. 그 과정에서 프롬프트 캐싱 경계(cache breakpoint)가 완전히 달라져 버려요. 결과적으로 캐시 읽기는 0이 되고, 모든 토큰이 새로 생성되는 겁니다.
패치 적용 전후 · 실제 성능 개선 수치
Reddit 커뮤니티에서 발견한 패치를 적용하면 어떻게 달라질까요?
패치 전:
- Turn 15: 캐시 읽기 15,451 / 캐시 생성 42,970 → 비율 26%
패치 후:
- Turn 2: 캐시 읽기 56,956 / 캐시 생성 728 → 비율 99%
거의 4배 가까운 효율 개선입니다. 같은 작업을 하는데 토큰을 4분의 1로 줄일 수 있다는 뜻입니다.
안전하게 적용하기 · 체크리스트 & 주의사항
중요 경고
⚠️ 이 패치는 공식이 아닙니다. Anthropic 공식 업데이트가 아니므로, 적용 시 계정 제한 가능성이 있습니다. 개인 책임 범위 내에서만 시도하세요.
Anthropic 개발팀에서는 이미 버그를 인정하고 다음 버전에서 수정하기로 했습니다. 그래서 기다리는 게 가장 안전합니다.
체크리스트
- Claude Code 버전 확인 (v2.1.81 기준, 다른 버전은 작동 안 할 수 있음)
- GitHub repo에서 패치 스크립트 다운로드 (공식 확인 필수)
- 기존 CLI 백업 생성 (
cli.js.orig) - npm으로 로컬 설치 (전역 설치 피하기)
- 패치 적용 후 테스트 (한 개 세션부터 시작)
- 캐시 비율이 95% 이상인지 확인
- Claude Code 공식 문서에서 버그 확인
- Reddit 원본 스레드 읽고 커뮤니티 반응 검토
- 패치 스크립트의 출처 확인 (신뢰할 수 있는 GitHub?)
- 현재 버전과 패치 호환성 체크
참고자료
- Reddit 원본 포스트 – CC Cache Fix
- GitHub Repository – Rangizingo/cc-cache-fix
- Anthropic Claude Code 공식 문서
- 프롬프트 캐싱 공식 가이드
최종 수정: 2026년 4월 2일
프롬프트 캐싱에 대해 더 알고 싶으신가요? 댓글로 궁금한 점 남겨주세요.
