Claude Code Costs, Act IV — The mistakes catalogue & cheat sheet

개요

Claude Code 사용 시 발생하는 비용 관련 실수들을 정리하고, 이를 방지하기 위한 참조 자료로 실수 목록과 치트 시트를 제공합니다.

주요 내용

* 실수 목록 및 해결 방안:
* 회당 라우팅 대신 대화당 라우팅: 대화 중 모델 전환 시 발생하는 콜드 시작 및 재진입 비용을 줄이기 위해 대화 또는 서브 에이전트별로 라우팅을 고정합니다.
* JSON 재직렬화 프록시 삽입: 프록시에서 JSON을 파싱하고 재방출할 때 발생하는 바이트 변경으로 캐시 히트율이 낮아지는 문제를 방지하기 위해 원본 바이트를 그대로 전달하고, 필요한 경우에만 부분적으로 수정합니다.
* 불안정한 툴/MCP 표면 유지: 비동기 MCP 커넥터나 동적 툴 검색으로 인해 발생하는 콜드 리빌드 비용을 줄이기 위해 --strict-mcp-config를 사용하고 고정된 툴셋을 유지합니다.
* 프롬프트 초반의 휘발성 토큰: 타임스탬프, UUID 등 휘발성 콘텐츠가 프롬프트 초반에 위치하면 고유한 접두사로 인해 캐시 히트율이 0%에 가까워지는 문제를 해결하기 위해, 휘발성 콘텐츠를 마지막 중단점 뒤로 이동시키고 키를 결정적으로 정렬합니다.
* 프록시에서 생각 블록 제거 또는 편집: 생각 블록을 편집하거나 제거할 때 발생하는 오류(400) 또는 비용 증가를 방지하기 위해 생각 블록을 절대 수정하지 않고 Claude Code가 조립한 대로 요청 본문을 유지합니다.
* 표시된 세션 비용을 송장으로 신뢰: /cost 또는 상태 표시줄의 비용이 실제 청구 비용과 다를 수 있으므로, 절대적인 청구를 위해서는 Anthropic Console을 사용하고 표시된 금액은 세션 내 상대적 비교에만 활용합니다.
* 3회 미만 읽을 접두사 캐싱: 단기 사용자 정의 하네스에서 공격적인 캐싱은 낭비된 쓰기 비용을 발생시키므로, 최소 3회 이상 재독할 경우에만 캐싱합니다.
* 캐시된 접두사에 공격적인 입력 압축기 실행: LLMLingua 등으로 캐시된 접두사를 압축하면 캐시된 바이트를 다시 쓰게 되어 비용이 증가하고 정확도가 저하되므로, 캐시가 없는 경우(one-shot, RAG) 또는 신규 테일 부분에만 압축기를 사용합니다.
* 에이전트 버스트가 20 블록 조회 범위 초과: 단일 턴에서 과도한 병렬 툴 호출은 다음 턴에서 캐시 재연결 실패 및 콜드 쓰기 비용을 발생시키므로, 버스트를 제한하거나 상태 비저장 중단점 그리드를 사용합니다.
* 최소 접두사 미만의 캐시 중단점: 1,024 토큰 미만 접두사에 대한 캐싱 마커는 작동하지 않으므로, cache_creation이 0이 아닌지, 다음 요청에서 cache_read가 0이 아닌지를 확인합니다.
* HTTP 200이 캐시 생존을 의미한다고 가정: 200 응답은 유효한 요청을 의미할 뿐 캐시 보존을 보장하지 않으므로, 접두사 변경 시 다음 요청의 cache_read를 확인합니다.
* 대화 중간에 Haiku → Sonnet 전환: 대화 중 모델을 전환하면 캐시 누락, 이전 모델의 생각 블록 처리 비용 발생, 접두사 이점 증발 등의 비용이 발생하므로, 대화 시작 시 티어를 결정하고 전환이 필요한 경우 새롭게 시작하는 것으로 간주합니다.

* 치트 시트:
* 네 가지 정신 모델: 무기억 계약자(서버는 아무것도 저장하지 않음), 접두사 일치 캐시(바이트 접두사 기준), 모델별 키(캐시 항목은 특정 모델에 속함), 암호화된 봉투(생각은 서명에 봉인되어 전달).
* 비용 관련 수치: 캐시 읽기 0.1x, 캐시 쓰기 2x(1시간 TTL), 출력 5x(캐시 안 됨), 캐싱은 3번째 읽기부터 손익분기점, 낭비된 쓰기 비용은 2x, 캐시 히트 시 콜드 처리보다 10x 저렴.
* 토크나이저 계수: Opus 4.8 = 1.0, Haiku 4.5 = 0.775, Sonnet 4.6 ≈ 0.775.
* Claude Code의 브레이크포인트: 3개(툴+ID, 전체 시스템, 슬라이딩 테일), 모두 1시간 TTL.
* 비용 절감 레버: 출력 압축(Caveman) 및 고정 라우팅(대화당/서브 에이전트당)은 캐시된 접두사를 건드리지 않아 가장 안전.
* 주요 권고: 툴, 시스템, 메시지 기록을 변경하기 전에 캐시된 접두사 바이트를 변경하는지 확인하고, 변경 시 2배의 재작성 비용이 발생함을 인지.

시사점

Claude Code에서 발생하는 비용 증가의 주요 원인을 파악하고, 캐시 효율성을 극대화하며 불필요한 쓰기 작업을 최소화하는 전략을 적용함으로써 상당한 비용 절감 효과를 얻을 수 있습니다.