만약 여러분이 프로덕션 환경에서 AI 에이전트 (AI agents)를 운영하고 있다면, 아마도 미처 생각하지 못한 비용 문제가 있을 것입니다. 에이전트 기반 대화 (agentic conversation)의 매 턴마다 전체 프롬프트 (prompt)가 모델로 전송됩니다. 여기에는 시스템 지침 (system instructions), 모든 도구 정의 (tool definitions), 이전에 로드된 모든 프로젝트 컨텍스트 (project context), 그리고 전체 대화 기록 (conversation history)이 포함됩니다. 모델은 이 모든 것을 처음부터 끝까지 매번 처리합니다. 두 번의 짧은 상호작용이라면 큰 문제가 되지 않습니다. 하지만 시스템 프롬프트 (system prompt)만 20,000 토큰 (tokens)에 달하는 50턴의 코딩 세션이라면 어떨까요? 이는 세션 전체에 걸쳐 100만 토큰의 반복적인 계산이 발생함을 의미하며, 모두 전체 입력 가격으로 청구되지만 새로운 통찰력은 전혀 만들어내지 못합니다. 모델은 이미 49턴 전에 해당 시스템 프롬프트를 처리했습니다. 단지 하지 말라는 명령이 없었기 때문에 다시 수행하고 있을 뿐입니다. 이것이 바로 프롬프트 캐싱 (prompt caching)이 해결하고자 하는 문제입니다. 그리고 Claude Code는 이를 올바르게 수행하는 방법에 대한 가장 좋은 사례 연구일 것입니다.

모든 프롬프트의 두 가지 구성 요소
가장 먼저 이해해야 할 점은 프롬프트 내의 모든 토큰 (tokens)이 동일하게 취급되지 않는다는 것입니다. 어떤 에이전트 기반 API 호출을 보더라도 두 개의 뚜렷한 계층을 확인할 수 있습니다:

기반 (The foundation): 이는 턴마다 변하지 않고 유지되는 모든 것입니다. 시스템 지침 (system instructions), 도구 스키마 (tool schemas), CLAUDE.md 파일과 같은 프로젝트 수준의 컨텍스트 (project-level context), 행동 규칙 (behavioral rules) 등이 해당됩니다. 만약 1번째 턴과 47번째 턴을 나란히 놓고 본다면, 이 부분은 동일할 것입니다.

대화 (The conversation): 이는 매 턴마다 달라지는 모든 것입니다. 사용자의 최신 메시지, 도구 호출 결과 (tool call results), 방금 읽은 파일 내용, 터미널 출력 등이 포함됩니다. 이는 상호작용이 진행될 때마다 커지며, 모델이 처리해야 할 진정으로 새로운 정보입니다.

프롬프트 캐싱의 핵심 비결은 이 '기반' 부분이 재처리될 필요가 없다는 점을 인식하는 것입니다. 한 번 계산하여 결과를 저장한 뒤, 이후의 모든 턴에서 이를 재사용합니다. 모델은 '대화' 계층에 대해서만 새로운 작업을 수행합니다.

실제로 캐싱되는 것: 트랜스포머 (Transformer)의 관점
이것은 단순히 문자열 비교를 건너뛰는 것이 아닙니다.

캐싱이 왜 비용을 그토록 극적으로 절감하는지 이해하려면, 모델이 프롬프트 (Prompt)를 읽을 때 무엇을 하는지 알아야 합니다. LLM 추론 (Inference)은 두 단계로 나뉩니다: Prefill (프리필): 모델이 전체 입력을 받아 토큰 단위로 밀집 행렬 곱셈 (Dense Matrix Multiplications)을 수행하며 내부 표현 (Internal Representation)을 구축합니다. 이 과정은 계산 비용이 많이 들며, 대부분의 시간과 비용이 발생하는 지점입니다. Decode (디코딩): 모델이 한 번에 하나의 토큰씩 응답을 생성하며, 주로 프리필 단계에서 이미 구축된 상태 (State)를 읽어옵니다. 프리필 단계 동안 모델은 모든 토큰에 대해 Query (쿼리), Key (키), Value (값)라는 세 가지 벡터를 계산합니다. 이것들은 어텐션 메커니즘 (Attention Mechanism)의 구성 요소로, 모델이 입력의 어떤 부분이 다른 부분에 중요한지를 파악하는 방식입니다. 중요한 속성: 특정 토큰에 대한 Key 및 Value 벡터는 오직 해당 토큰 이전의 토큰들에만 의존합니다. 즉, 이들은 결정론적 (Deterministic)입니다. 입력이 같다면 출력도 같습니다. 따라서 20,000개 토큰으로 구성된 시스템 프롬프트 (System Prompt)에 대한 Key-Value 쌍을 한 번 계산하고 나면, 이를 저장할 수 있습니다. 다음에 동일한 접두사 (Prefix)를 가진 요청이 들어오면, 해당 20,000개 토큰에 대한 전체 프리필 계산을 건너뛰고 즉시 새로운 콘텐츠를 처리할 수 있습니다. Anthropic의 인프라는 입력 접두사를 해싱 (Hashing)함으로써 이를 수행합니다. 해시가 같으면 캐시된 텐서 (Tensors)를 사용하므로 재계산이 필요 없습니다. 해시가 다르면 (단 1바이트만 달라도), 전체를 재계산해야 합니다. 경제성: 여기서부터 이야기가 구체화됩니다.

Anthropic의 캐싱 가격 책정은 세 가지 계층으로 나뉩니다:

Claude Sonnet 4.6 (기본 입력 가격 $3/MTok 기준)의 경우, 실제 적용 사례는 다음과 같습니다:

• 표준 입력 (Standard input): $3.00 / MTok
• 캐시 읽기 (Cache read): $0.30 / MTok (90% 절감)
• 5분 캐시 쓰기 (5-min cache write): $3.75 / MTok (25% 프리미엄, 1회 발생)
• 1시간 캐시 쓰기 (1-hour cache write): $6.00 / MTok (2x 프리미엄, 1회 발생)

캐시 히트(Cache hit)가 발생하면 표준 입력 비용의 10%만 소요됩니다. 이는 5분 지속 시간 동안 단 한 번의 후속 읽기만 발생해도 캐싱 비용이 스스로를 충당한다는 것을 의미합니다. 20,000개 토큰의 접두사(Prefix)를 재사용하는 50턴(Turn) 규모의 세션의 경우, 절감액은 매 턴마다 복리로 쌓입니다.

실제 Claude Code 세션 추적하기
이론은 좋습니다. 돈이 어디로 흘러가는지 확인하기 위해 단일 디버깅 세션의 실제 토큰 경제학을 추적해 보겠습니다.

당신은 Next.js 프로젝트에서 Claude Code를 실행합니다. 세션이 시작되는 순간, 시스템 프롬프트(System prompt), 사용 가능한 모든 도구 정의(file read, file write, bash, grep, glob 등), 그리고 프로젝트의 CLAUDE.md를 로드합니다. 이 초기 페이로드(Payload)는 약 20,000개 토큰 정도에 달합니다. 이 토큰들 중 단 하나도 빠짐없이 새롭게 처리됩니다. 이것이 당신이 이 토큰들에 대해 전체 가격을 지불하는 유일한 시점입니다.

당신은 다음과 같이 입력합니다: "결제 흐름(Checkout flow)에 레이스 컨디션(Race condition)이 있습니다. 사용자가 제출 버튼을 더블 클릭할 때 주문이 가끔 중복됩니다."

Claude Code는 단순히 파일을 편집하기 시작하지 않습니다. 먼저, 코드베이스를 이해하기 위해 Explore 하위 에이전트(Subagent)를 가동합니다. 해당 하위 에이전트는 API 라우트를 읽고, 데이터베이스 스키마를 확인하며, 주문 처리 로직을 살펴보고, 프론트엔드 폼 핸들러(Form handler)를 조사합니다. 이러한 모든 파일 읽기(File reads)와 grep 결과는 도구 출력(Tool outputs)으로서 늘어나는 대화 내용에 추가됩니다. 여기서 핵심은, 이 새로운 콘텐츠 중 그 어떤 것도 20,000개 토큰의 접두사(Prefix)에는 영향을 주지 않는다는 점입니다.

시스템 프롬프트(System prompt), 도구 정의(Tool definitions), CLAUDE.md 등 이 모든 것은 첫 번째 턴(Turn)부터 캐시(Cache)에 남아 있습니다. 이후의 모든 API 호출은 이 20,000개의 토큰을 $3.00/MTok 대신 $0.30/MTok의 가격으로 읽어옵니다. 여러분은 새로운 내용, 즉 여러분의 메시지와 도구 출력값(Tool outputs)에 대해서만 전체 가격을 지불하면 됩니다. Explore 서브 에이전트(Subagent)가 작업을 마치고 발견한 내용을 메인 에이전트(Main agent)에게 전달합니다. 하지만 이 과정에서 15,000개의 토큰에 달하는 가공되지 않은 파일 내용(Raw file contents)을 대화에 쏟아붓지 않습니다. 대신 어떤 파일이 관련 있는지, 현재 로직이 무엇을 하는지, 경합 조건(Race condition)이 발생할 가능성이 있는 곳이 어디인지와 같은 압축된 요약본(Condensed summary)을 전달합니다. 이는 의도적인 설계 선택입니다. 동적인 꼬리(Dynamic tail) 부분을 컴팩트하게 유지함으로써 캐시 비율(Cache ratio)을 높게 유지할 수 있습니다. 이제 Plan 서브 에이전트가 작동합니다. 이 에이전트는 요약본을 받아 수정 사항을 추론하고(프론트엔드의 멱등성 키(Idempotency key), API의 중복 제거 확인(Deduplication check), 안전장치로서의 데이터베이스 유니크 제약 조건(Database unique constraint)), 단계별 구현 계획을 생성합니다. 여러분이 이를 승인하면, Claude Code가 코드 작성을 시작합니다. 이후 15분 동안 여러분은 대화를 주고받습니다. Claude Code가 멱등성 로직(Idempotency logic)을 작성하면, 여러분은 결제 도중 페이지가 새로고침되는 경우도 처리해 달라고 요청하고, Claude Code는 이를 조정합니다. 이러한 각 턴(Turn)은 동적인 꼬리에 새로운 콘텐츠를 추가합니다. 하지만 기초가 되는 그 20,000개의 토큰은 매번 캐시에서 읽어옵니다. 각 캐시 히트(Cache hit)는 TTL(Time-to-live)을 재설정하므로, 작업을 계속하는 한 캐시는 절대 만료되지 않습니다. 세션이 끝날 무렵, 여러분은 아마 25번 정도의 턴을 거쳤을 것입니다. 처리된 총 토큰 수는 쉽게 150만 개를 넘어섭니다. 하지만 /cost 명령어를 실행하면, 청구서는 전체 가격으로 150만 개를 사용했을 때와는 전혀 다른 이야기를 들려줍니다. 대다수의 토큰이 90% 할인된 가격의 캐시 읽기(Cache reads)였기 때문입니다. 이것이 단 하나의 디버깅 작업을 수행하는 데 있어 4.50달러짜리 세션과 0.90달러짜리 세션을 가르는 차이입니다.

실제 운영 수치 (The Production Numbers)
이것은 이론적인 이야기가 아닙니다. Claude Code의 실제 운영 지표는 다음과 같습니다:

활성 세션에서 입력 토큰의 95% 이상은 일반적으로 캐시 히트이며, 기본 가격의 0.1배로 청구됩니다.

세션 내 400K(40만) 토큰 중, 아마도 20K에서 40K 정도만이 전체 가격으로 청구될 것입니다. 프롬프트 캐싱 (Prompt Caching)이 없다면, 긴 Opus 코딩 세션(압축 사이클을 포함한 100턴)은 입력 토큰 비용으로 50달러에서 100달러가 들 수 있습니다. 하지만 이를 사용하면 10달러에서 19달러로 줄어듭니다.

캐시 히트율 (Cache Hit Rate)을 망치는 단 한 가지 요소

프롬프트 캐싱에는 처음 접하는 거의 모든 사람을 당황하게 만드는 함정이 있습니다. 캐시 키 (Cache key)는 프롬프트 접두사 (Prefix)의 정확한 바이트 시퀀스 (Byte sequence)를 해싱한 값입니다. 의미가 아닙니다. 내용도 아닙니다. 정확히 동일한 순서의 정확한 바이트여야 합니다. 만약 시스템 프롬프트 내의 두 단락 순서를 바꾼다면, 해시 값이 변경됩니다. 완전한 캐시 미스 (Cache miss)가 발생하며, 모든 것이 전체 가격으로 다시 계산됩니다.

이로 인해 세 가지 실질적인 결과가 발생합니다:

1. 세션 중간에 도구 세트 (Tool set)를 변경하지 마세요
   도구 정의 (Tool definitions)는 캐시된 접두사의 일부입니다. 만약 1턴에는 없던 도구를 12턴에 추가한다면, 변경 시점 이후의 모든 토큰은 캐시 미스가 됩니다. 필요한 모든 것을 시작 시점에 로드하세요.

2. 대화 중간에 모델을 전환하지 마세요
   각 모델은 자신만의 캐시를 가집니다. 나중에 비용을 아끼기 위해 Opus에서 Sonnet으로 전환하는 것은 새 모델을 위해 캐시를 처음부터 다시 구축해야 함을 의미합니다. 재구축에 드는 비용이 저렴한 요율로 아낀 비용보다 더 클 것입니다.

3. 상태를 업데이트하기 위해 시스템 프롬프트를 편집하지 마세요
   만약 에이전트가 무언가(예: "사용자가 현재 인증됨")를 추적해야 한다면, 이를 시스템 프롬프트에 주입하지 마세요. 대신 다음 사용자 메시지에 노트 형식으로 추가하세요. 그러면 시스템 프롬프트는 바이트 단위로 동일하게 유지되어 캐시가 유효하게 유지됩니다.

Claude Code는 이 세 가지 규칙을 철저히 준수합니다. 이것이 바로 수백만 개의 세션에 걸쳐 92%의 히트율을 유지하는 비결입니다.

이를 여러분의 에이전트에 적용하기

Anthropic API를 기반으로 구축하고 있다면 동일한 원칙이 적용됩니다. 여기 실질적인 플레이북 (Playbook)이 있습니다.

프롬프트 구조가 중요합니다
가장 안정적인 콘텐츠를 상단에 배치하세요:

1. 시스템 지침 및 규칙 (가장 안정적이며, 가장 먼저 캐싱됨)

2. 도구 정의 (세션 지속 시간 동안 안정적임)

3. 참조 문서 / 검색된 컨텍스트 (Retrieved context)

5. 대화 기록 + 도구 출력 (Conversation history + tool outputs) (동적이며, 매 턴마다 증가함)

캐시는 위에서 아래 방향(top-down)으로 작동합니다. 첫 번째 변경 지점(change point)보다 위에 있는 모든 내용은 캐싱된 상태로 유지됩니다. 그 아래에 있는 모든 내용은 다시 계산됩니다.

자동 캐싱(Auto-caching) 사용하기

Anthropic의 API는 이제 자동 캐시 관리(automatic cache management)를 지원합니다. 요청에 단 하나의 cache_control 필드만 추가하면 시스템이 브레이크포인트(breakpoint) 배치를 대신 처리해 줍니다:

{ 
  "model" : "claude-sonnet-4-6-20260514" ,
  "max_tokens" : 1024 ,
  "cache_control" : { "type" : "ephemeral" },
  "system" : "여기에 시스템 프롬프트를 입력하세요..." ,
  "messages" : [ ... ] 
}

대화가 진행되고 더 많은 콘텐츠가 안정화됨에 따라 시스템은 캐시 경계(cache boundary)를 앞으로 이동시킵니다. 이 기능이 존재하기 전에는 토큰 경계를 수동으로 계산해야 했습니다. 계산이 틀리면 캐시를 전혀 활용하지 못하게 되었습니다.

캐시를 깨뜨리지 않고 압축하기 (Compact without breaking the cache)

대화가 컨텍스트 제한(context limit)에 도달하여 내용을 요약해야 할 때, 시스템 프롬프트와 도구 정의(tool definitions)는 동일하게 유지하십시오. 압축 지침(compaction instruction)을 새로운 사용자 메시지로 추가하면, 캐싱된 접두사(cached prefix)는 유효한 상태로 남습니다. 압축 프롬프트 자체에 대해서만 새로운 토큰 비용을 지불하면 됩니다.

히트율(Hit rate) 모니터링하기

모든 API 응답에는 추적해야 할 세 가지 필드가 포함되어 있습니다:

{ 
  "usage" : { 
    "cache_creation_input_tokens" : 15200 ,
    "cache_read_input_tokens" : 184800 ,
    "input_tokens" : 3400 
  } 
}

• cache_creation_input_tokens: 캐시에 기록된 토큰 (최초 처리 시)
• cache_read_input_tokens: 캐시에서 읽어온 토큰 (저렴한 토큰)
• input_tokens: 전체 비용으로 처리된 토큰 (사용 가능한 캐시 없음)

cache_read_input_tokens와 전체 input_tokens 사이의 비율이 바로 캐시 효율성 점수입니다. 가동 시간(uptime)을 추적하듯이 이를 추적하십시오. 수치가 갑자기 떨어진다면 프롬프트 구조 중 무언가가 변경되어 캐시가 무효화되었음을 의미합니다.

핵심 요약 (Key Takeaways)

프롬프트 캐싱(Prompt caching)은 단순히 켜고 잊어버리는 설정이 아닙니다. 이는 에이전트가 프롬프트를 구성하고, 도구를 관리하며, 긴 대화를 처리하는 방식에 내재되어야 하는 아키텍처 패턴(architectural pattern)입니다.

Claude Code는 이것이 제대로 구현되었을 때 어떤 모습인지 보여줍니다. 안정적인 접두사(stable prefixes), 서브에이전트 요약(subagent summarization), 그리고 캐시 인식 컨텍스트 관리(cache-aware context management)를 기반으로 92%의 캐시 히트율(cache hit rate)과 81%의 비용 절감을 달성했습니다. 만약 여러분이 에이전트(agents)를 구축하면서 캐시 아키텍처(cache architecture)를 고려하지 않고 있다면, 예산의 대부분을 낭비하고 있는 것입니다. 우리는 Web After AI에서 이와 같은 AI 인프라와 툴링(tooling)을 정기적으로 분석합니다. 실용적이고, 과장 없이, 실제로 이해할 수 있도록 설명합니다.