Anthropic의 프롬프트 캐싱 문서 (prompt caching docs)에 명시된 두 가지 숫자가 여러분의 토큰 비용 대부분을 설명합니다:

"5분 캐시 쓰기 토큰(5-minute cache write tokens)은 기본 입력 토큰(base input tokens) 가격의 1.25배입니다." (출처)

"캐시 읽기 토큰(Cache read tokens)은 기본 입력 토큰(base input tokens) 가격의 0.1배입니다." (출처)

계산 결과는 다음과 같습니다: 동일한 접두사(prefix)에 대해 캐시 미스(cache miss) = 캐시 히트(cache hit)보다 12.5배 더 비쌈입니다. 50,000개 토큰 규모의 Claude Code 세션 접두사(system + tools + CLAUDE.md + 초기 대화 내용)를 기준으로 할 때, 턴(turn)당 발생하는 차이는 실제 비용으로 직결되며, 대부분의 사용자는 인지하지 못한 채 캐시를 깨뜨리고 있습니다.

Anthropic은 정확한 무효화 표 (exact invalidation table)를 공개하고 있습니다. 캐시는 다음 순서로 구축됩니다: tools → system → messages. 어느 단계에서든 변경이 발생하면 해당 단계와 그 이후의 모든 것이 무효화됩니다. 따라서 모든 캐시 파괴(cache bust)가 동일한 것은 아닙니다. 어떤 것은 최근 메시지만 삭제하지만, 어떤 것은 도구 정의(tool definitions)까지 포함하여 전체 접두사를 다시 불러옵니다.

다음은 Claude Code에서 이를 유발하는 5가지 행동이며, "모든 것을 파괴하는 것"부터 "꼬리 부분만 잘라내는 것" 순으로 나열했습니다:

1. 세션 도중 MCP 서버를 설치하거나 제거하기 — 모든 것을 파괴함

Anthropic: "도구 정의(tool definitions)(이름, 설명, 파라미터)를 수정하면 전체 캐시가 무효화됩니다." MCP 서버는 도구 정의를 등록합니다. 활성 세션 중에 claude mcp add를 추가하거나 /mcp를 실행하면, 캐싱된 모든 요청의 상단에 있는 tools 블록이 변경됩니다. 그 하위의 모든 것—system, CLAUDE.md, 전체 대화 내용—이 1.25배의 비용으로 다시 작성됩니다.

해결책: 모든 MCP를 세션 시작 시점에 설치하세요. 작업 도중 새로운 MCP가 필요하다면, 현재 작업을 완료하고 /clear를 실행한 다음 추가하세요.

2. /model 명령어로 모델 전환하기 — 캐시 네임스페이스(cache namespace)가 완전히 변경됨

캐시는 모델별로 적용됩니다. 세션 중간에 Sonnet에서 Opus로 전환하면 캐시가 이전되지 않으며, 다음 턴에서 접두사(prefix)를 새로 처리하게 됩니다. UI에는 별도의 경고가 표시되지 않습니다.

해결책: 세션 시작 시 모델을 결정하세요. 계획 수립에는 Opus를, 실행에는 Sonnet을 사용하되, 하나의 세션에서 계속 모델을 바꾸지 말고 별도의 세션으로 분리하여 사용하세요.

3. 세션이 열려 있는 동안 CLAUDE.md 수정하기 — 시스템 프롬프트와 메시지 캐시 모두 파괴됨

CLAUDE.md의 내용은 시스템 프롬프트(system prompt) 영역의 일부로 전달됩니다. Anthropic의 무효화(invalidation) 규칙에 따르면, 시스템 수준의 모든 변경 사항은 시스템 캐시(system cache)와 그 위에 구축된 메시지 캐시(messages cache) 내의 모든 내용을 무효화합니다. CLAUDE.md에서 단 한 줄만 수정하고 저장한 뒤 다음 메시지를 보내면, CLAUDE.md 아래에 있는 접두사가 다시 작성됩니다.

해결책: CLAUDE.md는 세션 도중이 아니라 세션 사이에 수정하세요. 만약 세션 중간에 반드시 수정해야 한다면, 긴 대화 내용을 다시 작성하는 비용을 지불하지 않도록 먼저 /clear 명령어를 사용하세요.

**4. 패스트 모드(Fast mode

100% 동일해야 합니다. "대체로 같은" 수준이 아닙니다. CLAUDE.md 파일에서 단 한 글자만 바뀌어도, 다음 턴을 처리할 때 12.5배의 비용을 지불하게 됩니다. 이것이 바로 모든 Anthropic 문서에서 세션 시작 시 설정을 고정(lock)하라고 권장하는 이유입니다.

출처

• Prompt caching — Anthropic API docs (인용된 모든 수치는 이 페이지에서 가져왔습니다)
• How Claude remembers your project — Anthropic Claude Code docs
• Best practices for Claude Code — Anthropic