Claude Code 팀은 프롬프트 캐시 적중률이 일정 수준 아래로 떨어지면 SEV(서비스 장애)를 선언합니다. 비용과 지연 시간에 직결되기 때문인데, 캐싱이 단순한 최적화가 아니라 에이전트의 생존 조건이라는 뜻이기도 합니다.
Claude Code 팀이 장기 에이전트 제품을 운영하면서 터득한 프롬프트 캐싱 최적화 원칙을 공유했습니다. 직관에 반하는 내용이 적지 않아 에이전트를 만드는 개발자라면 특히 눈여겨볼 만합니다.
출처: Lessons from building Claude Code: Prompt caching is everything – claude.com (2026.4.30)
캐싱은 접두사 매칭이다
프롬프트 캐싱의 작동 방식은 단순합니다. API는 요청 시작부터 cache_control 브레이크포인트까지의 내용을 캐시합니다. 즉, 요청들이 공통 접두사를 많이 공유할수록 캐시가 잘 활용됩니다.
Claude Code는 이 원칙을 토대로 시스템 프롬프트를 이렇게 구성합니다.
- 정적 시스템 프롬프트 및 도구 (전역 캐시)
- CLAUDE.md (프로젝트 내 캐시)
- 세션 컨텍스트 (세션 내 캐시)
- 대화 메시지
변하지 않는 내용을 앞에, 바뀌는 내용을 뒤에 배치해 최대한 많은 세션이 캐시를 공유하도록 설계한 구조입니다.
팀에서 이 순서를 깨뜨린 경험도 공유했습니다. 정적 시스템 프롬프트에 상세한 타임스탬프를 넣거나, 도구 정의 순서가 비결정론적으로 섞이거나, 에이전트 도구의 파라미터를 변경했을 때 캐시가 무효화됐습니다. 순서는 생각보다 훨씬 민감합니다.
시스템 프롬프트를 바꾸지 말고 메시지를 쓰라
현재 시각이나 파일 변경 사항처럼 프롬프트 내용이 outdated될 때, 시스템 프롬프트를 수정하면 캐시 미스가 발생합니다. Claude Code는 대신 다음 사용자 메시지나 도구 결과에 <system-reminder> 태그로 업데이트된 정보를 전달합니다. 캐시를 유지하면서 모델에 새 정보를 건네는 방식입니다.
세션 중 모델을 바꾸면 더 비싸진다
프롬프트 캐시는 모델별로 분리됩니다. 그래서 100,000 토큰 대화를 Opus로 진행하다가 쉬운 질문을 Haiku에게 넘기면, Haiku용 캐시를 처음부터 다시 구축해야 합니다. 결과적으로 Opus에게 그냥 물어보는 것보다 비용이 더 들 수 있습니다.
모델 전환이 필요하다면 서브에이전트를 활용하는 방식을 씁니다. Opus가 현재 작업을 정리한 핸드오프 메시지를 만들고, 다른 모델이 그걸 받아 새로운 세션을 시작하는 구조입니다. Claude Code의 Explore 에이전트가 Haiku를 쓸 때 이 패턴을 적용합니다.
도구는 절대 빼지 마라
세션 중에 도구를 추가하거나 제거하면 캐시 전체가 무효화됩니다. 도구가 캐시 접두사의 일부이기 때문입니다.
직관적으로는 “지금 필요한 도구만 주면 되지 않나?” 싶지만, 그 순간 이전 대화의 캐시가 날아갑니다.
Plan Mode 설계가 대표적인 사례입니다. Plan Mode 진입 시 읽기 전용 도구만 남기는 방식이 직관적이지만 캐시를 깹니다. 대신 모든 도구를 그대로 유지한 채 EnterPlanMode와 ExitPlanMode를 도구로 추가했습니다. 모드 전환은 시스템 메시지로 처리하고, 도구 정의는 절대 바꾸지 않습니다. 덕분에 모델이 스스로 어려운 문제를 감지하면 캐시를 깨지 않고 Plan Mode에 자동 진입하는 것도 가능해졌습니다.
수십 개의 MCP 도구를 다루는 경우에는 defer_loading 방식을 씁니다. 도구를 제거하는 대신, 이름만 있는 경량 스텁(stub)을 두고 defer_loading: true로 표시합니다. 모델이 도구를 선택할 때만 전체 스키마가 로드되는 방식입니다. 캐시 접두사는 항상 같은 스텁이 같은 순서로 유지됩니다.
Compaction도 캐시 위협 요소다
컨텍스트 창이 가득 찼을 때 대화를 요약해 이어가는 Compaction 과정에서도 함정이 있습니다.
가장 단순한 방법은 “이 대화를 요약해줘”라는 별도 API 호출을 쓰는 겁니다. 그런데 이 요청은 시스템 프롬프트와 도구가 다르기 때문에 첫 토큰부터 접두사가 갈립니다. 결과적으로 요약 요청 전체가 비캐시 요금으로 청구됩니다. 대화가 길수록 이 비용이 커집니다.
Claude Code의 해법은 캐시 안전 포킹(cache-safe forking) 입니다. 요약 요청을 보낼 때 부모 대화와 정확히 같은 시스템 프롬프트, 컨텍스트, 도구 정의를 유지합니다. 부모 대화의 메시지를 앞에 붙이고, 요약 프롬프트를 새 사용자 메시지로 맨 뒤에 추가합니다. API 관점에서는 부모 요청의 마지막과 거의 동일한 요청이 들어오는 셈이라 캐시 접두사가 재사용됩니다.
이 패턴은 이제 API에 Compaction 기능으로 직접 내장되어 있습니다.
캐싱을 인프라처럼 다루기
Claude Code 팀이 강조하는 메시지는 하나입니다. 캐시 적중률을 업타임처럼 모니터링하고, 캐시 미스를 인시던트로 처리하라는 것입니다. 몇 퍼센트 포인트의 미스율이 비용과 지연 시간에 큰 영향을 줍니다.
에이전트 제품을 처음부터 캐싱 중심으로 설계한다는 말은, 기능이 아닌 캐시 제약 조건을 먼저 고려하며 구조를 짜는 것을 뜻합니다. Plan Mode나 defer_loading이 그 결과물입니다. 원문에는 각 패턴의 구체적인 구현 방식과 API 사용법도 담겨 있습니다.
답글 남기기