프롬프트 캐싱으로 비용·지연 줄이기

프롬프트 캐싱으로 비용·지연 줄이기

Claude Code가 반복되는 프롬프트 컨텍스트를 캐싱해 비용과 지연 시간을 줄이는 메커니즘을 설명하는 페이지입니다. 캐시 적중(cache hit)은 캐시 미스보다 훨씬 저렴하고 빠릅니다. 코드 에이전트에서의 캐시 동작을 이해하면 비용을 최적화할 수 있습니다.

출처: 공식문서

본문

프롬프트 캐싱이란

Anthropic API는 반복되는 프롬프트 접두사(prefix)를 캐시해 재사용합니다. 이후 요청이 이전과 같은 프롬프트 접두사로 시작하면, 입력 토큰이 다시 처리되는 대신 캐시된 결과가 재사용됩니다. 결과적으로 실제 처리되는 토큰이 줄어 비용이 낮아지고 응답이 빨라집니다.

  • 캐시 히트: 캐시에 있던 접두사를 재사용 (입력 토큰의 캐시 읽기 비용만)
  • 캐시 미스: 전체 프롬프트를 새로 처리 (캐시 쓰기 비용 + 전체 입력 비용)

코드 에이전트 환경에서 프롬프트 접두사는 시스템 프롬프트, 도구 정의, 턴이 쌓인 대화 컨텍스트 등이 되며, 턴이 거듭될수록 이 접두사가 길어집니다.

Claude Code에서의 캐시 동작

Claude Code는 세션 도중 같은 컨텍스트(시스템 프롬프트, 도구 정의, 읽은 파일, 이전 메시지)를 반복해서 모델에 보냅니다. 캐싱을 활용하면:

  • 반복되는 접두사가 재사용돼 비용이 줄어듭니다.
  • 컨텍스트가 커지는 긴 세션일수록 절감 효과가 큽니다.
  • 별도 구성 없이 자동 동작하지만, 설정으로 캐시 동작을 튜닝할 수 있습니다.

프롬프트 캐싱 관련 설정

model 구성과 캐시 관련 옵션을 조정해 캐시 활용을 제어합니다.

캐시에 들어가는 토큰 수를 예측하고 싶다면 세션의 예상 컨텍스트 크기(시스템 프롬프트 + 도구 정의 + 현재 대화)를 고려하세요. 캐시는 접두사 단위로 동작하므로, 접두사 길이가 유지되는 한 이후 턴에서 히트율이 올라갑니다.

캐시 비용

  • 캐시 히트 입력 토큰: 일반 입력 토큰보다 저렴 (대략 1/10 수준, 모델·가격에 따라 다름)
  • 캐시 미스: 캐시 쓰기 비용이 입력 토큰에 추가
  • 출력 토큰: 캐시와 무관하게 동일

정확한 가격은 Anthropic 가격 페이지를 참조하세요.

비용 절감 모범 사례

  • 컨텍스트를 안정적으로: 세션 중 시스템 프롬프트·도구 정의가 자주 바뀌면 접두사가 깨져 히트율이 떨어집니다. 안정된 접두사를 유지하세요.
  • 긴 세션 활용: 턴이 쌓일수록 접두사가 길고 재사용 빈도가 높아 절감 효과가 커집니다. 관련 작업은 한 세션에 유지하는 것이 유리할 수 있습니다.
  • /compact·/clear 조심: 컨텍스트를 요약·리셋하면 접두사가 바뀌어 캐시가 무효화됩니다. 큰 세션을 줄일 때는 절감 효과와의 균형을 보세요.
  • 큰 파일 재읽기 제한: 자주 읽는 파일을 접두사에 유지하면 반복 재처리를 피합니다.

더 알아보기