모든 설정을 변경하지 않았습니다. 이것은 그냥 백그라운드에서 prompt 캐싱이 정상적으로 작동 중임을 의미합니다.

하지만 캐시가 무엇인지를 정말 이해하고 나서, 캐시를 "망가뜨리지 않는" 방법을 알게 되면, 동일한 할당량을 사용하더라도 제 세션을 더 오래 유지할 수 있습니다. 따라서, 이곳에는 Claude Code prompt 캐싱의 80/20 입문 안내서가 제공되며, API 수준의 심층적인 내용은 다루지 않습니다.

요약

토큰을 캐시하는 비용은 일반적인 입력 토큰의 10%뿐입니다. 9100만 개의 캐시 토큰은 실제 청구량으로는 약 900만 개의 토큰과 동등합니다.

Claude Code 구독판의 캐시 TTL은 1시간이며, API의 기본값은 5분이며, Sub-agent는 항상 5분입니다.

캐시는 시스템 레이어, 프로젝트 레이어, 대화 레이어로 나뉩니다.

세션 중간 전환 모델은 캐시를 파괴하며, "opus plan" 모드를 활성화하는 것을 포함합니다.

캐시 청구는 어떻게 이뤄지나요?

캐시되는 매 토큰마다 비용은 일반 입력 토큰의 10%입니다.

그래서 대시보드에 특정 날짜에 9100만 개의 토큰이 캐시되었다고 표시되면, 실제 청구량은 대략 900만 개의 토큰을 처리한 것과 같습니다. 이것이 캐시가 없는 경우보다 Claude Code를 오랫동안 사용하면 세션이 거의 "무료"로 연장된 것으로 느끼는 이유입니다.

대시보드에 주목해야 할 두 가지 숫자가 있습니다:

캐시 생성: 콘텐츠를 캐시에 씁니다. 일회성 비용이 발생하며, 다음 대화에서 작동합니다.
캐시 읽기: Claude가 캐시에서 재사용하는 토큰으로, CLAUDE.md, 툴 정의, 이전 메시지 등을 포함합니다. 다시 입력 처리보다 비용이 10배 저렴합니다.

캐시 읽기 수치가 높으면 캐시를 효율적으로 활용 중이라는 것을 의미하며, 이 수치가 낮으면 동일한 컨텍스트에 대해 반복해서 지불하고 있다는 의미입니다.

Anthropic의 Thariq는 이렇게 말했습니다. "실제로 우리는 prompt 캐시의 히트율을 모니터링하며, 히트율이 너무 낮아지면 경보가 작동하고 경고 수준 사고가 발생합니다."

그는 이미 꽤 좋은 X 기사를 썼습니다. 캐시 히트율이 높을 때는 Claude Code의 느낌이 더 빨라지고, Anthrop의 서비스 비용이 감소하며, 구독 한도가 내구성이 더 강해지며, 장기 코딩 세션이 더 현실적으로 변화합니다.

하지만 히트율이 매우 낮으면 모두 손해를 보게 됩니다.

그래서 양측의 인센티브는 사실상 동일합니다: Anthrop은 캐시 히트율이 더 높아지기를 바라고 있으며, 당신도 히트율이 더 높아지기를 희망합니다. 실제로 주의해야 할 것은, 보이지 않는 것 같지만 캐시를 조용히 재설정하는 작은 습관들뿐입니다.

캐시는 각 대화 라운드에서 어떻게 성장하나요?

캐시는 접두어 일치(prefix matching)에 의존합니다.

너무 기술적인 세부 사항에 빠지지 마세요. 이해해야 할 핵심은 여기에 있습니다: 특정 위치 이전의 내용이 이미 캐시된 내용과 완전히 일치하면, Claude는 이 부분의 캐시 토큰을 재사용할 수 있습니다.

새로운 대화는 대략적으로 다음과 같이 전개됩니다:

Claude Code 문서에 따르면, 새로운 대화는 일반적으로 다음과 같이 진행됩니다:

첫 번째 대화 라운드: 어떠한 캐시도 없습니다. 시스템 제안어구, 귀하의 프로젝트 컨텍스트(예: CLAUDE.md, 메모리, 규칙) 및 귀하의 첫 번째 메시지가 모두 다시 처리되어 캐시에 기록됩니다.

두 번째 대화 라운드: 첫 번째 라운드에서 모든 내용이 이미 캐시되어 있습니다. Claude는 귀하의 새로운 응답과 다음 메시지만 처리하면 됩니다. 이 라운드의 비용은 훨씬 낮아집니다.

세 번째 대화 라운드: 논리는 같습니다. 이전 대화는 여전히 캐시에 유지되며, 최신 대화 라운드만 다시 처리해야 합니다.

캐시 자체는 세 가지 계층으로 나뉩니다:

Thariq의 X 기사에서:

시스템 계층(System layer): 기본 명령어, 도구 정의(read, write, bash, grep, glob) 및 출력 스타일을 포함합니다. 이 계층은 전역 캐시입니다.

프로젝트 레이어(Project layer) : CLAUDE.md, 메모리, 프로젝트 규칙이 포함됩니다. 이 레이어는 프로젝트 캐시에 따라 구성됩니다.

대화 레이어(Conversation) : 응답과 메시지가 포함되며, 각 대화 라운드마다 지속적으로 늘어납니다.

대화 중에 시스템 레이어나 프로젝트 레이어의 내용이 변경되면 모든 내용을 처음부터 다시 캐시해야 합니다. 이것이 가장 "비싼" 작업입니다. 상상해보세요: 이미 16번 메시지까지 대화를 나누었을 때, 갑자기 시스템 힌트가 바뀌거나 중간에 1시간이 멈췄다면, 1번 메시지부터의 모든 토큰을 다시 처리해야 합니다.

1시간과 5분의 혼동

가장 혼란스러운 부분입니다.

Claude Code 구독 버전: 기본 TTL은 1시간입니다.

Claude API: 기본 TTL은 5분입니다. 높은 비용을 지불하여 1시간으로 업그레이드할 수 있습니다.
모든 계획의 Sub-agent: 항상 5분입니다.

Claude.ai 웹 채팅: 공식적으로 명시된 내용이 없습니다. 아마 구독 버전과 비슷할 것으로 생각되지만, 확인하지 않았습니다.

몇 달 전에 많은 사람들이 클로드 구독 한도가 너무 빨리 소모된다고 불평했습니다. 그 때에는 안쏘픽(Anthropic)이 TTL을 1시간에서 5분으로 조용히 낮춘 것으로 생각한 사람들이 있었고, 사용자에게 공지하지 않았다고 생각했습니다. 하지만 사실은 그렇지 않으며, Claude Code의 TTL은 여전히 1시간입니다.

문제는 Claude Code와 API의 문서가 별도로 공개되어 있고, 이 둘이 실제로 확실히 다른 것인데도 혼란이 있었다는 점입니다.

많은 양의 서브 에이전트 워크플로우를 실행하거나 API를 직접 사용하는 경우 5분이라는 숫자가 매우 중요합니다. 그러나 95%의 Claude Code 사용자에게 있어 실제로 주의해야 할 것은 그 1시간 윈도우뿐입니다.

95% 사용자를 커버하는 세 가지 습관

아래는 일상적인 사용 시 정말 유용한 부분이라고 생각하는 것입니다.

긴 시간 멈추지 마세요

이미 1시간이 넘는 휴식을 취했다면 이전 내용은 대부분 캐시에서 만료되었을 것입니다. 다음 메시지는 다시 캐시를 구축하게 됩니다. 이러한 경우에는 이미 "차가워진" 이전 대화를 계속할 대신 명확한 전환을 하고 새 대화를 시작하는 것이 일반적으로 더 경제적입니다.

작업 전환 시 재시작 바로하기

/compact 또는 /clear는 이미 캐시를 파괴하므로이 노드에서 한 번 제대로 재설정하는 것이 더 나을 수 있습니다.

나는 직접 session handoff skill을 만들었고 이를 /compact 대신 사용하고 있습니다. 이는 이미 완료한 작업, 보류 중인 의사 결정, 가장 중요한 파일 및 앞으로 어디서부터 진행해야 하는지에 대한 요약을 제공합니다. 그런 다음 /clear를 실행하고 이 요약을 붙여넣으면 마치 중단되지 않은 것처럼 계속 진행할 수 있습니다.

compact 명령은 때로 실행이 매우 느립니다. 그에 비해 handoff skill은 보통 1분 이내에 완료됩니다.

Claude 채팅에서는 대형 문서를 Projects에 넣는 것이 좋습니다

Claude.ai의 캐시 메커니즘에는 매우 자세한 공식 설명이 없지만, Projects는 일반 대화 스레드와는 다른 최적화 방식을 사용한다고 합니다. 그래서 매우 큰 문서를 붙여넣어야 한다면 직접 대화창에 넣는 것이 아닌 Project에 넣는 것이 좋습니다.

어떤 조작이 캐시를 은밀하게 파괴하나요?

일부 작업은 명시적인 경고 없이 캐시를 완전히 재설정합니다.

모델 전환: 캐시는 접두사 일치에 의존하기 때문에 각 모델에는 고유한 캐시가 있습니다. 모델을 전환하면 다음 요청은 어떠한 캐시도 적중되지 않고 전체 기록을 새로 읽습니다.

Opus plan 모드: 이 설정은 계획 단계에서 Opus를 사용하고 실행 단계에서 Sonnet을 사용합니다. 이것은 이전에 일부 토큰 최적화 비디오에서 추천한 바 있으며 그 이유가 있습니다. 그러나 이해해야 할 점은 각 plan 전환은 본질적으로 모델 전환이며, 따라서 새로운 캐시를 구축해야 한다는 것입니다. 장기적으로는 세션 시간을 연장하는 데 도움이 되지만, 하단에서 무슨 일이 일어나고 있는지 알아야 합니다.

세션 중 CLAUDE.md를 편집하는 것은 가능합니다: 이 변경은 즉시 적용되지 않고 다음 재시작 때야 적용됩니다. 따라서 현재 실행중인 캐시에는 영향을 주지 않습니다.

내 무료 토큰 대시보드

저는 전시한 스크린샷이 무료 토큰 대시보드에서 왔습니다.

https://github.com/nateherkai/token-dashboard

이것은 매우 간단한 GitHub 저장소입니다. 링크를 Claude Code에게 건네서 로컬 localhost에서 배포하게 하면 이전에 수행한 모든 세션 기록을 읽어들이며 처음부터 계산을 시작하지 않습니다. 시작하자마자 매일의 입력(input), 출력(output), 캐시 생성(cache create) 및 캐시 읽기(cache read) 데이터를 볼 수 있습니다.

다만 한 가지 주의할 점은 이 대시보드가 로컬 장치에 대한 토큰 데이터를 통계하는 것입니다. 데스크톱에서 노트북으로 전환하면 숫자가 완전히 일치하지 않습니다. 각 장치에는 고유한 통계 보기가 있습니다.

Summary

프롬프트 캐싱(Prompt caching)은 깊이 연구할 가치가 있는 주제입니다. Thariq의 그 기사는 이겼다. 여기보다 더 완벽하게 설명하고 있으니 전체 모습을 원한다면 꼭 읽어보세요.

그러나 모든 세부 사항을 완전히 이해할 필요는 없습니다. 이로부터 이익을 얻으려면 가장 중요한 80/20만 이해하면 됩니다. 캐싱된 토큰은 일반 토큰보다 10배 가치가 있고, Claude Code의 TTL은 1시간입니다. 모델을 전환하면 캐시가 손상되며, 과업 간에 명확한 전달을 확실히 하면 종종 오래된 세션을 "만료" 상태로 만들고 다시 사용하는 것보다 더 나은 선택입니다.

[Original Link]

BlockBeats 공식 커뮤니티에 참여하세요:

Telegram 구독 그룹：https://t.me/theblockbeats

Telegram 토론 그룹：https://t.me/BlockBeats_App

Twitter 공식 계정：https://twitter.com/BlockBeatsAsia