Claude Code 비용, 제4막 — 실수 목록 및 치트 시트

이번 막에서는 모든 내용을 두 가지 참조 아티팩트(artifact)로 통합합니다: 복습을 위한 실수 목록(각 실수에는 증상, 비용, 해결책 포함)과 한 페이지 분량의 치트 시트(cheat sheet)입니다.

실수 목록 (The mistakes catalogue)

비용이 얼마나 발생하는지와 얼마나 자주 발생하는지를 기준으로 대략적으로 정렬되었습니다.

1. 대화(conversation) 단위가 아닌 턴(turn) 단위의 라우팅 (Routing per turn instead of per conversation). 증상: 대화 중간에 모델을 전환하여 "비용 절감"을 시도하는 라우터. 비용: 첫 번째 전환 시 발생하는 콜드 프리픽스 쓰기(cold prefix write) + 재진입 시마다 발생하는 캐치업 쓰기(catch-up write); Sonnet의 경우 순손실(net loss, 측정치 +2.1%) 발생. 해결책: 스티키 라우팅(route sticky) 적용 — 대화 단위 또는 서브 에이전트(sub-agent) 단위로 수행. 전환 여부보다 전환 시점이 더 중요함.

2. JSON을 재직렬화(re-serializes)하는 프록시 삽입. 증상: 요청을 파싱(parse)하고 다시 방출(re-emit)하는 로깅/압축/라우팅 프록시. 비용: 논리적으로 동일한 재인코딩(re-encode)이라 할지라도 바이트(bytes)가 변경되어(구분자, 이스케이프, 키 순서, 숫자 형식 등) 모든 트래픽에 대해 캐시 히트율(cache hit rate)이 ~0으로 떨어짐. 해결책: 원본 바이트를 그대로(verbatim) 전달; messages 꼬리 부분에 대해 정밀한 바이트 조각 교체(surgical byte-fragment replacement) 방식으로만 수정.

3. 도구(tool)/MCP 인터페이스를 불안정하게 유지. 증상: 초기 턴에서 도구 개수가 증가함(비동기 MCP 커넥터), 또는 동적/런타임 도구 발견(dynamic/runtime tool discovery)이 활성화됨. 비용: 바이트-0 변화(byte-0 churn) → 영향을 받는 매 턴마다 전체 콜드 재빌드(full cold rebuild, 2배의 쓰기 발생). 해결책: --strict-mcp-config 사용 및 고정된 시작 도구 세트(frozen startup tool set) 구성; 런타임 도구 변형(runtime tool mutation) 대신 고정된 디스패처 도구(fixed dispatcher tool) 사용.

4. 프롬프트 초반의 휘발성 토큰 (Volatile tokens early in the prompt). 증상: 시스템 프롬프트 상단 근처에 타임스탬프(timestamp), UUID, 또는 요청 ID(request-ID)가 위치함; 정렬되지 않은 json.dumps. 비용: 모든 요청이 고유한 프리픽스(prefix)를 가짐 → 조용히 캐시 히트율이 ~0%로 떨어짐. 해결책: 모든 휘발성 콘텐츠를 마지막 중단점(breakpoint) 이후로 이동; 키(key)를 결정론적(deterministically)으로 정렬.

5. 프록시(proxy)에서 사고 블록(thinking blocks)을 제거하거나 편집하는 경우. 증상: 사고 블록을 "정리"하거나 제거하는 프록시를 사용함. 비용: 편집 시 → 400 (무결성 저해); 제거 시 → 200이지만 위치에 따른 재키(re-key) 발생 (초기 블록을 제거하면 후기 블록 제거 시의 440 토큰 대비 8,104개의 캐시 토큰을 손실함). 해결책: 사고 블록을 절대 변형하지 마세요; Claude Code가 조립한 그대로의 요청 본문(request body)을 전달하세요.

6. 표시된 세션 비용을 실제 청구서로 신뢰하는 경우. 증상: /cost 명령어나 상태 표시줄을 신뢰할 수 있는 정보원(source of truth)으로 사용함. 비용: 1시간 분량의 쓰기 작업을 5분 분량의 1.25배 요율로 책정하며, 읽기 비용은 실제 세션 대비 약 10% 낮게 측정함 ($1.97 대비 $1.77).
해결책: 정확한 과금 확인을 위해 Anthropic Console을 사용하세요; 표시된 수치는 세션 내 상대적 비교 용도로만 사용하세요.

7. 3회 미만으로 읽을 접두사(prefix)를 캐싱하는 경우. 증상: 수명이 짧은 커스텀 하네스(harness)에서 공격적으로 캐싱을 수행함. 비용: 낭비된 쓰기 비용은 2배에 달하며, 이는 캐싱을 하지 않았을 때보다 두 배의 비용이 드는 것입니다. 해결책: 접두사를 3회 이상 다시 읽을 때만(손익분기점) 캐싱하세요; 대화형 세션은 기본적으로 캐싱하도록 두세요.

8. 캐싱된 접두사에 공격적인 입력 압축기(input compressor)를 실행하는 경우. 증상: 대화형 접두사에 LLMLingua 또는 LLM 기반 압축을 적용함. 비용: 캐싱된 바이트를 다시 쓰게 되면 읽기 비용(0.1배)이 쓰기 비용(2배)으로 전환됩니다; 정확도는 약 20배를 넘어서면 저하됩니다. 해결책: 손실될 캐시가 없는 경우(one-shot, RAG 조립)나 새로운 꼬리(tail) 부분에만 입력 압축기를 사용하세요; 캐시를 인식하는(cache-aware) 도구를 선호하세요.

9. 에이전트적 폭발(Agentic bursts)로 인해 20-블록 룩백(lookback) 범위를 초과하는 경우. 증상: 단일 턴에서 10개 이상의 병렬 도구 호출(tool calls)이 발생함 (≈21개 이상의 도구 호출/결과 블록). 비용: 다음 턴에서 캐시를 다시 연결할 수 없게 되어, 공백 부분을 새로 써야(cold-writes) 합니다. 해결책: Claude Code에서는 폭발적인 호출을 제한하세요; 프록시 뒤에서는 상태가 없는 중단점 그리드(stateless breakpoint grid, 간격 ~18, 마커 4개)를 사용하여 턴당 최대 ~74개 블록까지 복구할 수 있습니다.

10. 최소 접두사(minimum prefix) 미만의 캐시 중단점(cache breakpoint). 증상: 캐싱을 위해 1,024토큰 미만의 접두사(prefix)를 마킹함. 비용: 마커가 아무런 동작을 하지 않음 (cache_creation: 0); 사용자는 캐싱이 작동 중이라고 생각함. 해결책: cache_creation이 0이 아닌지 확인한 후, 다음 요청에서 cache_read가 0이 아닌지 확인하십시오.

11. HTTP 200이 캐시가 유지되었음을 의미한다고 가정함. 증상: "여전히 작동한다"는 이유로 프록시(proxy) 변경 여부를 판단함. 비용: 200은 "유효한 요청"을 의미할 뿐, "캐시 보존"을 의미하지 않습니다. 저렴한 읽기(read) 작업이 조용히 비싼 쓰기(write) 작업으로 전환될 수 있습니다. 해결책: 상태 코드만 보지 말고, 접두사(prefix)에 영향을 주는 모든 변경 사항에 대해 다음 요청의 cache_read를 모니터링하여 검증하십시오.

12. 대화 도중 Haiku에서 Sonnet으로 전환함. 증상: 진행 중인 Haiku 대화를 Sonnet으로 격상시킴. 비용: 세 가지 문제가 중첩됩니다. 즉, 전체 캐시 미스(cache miss, 모델 범위 내), Haiku가 무시하고 있었다고 생각했던 부분을 Sonnet이 이제 유지하고 비용을 청구함, 그리고 접두사 효율성(prefix-leanness)의 이점이 모두 증발함. 해결책: 대화 시작 시점에 티어(tier)를 결정하십시오. 만약 격상해야 한다면, 이를 저렴한 연속이 아닌 새로운 콜드 스타트(cold start)로 받아들여야 합니다.

원페이지 치트 시트 (One-page cheat sheet)

네 가지 멘탈 모델 (The four mental models)

• 기억상실증에 걸린 계약자 (Amnesiac contractor) — 서버는 아무것도 저장하지 않습니다; 요청(request)만이 유일한 상태(state)입니다.
• 접두사 일치 캐시 (Prefix-match cache) — 캐싱은 엄격한 바이트 접두사(byte-prefix) 방식입니다; N번째 바이트에서의 변경은 N 이상의 모든 것을 무효화합니다.
• 모델 범위 키 (Model-scoped key) — 캐시 엔트리(cache entry)는 하나의 모델에 속합니다; 다른 모델은 이를 읽을 수 없습니다.
• 암호화된 봉투 (Encrypted envelope) — 사고 과정은 signature 안에 봉인된 채로 돌아옵니다; 당신은 그것을 운반할 뿐, 열거나 수정할 수 없습니다.

수치 (The numbers)

• 캐시 읽기 (read) = 입력의 0.1배; 캐시 쓰기 (write) = 2배 (1시간 TTL, Claude Code가 전송하는 방식); 출력 (output) = 입력의 5배, 캐시되지 않음.
• 캐시는 3번째 읽기부터 (2배 비용 시점에서) 손익분기점을 넘깁니다. 낭비된 쓰기(write)는 2배의 비용을 발생시킵니다 (캐시 미적용 시의 두 배).
• 캐시 히트 (cache hit)는 콜드 프로세싱 (cold processing)보다 약 10배 저렴합니다.
• 토크나이저 (Tokenizer) 계수: Opus 4.8 = 1.0; Haiku 4.5 = 0.775 (측정치); Sonnet 4.6 ≈ 0.775 (가정치).
• Claude Code: 3개의 중단점 (breakpoints), 모두 1시간 TTL (도구+ID, 전체 시스템, 슬라이딩 테일 (sliding tail)). 표시되는 total_cost_usd는 실제보다 적게 보고됩니다 (쓰기 비용을 1.25배로 책정함).

렌더링 순서 (The render order) — tools → system → messages. 안정적인 것을 먼저, 변동적인 것을 마지막에 배치합니다.

가장 안전한 두 가지 비용 조절 레버 (The two safest cost levers) (접두사 (prefix)는 절대 건드리지 마세요):

1. 출력 압축 (Output compression) (Caveman 방식) — 절대 캐시되지 않는 가장 비싼 항목을 공략합니다.
2. 고정 라우팅 (Sticky routing) — 대화/하위 에이전트(sub-agent)별 설정: Opus 대비 전부 Sonnet 사용 시 ≈ −53%, 전부 Haiku 사용 시 ≈ −85%.

길러야 할 반사 신경: 도구 (tools), 시스템 (system), 또는 메시지 이력 (message history)을 건드리는 어떠한 변경을 하기 전에, _"이 변경이 캐시된 접두사 (cached prefix) 내부의 1바이트라도 바꾸는가?"_라고 자문하십시오. 만약 그렇다면, 당신은 2배의 재작성 (rewrite) 비용을 지불하게 됩니다 — 반드시 의도적인 경우에만 그렇게 하십시오.

종합 (Synthesis) — 가이드 전체를 12줄로 요약

1. Claude Code는 상태가 없는 (stateless) API 클라이언트입니다. 매 턴은 도구 (tools) + 시스템 (system) + 전체 대화 내용을 포함하는 하나의 완전한 /v1/messages 요청입니다. 서버는 아무것도 저장하지 않으며, 클라이언트는 매 턴마다 (사고 과정 (thinking)을 포함하여) 모든 것을 다시 전송합니다. 요청 자체가 유일한 상태입니다.
2. 캐싱 (Caching)은 접두사 일치 (prefix match) 방식입니다. N번째 바이트에서 변경이 발생하면 N 이상의 모든 캐시가 무효화됩니다. 도구(tools) → 시스템(system) → 메시지(messages) 순서로 배치하십시오. 변하지 않는 것을 앞에, 변하기 쉬운 것을 뒤에 두어야 합니다.
3. 중단점 (Breakpoints)은 콘텐츠 주소 지정 방식의 절단 지점입니다 (최대 4개). 가장 길게 일치하는 접두사를 읽고, 차이점 (delta)만 다시 처리합니다. 역방향 재연결 (backward re-link)은 20개 블록으로 제한됩니다.
4. 새로운 턴은 추가하고 읽는 것이지, 무효화하는 것이 아닙니다. 읽기 작업은 TTL (Time-To-Live)을 갱신합니다. 2배의 쓰기 프리미엄 (write premium)은 오직 차이점 (delta)에 대해서만 지불되며, 거대한 접두사 (prefix)는 한 번만 기록됩니다.
5. Claude Code는 1시간 TTL을 가진 3개의 중단점을 사용합니다 — 도구+신원 (tools+identity), 전체 시스템 (full system), 슬라이딩 테일 (sliding tail). 날짜는 시스템 중단점 이후의 시스템 리마인더 (system-reminder)입니다. 과금 헤더의 토큰은 캐시 키 (cache key)에서 제외됩니다. 표시되는 비용은 1시간 쓰기 비용을 1.25배로 책정하여 실제보다 적게 보고됩니다.
6. **모델을 전환하는 것이 항상

Dynamic MCP tools (런타임 list_changed 또는 비동기 커넥터 로드)는 바이트 0에서 전체 재구축 (full rebuild)으로 전환되며 비용을 소모합니다. 도구 세트(tool set)를 안정적으로 유지하고, 고정된 디스패처 (fixed dispatcher)를 사용하세요. 먼저 도구 인터페이스 (tool surface)를 안정화해야 합니다.
10. 출력 (Output)이 생성 중심의 턴 (generation-heavy turns)을 지배함 — 콜드 크로스 모델 바운스 (cold cross-model bounce)가 여전히 승리할 수 있는 유일한 영역입니다 (출력 > 약 2,500 토큰).
11. 턴 단위가 아닌 대화 단위로 라우팅 (Route per conversation, not per turn) 하세요. 쓰기 비용이 2배인 경우, 요청당 20% Sonnet 방식은 2.1% 손해를 보는 반면, Sonnet 고정 (sticky all-Sonnet) 방식은 53%를 절감하고, Haiku 고정 (all-Haiku) 방식은 85%를 절감합니다. 전환 여부보다 전환 시점이 더 중요합니다.
12. 비용 절감 도구는 비용 항목별로 클러스터링됩니다. 라우터 (Routers)는 모델 계층 (model tier)을 공략합니다 (고정 방식에서만 효과가 있음). 압축기 (compressors)는 입력/캐시 (input/cache)를 공략합니다 (캐시된 접두사 (cached prefix)를 바이트 단위로 안정적으로 유지해야 함). 출력 압축기 (output compressors)는 가장 비싸고 캐시에 영향을 주지 않는 항목을 공략합니다. 가장 안전한 승리 전략인 출력 압축 (output compression)과 고정 라우팅 (sticky routing)은 캐시된 접두사를 전혀 건드리지 않는 두 가지 방식입니다.

참고 문헌 및 주의 사항

비용은 Anthropic의 리스트 가격을 기준으로 측정된 토큰 수에서 계산되었습니다 (2026-06-15 기준, 1M당): Opus 4.8 $5/$25, Sonnet 4.6 $3/$15, Haiku 4.5 $1/$5 (입력/출력); 캐시 읽기 (cache read) 0.1×, 캐시 쓰기 (cache write) 2× (1시간 TTL). 토크나이저 계수 (tokenizer factor) 0.775는 Haiku에서 측정되었으며 Sonnet에 대해서는 가정된 값입니다. Sonnet 라우팅 수치는 실행된 것이 아니라 모델링된 것입니다. Claude Code에 표시되는 total_cost_usd는 1.25× 쓰기 승수를 사용하며, 문서화된 요율보다 낮게 읽힙니다. 가격과 동작은 버전에 따라 다릅니다 (Claude Code 2.1.150, 2026년 중반) — 사용자의 환경에 맞춰 다시 확인하십시오.

Anthropic 문서

• 확장된 사고 (Extended thinking) (서명, 암호화, 표시, 보관, 멀티 턴/도구 사용): platform.claude.com/docs/en/build-with-claude/extended-thinking
• 적응형 사고 및 노력 (Adaptive thinking & effort): platform.claude.com/docs/en/build-with-claude/adaptive-thinking
• 프롬프트 캐싱 (Prompt caching): platform.claude.com/docs/en/build-with-claude/prompt-caching
• 가격 책정 (Pricing): claude.com/pricing

비용 절감 도구 (Cost-reduction tooling)

• 비용 절감 도구 (Cost-reduction tooling):
• Routers: RouteLLM lm-sys/RouteLLM · vLLM Semantic Router vllm-project/semantic-router
• 입력/캐시 압축기 (Input/cache compressors): Headroom chopratejas/headroom · LLMLingua microsoft/LLMLingua · RTK rtk-ai/rtk · lean-ctx yvgude/lean-ctx
• 출력 압축기 (Output compressor): Caveman JuliusBrussee/caveman
• 참조된 MCP 서버: github/github-mcp-server (v1.0.5; v1.1.0에서 dynamic-toolsets 제거됨, PR #2512 — 캐시가 아닌 기술 부채용) · docker/mcp-gateway (v0.43.0 / 4833d8c; dynamic-tools 기본 활성화)