Claude Code 아키텍처로 살펴본 프롬프트 캐싱 설계 전략과 비용 최적화 원칙

장시간 실행되는 AI 에이전트를 운영하다 보면 응답 지연과 비용 문제가 빠르게 누적됩니다. 특히 수만~수십만 토큰이 오가는 세션에서는 작은 설계 실수 하나가 전체 비용 구조를 무너뜨릴 수 있습니다. Claude Code 구축 사례는 이 문제를 정면으로 다루며, 그 해답을 프롬프트 캐싱 중심 설계에서 찾았습니다.

이 글에서는 Claude Code의 아키텍처를 통해 프롬프트 캐싱이 어떻게 동작하는지, 왜 시스템 전체를 이 제약에 맞춰 설계해야 하는지, 그리고 실제로 어떤 패턴이 비용과 지연을 획기적으로 줄이는지 정리합니다. 장기 실행 에이전트를 설계하고 있다면 반드시 고려해야 할 실전 교훈을 얻을 수 있습니다.

반응형

---

1. 왜 프롬프트 캐싱이 전부인가

“Cache Rules Everything Around Me”라는 표현은 에이전트 아키텍처에도 그대로 적용됩니다.

프롬프트 캐싱은 이전 라운드트립에서 수행한 연산 결과를 재사용해 latency와 cost를 크게 줄이는 기술입니다. 장시간 실행 에이전트에서는 매 요청마다 비슷한 시스템 프롬프트, 도구 정의, 세션 컨텍스트가 반복됩니다. 이 반복 영역을 재계산하지 않도록 만드는 것이 핵심입니다.

Claude Code는 이 전제를 중심으로 전체 구조가 설계되었습니다. 캐싱이 없다면 장시간 대화 기반 제품 자체가 경제적으로 성립하기 어렵습니다.

---

2. 프롬프트 캐싱의 작동 원리: 접두사 매칭

프롬프트 캐싱은 접두사(Prefix) 매칭 방식으로 작동합니다. API는 요청 시작부터 특정 cache_control 중단점까지의 내용을 캐싱합니다.

여기서 중요한 사실은 단 하나입니다.

접두사 어디에서든 변경이 발생하면, 그 이후의 모든 캐시가 무효화됩니다.

따라서 요청 간 공유 접두사를 최대화하는 것이 핵심이며, 이를 위해 반드시 다음 원칙을 따라야 합니다.

• 정적 콘텐츠는 앞에 배치
• 동적 콘텐츠는 뒤에 배치

Claude Code의 실제 배치 순서는 다음과 같습니다.

1. 정적 시스템 프롬프트 및 도구 (전역 캐싱)
2. Claude.MD (프로젝트 내 캐싱)
3. 세션 컨텍스트 (세션 내 캐싱)
4. 대화 메시지

이 순서는 단순해 보이지만 매우 깨지기 쉽습니다. 예를 들어 다음과 같은 변화만으로도 캐시가 무효화될 수 있습니다.

• 시스템 프롬프트에 상세 타임스탬프 삽입
• 도구 순서의 비결정적 셔플링
• 도구 매개변수 업데이트

결론적으로, 프롬프트의 구조적 안정성이 곧 비용 안정성입니다.

---

3. 시스템 메시지를 활용한 업데이트 전략

시간 정보 변화나 사용자 파일 변경처럼 프롬프트 내부 정보가 오래될 수 있는 상황이 존재합니다. 이때 시스템 프롬프트를 직접 수정하면 어떻게 될까요?

즉시 캐시 미스가 발생하고 사용자 비용이 증가합니다.

Claude Code는 이를 피하기 위해 다음과 같은 전략을 사용합니다.

• 시스템 프롬프트를 수정하지 않음
• 대신 다음 턴의 user message 또는 tool result에 <system-reminder> 태그로 업데이트 정보 삽입

예를 들어 “이제 Wednesday”와 같은 시간 변경 정보도 시스템 메시지 형태로 다음 턴에 전달합니다.

이 방식은 캐시된 접두사를 보존하면서도 최신 정보를 반영할 수 있는 안전한 설계입니다.

---

4. 세션 중간에 모델을 변경하면 안 되는 이유

프롬프트 캐시는 모델별로 고유합니다.

예를 들어 Opus로 100k 토큰 대화를 진행하다가, 간단한 질문을 위해 Haiku로 전환한다고 가정해보겠습니다. 직관적으로는 더 저렴할 것 같지만 실제로는 Haiku용 캐시를 처음부터 다시 구축해야 합니다.

결과적으로 Opus로 계속 답하는 것보다 비용이 더 높아질 수 있습니다.

이 문제를 해결하는 방식은 서브에이전트 구조입니다.

• 상위 모델(Opus)이
• 다른 모델(Haiku)에 전달할 핸드오프 메시지를 준비
• 별도 서브 세션에서 처리

Claude Code의 Explore 에이전트는 이 패턴을 사용합니다. 모델 전환은 직접 변경이 아니라 분리된 실행 단위로 다뤄야 캐시를 보존할 수 있습니다.

---

5. 도구 추가·제거가 가장 위험한 이유

도구 집합 변경은 캐시 무효화의 가장 흔한 원인입니다.

도구 정의 자체가 캐싱된 접두사의 일부이기 때문입니다. 도구를 하나라도 추가하거나 제거하면 전체 대화의 캐시가 무효화됩니다.

5-1. Plan Mode의 캐시 중심 설계

직관적 접근은 다음과 같습니다.

• 사용자가 plan mode에 진입
• 읽기 전용 도구만 남김

하지만 이는 도구 집합을 변경하므로 캐시를 파괴합니다.

Claude Code의 실제 설계는 다릅니다.

• 모든 도구를 항상 요청에 포함
• EnterPlanMode와 ExitPlanMode를 도구로 구현
• Plan mode 진입 시 시스템 메시지로 행동 제약 전달

도구 정의는 절대 변경되지 않습니다.

이 방식은 캐시를 유지하면서도 상태 전환을 구현할 수 있습니다. 추가로, 모델이 스스로 EnterPlanMode를 호출해 자율적으로 모드 전환이 가능합니다.

5-2. Tool Search: 제거 대신 지연 로딩

수십 개의 MCP 도구를 모두 포함하면 비용이 증가합니다. 그렇다고 제거하면 캐시가 파괴됩니다.

해결책은 defer_loading 방식입니다.

• 실제 도구 대신 이름만 포함된 경량 스텁(defer_loading: true) 전송
• 필요 시 ToolSearch 도구를 통해 전체 스키마 로드
• 스텁은 항상 같은 순서로 존재

이 구조는 캐싱된 접두사를 안정적으로 유지합니다.

---

6. 컨텍스트 포킹과 컴팩션의 올바른 구현

컨텍스트 윈도우를 초과하면 대화를 요약해 새 세션을 시작하는 컴팩션이 필요합니다.

잘못된 구현 방식은 다음과 같습니다.

• 별도 API 호출
• 다른 시스템 프롬프트와 도구 사용
• 부모 대화와 전혀 다른 요청 구조

이 경우 캐시 접두사가 전혀 일치하지 않아 모든 입력 토큰에 대해 전액 비용이 발생합니다.

Cache-Safe Forking 패턴

올바른 방법은 다음과 같습니다.

• 부모 대화와 동일한 시스템 프롬프트, 사용자 컨텍스트, 도구 정의 사용
• 부모 대화 메시지를 앞에 배치
• 컴팩션 프롬프트를 새 사용자 메시지로 끝에 추가

API 관점에서 이 요청은 부모의 마지막 요청과 거의 동일하게 보입니다. 따라서 캐싱된 접두사를 재사용할 수 있고, 새로 발생하는 비용은 컴팩션 프롬프트 부분뿐입니다.

추가로, 컨텍스트 윈도우 내에 컴팩트 메시지와 요약 출력 토큰을 위한 컴팩션 버퍼를 확보해야 합니다.

이 패턴은 이후 API 차원에서 직접 컴팩션 기능으로 내장될 수 있는 구조적 기반이 됩니다.

---

7. 캐시 적중률은 업타임처럼 관리해야 한다

캐시 적중률은 단순한 최적화 지표가 아닙니다.

수 퍼센트의 캐시 미스도 비용과 지연에 극적인 영향을 미칩니다. 따라서 캐시 적중률은 업타임처럼 모니터링하고, 작은 하락도 인시던트로 취급해야 합니다.

에이전트 제품에서는 캐시 미스가 곧 손익 구조 변화로 이어집니다.

---

핵심 교훈 정리

Claude Code 사례에서 얻을 수 있는 핵심 교훈은 다음과 같습니다.

1. 프롬프트 캐싱은 접두사 매칭이며, 접두사 변경은 곧 전체 무효화
2. 시스템 프롬프트를 수정하지 말고 대화 중 시스템 메시지 삽입으로 대응
3. 세션 중간에 모델을 직접 변경하지 말 것
4. 도구 추가·제거 금지, 상태 전환은 도구로 모델링
5. 도구 제거 대신 지연 로딩 활용
6. 컴팩션과 포크 작업은 부모 접두사를 공유해야 함
7. 캐시 적중률을 업타임처럼 관리

결론은 명확합니다.

에이전트를 구축한다면 첫날부터 프롬프트 캐싱 중심으로 설계해야 합니다.

---

728x90

에이전트 설계의 관점을 바꿔야 한다

프롬프트 캐싱은 단순한 성능 최적화 기법이 아닙니다. 아키텍처의 제약 조건이며, 설계의 출발점입니다.

장기 실행 에이전트에서 비용과 지연 문제를 해결하고 싶다면 기능 추가보다 먼저 물어야 할 질문은 이것입니다.

“이 변경이 접두사를 깨는가?”

이 질문을 중심에 두는 순간, 시스템 설계 방식이 완전히 달라집니다. 그리고 그 차이가 곧 제품의 지속 가능성을 결정합니다.

300x250

https://x.com/trq212/status/2024574133011673516

X의 Thariq님(@trq212)