claude-code 같은 장기 실행 에이전트는 매 턴 긴 시스템 프롬프트, 도구 정의, 프로젝트 규칙, 대화 기록을 다시 보낸다. Anthropic의 Claude Code 팀은 이 비용을 줄이기 위해 하네스를 프롬프트 캐싱(prompt caching) 중심으로 설계했다. 핵심 원칙은 단순하다. 캐시는 prefix가 바이트 단위로 일치할 때만 재사용되므로, 변하지 않는 것은 앞에 두고 변하는 것은 뒤에 둔다.
캐시 친화적 프롬프트 순서
Claude Code가 권장하는 구조는 다음 순서다.
- 정적 시스템 프롬프트와 도구 정의
- 프로젝트별
CLAUDE.md - 세션 컨텍스트
- 대화 메시지
앞부분이 여러 요청에서 같을수록 캐시 적중률이 올라간다. 반대로 정적 시스템 프롬프트에 상세 타임스탬프를 넣거나, 도구 정의 순서가 실행마다 바뀌거나, 세션 도중 도구 파라미터가 달라지면 그 지점 뒤의 캐시가 깨진다.
업데이트는 시스템 프롬프트가 아니라 메시지로 넣는다
현재 시간, 파일 변경, 사용자 상태처럼 최신 정보가 필요할 때 시스템 프롬프트 자체를 수정하면 캐시 prefix가 달라진다. Claude Code는 이런 정보를 다음 사용자 메시지나 도구 결과 안의 시스템 알림 형태로 넣어 정적 prefix를 보존한다.
에이전트 앱을 직접 만든다면 “항상 고정되는 지침”과 “이번 턴에만 필요한 상태”를 API 레벨에서 분리해야 한다. 예를 들어 날짜, 현재 브랜치, 마지막 빌드 결과, 파일 변경 알림은 시스템 프롬프트가 아니라 메시지 계층에 넣는 편이 낫다.
세션 중 모델을 바꾸지 않는다
프롬프트 캐시는 모델별로 분리된다. 긴 세션이 이미 Opus 계열 모델의 캐시에 올라가 있다면, 쉬운 질문 하나를 Haiku 계열 모델로 바꾸는 것이 오히려 더 비쌀 수 있다. 새 모델에서 같은 긴 prefix를 다시 구축해야 하기 때문이다.
모델 전환이 필요하면 기존 세션을 직접 바꾸기보다 서브에이전트를 쓴다. 상위 모델이 짧은 hand-off 메시지를 만들고, 하위 모델이 그 요약만 받아 독립 작업을 처리하면 긴 parent 세션의 캐시는 유지된다.
도구를 빼고 넣지 않는다
도구 정의는 캐시되는 prefix의 일부다. 세션 도중 “이번에는 읽기 전용 도구만”, “이번에는 MCP 도구 3개만”처럼 도구 집합을 바꾸면 캐시가 깨진다. Claude Code의 Plan Mode는 이를 피하기 위해 도구 집합 자체를 교체하지 않고, EnterPlanMode와 ExitPlanMode를 도구로 모델링한다. 상태 전환은 메시지와 도구 호출로 표현하고, 도구 정의 목록은 유지하는 방식이다.
도구가 너무 많아 prefix가 커지는 문제는 제거가 아니라 지연 로딩으로 푼다. Anthropic은 defer_loading 형태의 가벼운 도구 스텁을 항상 같은 순서로 두고, 모델이 필요할 때 tool search로 전체 스키마를 발견하게 하는 패턴을 제시한다.
컴팩션도 parent prefix를 공유해야 한다
컨텍스트가 가득 차면 대화 요약(compaction)이 필요하다. 가장 쉬운 구현은 별도 요약용 시스템 프롬프트로 전체 대화를 다시 보내는 것이지만, 이 방식은 기존 캐시를 거의 활용하지 못한다. system prompt와 tool set이 첫 토큰부터 달라지기 때문이다.
캐시 친화적인 방식은 parent 세션과 같은 시스템 프롬프트, 사용자 컨텍스트, 도구 정의를 사용해 분기(fork)하고, parent 대화 뒤에 “요약하라”는 새 사용자 메시지만 붙이는 것이다. 그러면 API 관점에서는 parent의 마지막 요청과 거의 같은 prefix가 되며, 새로 과금되는 부분은 컴팩션 지시와 요약 출력에 가까워진다.
이 설계에는 컴팩션 버퍼가 필요하다. 요약 지시와 요약 결과가 들어갈 토큰 공간을 남겨 둔 채 컴팩션을 시작해야 한다.
운영 체크리스트
| 항목 | 권장 방식 |
|---|---|
| 정적 지침 | 시스템 프롬프트 앞쪽에 고정 |
| 프로젝트 규칙 | CLAUDE.md처럼 프로젝트 단위로 안정적으로 삽입 |
| 최신 상태 | 다음 메시지나 도구 결과로 전달 |
| 모델 선택 | 긴 세션 중간 전환 최소화 |
| 도구 목록 | 세션 중 추가·삭제 금지 |
| 대량 도구 | tool search와 지연 로딩 사용 |
| 컴팩션 | parent와 같은 prefix로 fork |
| 운영 지표 | 캐시 적중률을 비용·지연 시간 SLO처럼 모니터링 |
어디에 적용하면 좋은가
- 긴 코드베이스 컨텍스트를 반복 사용하는 코딩 에이전트
- 여러 MCP 도구를 장착한 업무 자동화 에이전트
- 대화가 수십~수백 턴 이어지는 고객지원·분석 에이전트
- 컴팩션, 요약, 서브에이전트 호출을 자주 수행하는 멀티 에이전트 시스템
핵심은 프롬프트 캐싱을 나중에 붙이는 최적화가 아니라, 하네스 구조를 결정하는 제약으로 보는 것이다. 정적 prefix를 안정적으로 유지하면 비용과 지연 시간이 내려가고, 캐시가 깨지는 작은 변경은 장기 세션에서 큰 비용 차이로 커진다.
참고 자료
- Lessons from building Claude Code: Prompt caching is everything — Claude Blog (2026-04-30)