한 줄 요약: Claude Code 공식 문서 "How Claude Code uses prompt caching". Claude Code는 매 턴 전체 맥락을 다시 보내고, API는 요청 앞부분(prefix)이 직전 요청과 글자 그대로 같으면 그 부분을 캐시에서 읽는다. 그래서 시스템 프롬프트·프로젝트 맥락·대화 순으로 층을 쌓고, 모델 바꾸기·effort 바꾸기·MCP 서버 연결·도구 전체 deny·컴팩션 같은 행동은 캐시를 깨 다음 한 턴을 느리고 비싸게 만든다. 반대로 파일 편집, 세션 중 CLAUDE.md 편집, 권한 모드·출력 스타일 바꾸기, 스킬 호출, /rewind는 캐시를 지킨다. 캐시 수명(TTL)은 5분과 1시간 두 가지이고, /usage로 적중률을 본다.
원본 정보#
- 제목: How Claude Code uses prompt caching
- 발행처: Claude Code 공식 문서(code.claude.com)
- 원본 날짜: 문서에 표기 없음. 서버 Last-Modified 2026-10-26, 수집 2026-10-26. 이 페이지의 버전·설정 사실은 2026-10-26 기준이다.
- URL: https://code.claude.com/docs/en/prompt-caching (새 창)
핵심 주장#
- 캐시는 요청 앞부분이 글자 그대로 같을 때만 쓰인다. 매 메시지마다 Claude Code는 시스템 프롬프트, 프로젝트 맥락, 이전 메시지와 도구 결과 전부, 새 메시지를 다시 보낸다. API는 요청의 시작 부분(prefix)을 최근 처리한 내용과 맞춰 보고, 일치는 정확해야 해서 앞부분 어디가 바뀌든 그 뒤 전부를 다시 계산한다. 파일별·구간별 캐시는 없다. → 프롬프트 캐싱
- 세 층으로 쌓는다. 시스템 프롬프트(핵심 지시, 도구 정의: 로드된 도구 정의 집합이 바뀔 때 변함), 프로젝트 맥락(CLAUDE.md, 자동 메모리, 범위 없는 rules: 세션 시작,
/clear·/compact뒤 변함), 대화(매 턴 변함). 대화 층이 바뀌어도 위 두 층은 캐시에 남지만, 시스템 프롬프트가 바뀌면 전부 무효가 된다. 모델과 effort 수준은 표에 없지만 캐시를 가른다. → 프롬프트 캐싱, 컨텍스트 비용 - 캐시를 깨는 행동 9가지. 모델 바꾸기, effort 바꾸기(대부분 모델), fast mode 켜기, MCP 서버 연결·제거(도구 검색이 꺼졌을 때), 플러그인 켜기·끄기(MCP 서버를 주는 경우), 도구 전체 deny(도구 검색이 꺼졌을 때), 컴팩션, 이미지 누적, Claude Code 업그레이드. 깨지면 한 번 느리고 비싼 턴이 생기고 그 뒤 새 prefix가 캐시된다. → 프롬프트 캐싱
- 캐시를 지키는 행동. 저장소 파일 편집, 세션 중 CLAUDE.md 편집(대신 다음
/clear·/compact·재시작 전까지 반영되지 않음), 권한 모드 바꾸기(opusplan예외), 출력 스타일 바꾸기(새 스타일 지시를 대화 메시지로 전달, v2.1.251 이전에는/clear나 새 세션 전까지 적용 안 됨), 스킬·명령 호출,/recap,/rewind, 서브에이전트 띄우기. → 메모리(CLAUDE.md), 출력 스타일 - 재개와
--append-system-prompt. 재개하면 대화 전체를 다시 보내고 바뀌지 않았고 수명 안에 있는 prefix를 캐시에서 읽는다. 업그레이드 뒤나 재개 때 다른--append-system-prompt텍스트를 주면 시스템 프롬프트가 바뀌지만, 기본으로 재개한 대화는 시작할 때의 시스템 프롬프트를 유지하고 변화는 컴팩션 때나 새 대화에서 반영된다. → Claude Code CLI 플래그 - 캐시 수명(TTL)은 5분과 1시간. 메인 대화는 Claude 구독의 플랜 포함 사용량 안에서 1시간, 사용량 크레딧·API 키·클라우드 제공자는 5분이 기본이다. 서브에이전트·워크플로·컴팩션 같은 나머지 요청은 기본 5분(서버가 정하는 일부 보조 요청만 1시간).
promptCacheTtl·subagentPromptCacheTtl설정이나 환경 변수로5m·1h를 고른다(v2.1.242 이상). → 프롬프트 캐싱 - 확인 방법.
/usage의Prompt cache (main)줄이 세션 적중률·미스 수·지금 캐시가 따뜻한지를 보여 주고(v2.1.251 이상), 마지막 미스의 원인을 짐작할 수 있으면likely cause: tool definitions changed처럼 적는다(v2.1.260 이상). 상태 줄 스크립트는cache_creation_input_tokens·cache_read_input_tokens를 읽는다. → 프롬프트 캐싱
다른 원본과의 관계#
- Steering Claude Code(2026-06-18)는 시스템 프롬프트 덧붙이기가 "세션 첫 요청 뒤 캐시된다"고 했다. 이 원본은
--append-system-prompt텍스트가 바뀌는 것을 시스템 프롬프트 변경으로 다루고, 시스템 프롬프트 층은 바뀌지 않으면 다음 요청에서 캐시로 읽힌다고 적는다(27~33행. 표의 "바뀌는 때"는 흔한 예일 뿐 전부가 아니라고 33행이 밝힌다). 두 문장을 함께 읽으면 덧붙인 텍스트도 캐시되는 시스템 프롬프트 층에 들어간다. "덧붙이기가 캐시된다"를 한 문장으로 쓴 곳은 없다. - Claude Code 출력 스타일은 스타일을 세션 중 바꾸면 다음 메시지부터 적용된다고 하고 첫 메시지의 캐싱 비용을 이 문서로 넘겼다. 이 원본은 새 스타일 지시를 대화 메시지로 전달해 캐시가 유지된다고 답한다.
- Claude Code CLI 레퍼런스의 재개 동작(첫 요청에서 만든 시스템 프롬프트를 기록해 컴팩션 전까지 쓴다)과 같은 방향이다.
- Claude Code 서브에이전트의 "포크는 부모의 프롬프트 캐시를 재사용한다"를 이 원본도 확인하고, 일반 서브에이전트는 자기 캐시를 따로 데우며 구독에서도 기본 5분 TTL이라고 더한다.
원본에 없는 것#
- 캐시 읽기·쓰기 요금 숫자. 원본은 API 요금 문서로 넘긴다.
- 이미지·PDF 개수 한도 숫자. 원본은 API Vision 문서로 넘긴다.
원본이 링크만 한 것#
API 문서 Prompt caching(메커니즘·breakpoint·요금), Model configuration(effort, opusplan, 자동 모델 대체), Fast mode, MCP tool search, Plugins(/reload-plugins), Costs(/usage 캐시 통계), Statusline, Monitoring usage(OpenTelemetry), Workflows(fan-out 캐싱), Agent SDK(시스템 프롬프트 수정, 비용 추적), LLM gateway, 블로그 "Lessons from building Claude Code: Prompt caching is everything".