프롬프트 캐싱으로 Claude Code의 성능을 극대화하다

본문은 프롬프트 캐싱(Prompt Caching)이 에이전트(Agent) 시스템의 성능과 비용에 미치는 영향에 대해 설명한다. 프롬프트 캐싱은 이전 요청의 계산 결과를 재사용하여 지연 시간(Latency)을 줄이고 비용을 절감하는 핵심 기술이다. Claude Code는 시스템 프롬프트(System Prompt)를 구성할 때, 변경 빈도가 낮은 정보(Static Information)를 먼저 배치하고, 대화 내용과 같이 동적으로 변하는 정보(Dynamic Information)를 뒤에 배치하는 방식으로 캐시 효율을 높인다. 특히, API는 요청 시작부터 각 `cache_control` 지점까지의 모든 내용을 캐싱하므로, 요청 순서(Request Order)가 캐싱 효율에 결정적인 영향을 미친다.

글에서는 프롬프트 캐싱(Prompt Caching)의 효율을 높이기 위한 다양한 설계 패턴을 제시한다. 예를 들어, 시간 정보와 같이 자주 변경되는 정보(Dynamic Information)는 시스템 프롬프트(System Prompt)에 직접 포함하는 대신, 메시지(Message)를 통해 전달하여 캐시 미스(Cache Miss)를 방지한다. 또한, 모델 변경(Model Switching)이나 도구 추가/제거(Tool Addition/Removal)는 캐시를 무효화하므로, 서브 에이전트(Subagent)를 활용하거나 Plan Mode와 Tool Search와 같은 기능을 캐싱 제약 조건에 맞춰 설계한다. 이러한 설계는 캐시 적중률(Cache Hit Rate)을 극대화하여 시스템의 성능과 비용 효율성을 향상시킨다.

본문은 Plan Mode와 Tool Search 기능을 프롬프트 캐싱(Prompt Caching) 제약 조건에 맞춰 설계한 사례를 소개한다. Plan Mode의 경우, 도구 집합(Tool Set)을 변경하는 대신 `EnterPlanMode`와 `ExitPlanMode`를 도구로 활용하여 캐시를 유지한다. 사용자가 Plan Mode를 활성화하면, 에이전트는 시스템 메시지를 통해 Plan Mode임을 알리고, 코드 탐색(Code Exploration) 및 파일 수정 금지(File Modification Prohibition)와 같은 지침을 제공한다. Tool Search의 경우, 모든 도구를 요청에 포함하는 대신, `defer_loading: true`를 사용하여 필요한 도구만 로드하도록 지연 로딩(Deferred Loading)을 구현한다. 이러한 설계를 통해 캐시 적중률(Cache Hit Rate)을 유지하면서 기능의 유연성을 확보한다.

글에서는 컨텍스트 창(Context Window)이 가득 찼을 때, 캐시 효율을 유지하면서 요약(Summarization)을 수행하는 방법을 설명한다. Claude Code는 캐시 안전 포킹(Cache-safe Forking)을 통해 요약을 수행한다. 즉, 요약 요청 시, 부모 대화(Parent Conversation)와 동일한 시스템 프롬프트(System Prompt), 사용자 컨텍스트(User Context), 시스템 컨텍스트(System Context), 도구 정의(Tool Definition)를 사용한다. 부모 대화의 메시지를 먼저 추가하고, 요약 프롬프트를 새로운 사용자 메시지로 추가하여, API가 부모 요청과 거의 동일한 요청으로 인식하도록 한다. 이 방식을 통해 캐시된 접두사(Cached Prefix)를 재사용하고, 요약 프롬프트 자체에 대한 비용만 지불한다. 이는 지속적인 캐시 적중(Cache Hit)을 보장하여 시스템의 성능을 유지한다.

본문은 Claude Code 구축 경험을 바탕으로 프롬프트 캐싱(Prompt Caching) 최적화를 위한 핵심 교훈을 제시한다. 첫째, 프롬프트 캐싱은 접두사 일치(Prefix Match) 방식이므로, 접두사 내의 모든 변경 사항은 캐시를 무효화한다. 따라서 시스템 전체를 이 제약 조건에 맞춰 설계해야 한다. 둘째, 시스템 프롬프트(System Prompt) 변경 대신 메시지(Message)를 사용하고, 모델 및 도구 변경을 최소화해야 한다. 셋째, 캐시 적중률(Cache Hit Rate)을 모니터링하고, 캐시 미스(Cache Miss)를 심각한 문제로 간주해야 한다. 마지막으로, 요약과 같은 포킹(Forking) 작업 시, 부모와 동일한 캐시 안전 매개변수를 사용하여 캐시 적중을 보장해야 한다. 이러한 교훈을 통해 에이전트(Agent) 시스템 구축 시 성능과 비용 효율성을 극대화할 수 있다.