프롬프트 캐싱

이 페이지의 목차

확인 2026-10-26근거 자료 4건갱신 2026-10-26언급 13곳

이 페이지의 목차

확인 날짜 안내

이 페이지는 Claude Code 공식 Prompt caching 문서(원본 날짜 미상, 서버 Last-Modified 2026-10-26, 수집 2026-10-26) 기준이다. 버전 조건(v2.1.xxx)과 모델 이름은 빨리 바뀌니 90일이 지나면 다시 확인한다. 낯선 말은 용어 사전에서 찾는다.

어떻게 작동하나#

모델은 요청 사이에 아무것도 기억하지 않는다. 그래서 Claude Code는 매 메시지마다 시스템 프롬프트, 프로젝트 맥락, 이전 메시지와 도구 결과 전부, 새 메시지를 다시 보낸다. 새 내용은 끝에 붙으므로 요청의 대부분은 직전과 같다. Claude Code 프롬프트 캐싱
API는 요청의 시작 부분(prefix, 접두부)을 최근 처리한 내용과 맞춰 본다. 일치는 정확해야 해서, 앞부분 어디가 바뀌든 그 뒤 전부를 다시 계산한다. 파일별·구간별 캐시는 없다. 캐시에서 읽은 부분은 캐시 토큰 요율로 청구된다(요율 숫자는 원본이 API 요금 문서로 넘긴다). Claude Code 프롬프트 캐싱
Claude Code는 잘 안 바뀌는 것을 앞에 둔다:

층	내용	바뀌는 때
시스템 프롬프트	핵심 지시, 도구 정의	로드된 도구 정의 집합이 바뀔 때
프로젝트 맥락	CLAUDE.md, 자동 메모리, 범위 없는 rules	세션 시작, `/clear`·`/compact` 뒤
대화	내 메시지, Claude 응답, 도구 결과	매 턴

대화 층이 바뀌어도 위 두 층은 캐시에 남지만, 시스템 프롬프트가 바뀌면 그 뒤가 모두 무효가 된다. 표의 "바뀌는 때"는 흔한 예이고 전부는 아니다. 표에 없지만 캐시를 가르는 것이 둘 더 있다: 모델(모델마다 캐시가 따로)과 effort 수준(대부분 모델에서 수준마다 캐시가 따로). Claude Code 프롬프트 캐싱

캐시가 사는 곳은 인증 방식에 따라 다르다. API 키·Claude 구독·Claude Platform on AWS는 Anthropic 인프라, Amazon Bedrock·Google Cloud's Agent Platform은 그 클라우드, 직접 정한 ANTHROPIC_BASE_URL이나 LLM 게이트웨이를 거치면 게이트웨이가 캐시 표시를 어떻게 다루느냐에 달렸다(표시를 지우고 성공을 돌려주는 게이트웨이면 매 턴 대화 전체가 캐시 없이 청구된다). Claude Code 프롬프트 캐싱
캐시 범위: Claude Code에서는 사실상 기기 하나·디렉터리 하나 단위다. 다른 디렉터리의 두 세션은 서로의 캐시를 못 쓰고, 같은 디렉터리에서 동시에 돌리는 세션은 쓸 수 있다. 차례로 연 세션은 시작 때 찍은 git status 스냅샷이 같을 때만 앞부분을 공유한다. Claude Code 프롬프트 캐싱

캐시를 깨는 행동 (2026-10-26 기준)#

깨지면 다음 요청이 캐시 일부나 전부를 놓쳐 한 번 느리고 비싼 턴이 생기고, 그 뒤에는 새 앞부분이 캐시된다. Claude Code 프롬프트 캐싱

행동	무엇이 일어나나	조건·예외
모델 바꾸기(`/model`)	다음 요청이 대화 전체를 캐시 없이 읽는다	캐시가 따뜻하고 새 모델이 마지막 응답을 만든 모델이 아니면 확인을 묻는다(v2.1.238 이전에는 만료 뒤에도 물었다). `opusplan`은 plan 모드를 켜고 끌 때마다 모델이 바뀐다. 스킬·명령의 frontmatter가 다른 `model`을 지정하면 그 턴도 모델 전환이다
effort 수준 바꾸기	대부분 모델에서 다음 요청이 전체를 캐시 없이 읽는다	대부분 모델에서는 캐시가 따뜻할 때 먼저 확인을 묻는다. Opus 5.5·Sonnet 5.5·Haiku 5.5·Fable 5.1을 API 키나 Claude 구독으로 쓰면 기본으로 캐시가 유지된다(Fable 5.1은 v2.1.260 이상). 단 Amazon Bedrock, Google Cloud's Agent Platform, Claude apps gateway, `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 설정, 조직의 HIPAA 구성에서는 해당하지 않는다
fast mode 켜기	표준 속도와 캐시가 따로라 처음 켤 때 지금까지 대화를 캐시 없이 fast mode 요율로 읽는다	원본은 세션 시작 때 켜라고 권한다
MCP 서버 연결·제거	도구 정의가 바뀌어 캐시가 깨질 수 있다	지원 모델의 기본인 도구 검색(tool search)이 켜져 있으면 첫 요청의 도구 목록을 대화 내내 유지해 깨지지 않는다. 도구 검색이 꺼졌거나 쓸 수 없을 때만 깨진다. MCP 설정 파일을 고치는 것만으로는 바뀌지 않고 재시작 뒤 적용된다
플러그인 켜기·끄기	플러그인의 스킬·명령·에이전트·훅·모니터·테마는 캐시를 깨지 않는다	MCP 서버를 주는 플러그인은 위 MCP 규칙을 따른다. 전체 재읽기가 필요한 `/reload-plugins`는 경고를 띄우고 멈추며, `--force`로 강제한다
도구 전체 deny(`Bash`, `WebFetch` 같은 맨 도구 이름)	도구 검색이 꺼져 있으면 정의가 빠져 캐시가 깨진다	도구 검색이 켜져 있으면 캐시는 유지된다. 어느 쪽이든 다음 요청부터 그 도구는 부를 수 없다(캐시 유지는 차단이 늦게 먹는다는 뜻이 아니다). `Bash(rm *)` 같은 범위 지정 deny와 allow·ask 규칙은 Claude가 보는 도구를 바꾸지 않아 캐시를 지킨다
컴팩션(`/compact`)	설계상 대화 층을 새 요약으로 바꾼다	시스템 프롬프트 층은 보통 캐시에서 읽고, 프로젝트 맥락 층은 세션 시작 뒤 CLAUDE.md·메모리가 바뀌지 않았을 때만 캐시에서 읽는다
이미지·PDF 누적	한도를 넘기면 오래된 이미지 묶음을 빼고, 그 메시지부터 다시 처리한다	묶음 단위로 빼므로 스크린샷마다가 아니라 묶음마다 한 번 느려진다. 뺀 이미지는 Claude가 더는 못 보니 필요하면 다시 공유한다
Claude Code 업그레이드	새 버전은 보통 시스템 프롬프트·도구 정의를 바꿔 업그레이드 뒤 첫 대화는 처음부터 캐시를 만든다	자동 업데이트는 다음 실행 때 적용되고 세션 중에는 적용되지 않는다. `DISABLE_AUTOUPDATER=1`로 적용 시점을 직접 정한다

근거: Claude Code 프롬프트 캐싱

캐시를 지키는 행동 (2026-10-26 기준)#

대화 끝에 붙이거나 요청을 건드리지 않는 행동이다. Claude Code 프롬프트 캐싱

저장소 파일 편집: 파일 내용은 Claude가 읽을 때만 대화에 들어간다. 이미 읽은 파일을 고쳐도 예전 읽기 기록은 그대로이고, Claude Code가 파일이 바뀌었다는 알림(<system-reminder>)을 끝에 붙인다.
세션 중 CLAUDE.md 편집: 프로젝트 루트와 사용자 수준 CLAUDE.md는 세션 시작 때 한 번 읽어 둔다. 세션 중에 고쳐도 캐시는 깨지지 않지만, 고친 내용도 적용되지 않는다. 다음 /clear, /compact, 재시작 때 새 내용이 들어간다. 하위 디렉터리 CLAUDE.md와 paths: rules는 나중에 필요할 때 로드되므로, 로드되기 전에 고치면 반영된다. → 메모리(CLAUDE.md), CLAUDE.md 문제 해결
권한 모드 바꾸기: 시스템 프롬프트·도구 정의를 바꾸지 않아 안전하다. 예외는 opusplan 모델 설정에서 plan 모드를 드나드는 경우(모델 전환). → 권한 모드
출력 스타일 바꾸기: /output-style, /config, outputStyle 설정으로 세션 중 바꾸면 다음 메시지부터 새 스타일을 쓰고, 새 스타일 지시는 대화 메시지로 전달돼 앞부분 캐시가 유지된다. v2.1.251 이전에는 캐시는 지켰지만 /clear나 새 세션 전까지 적용되지 않았다. → 출력 스타일
스킬·명령 호출: 지시를 호출 시점의 사용자 메시지로 넣는다. 단 frontmatter에 model을 지정한 스킬·명령은 그 턴이 모델 전환이 될 수 있다. → 스킬
/recap: 요약을 명령 출력으로 붙인다. /compact처럼 기록을 바꾸지 않는다.
/rewind: 대화를 앞 턴으로 잘라 이미 캐시된 앞부분으로 돌아간다. 파일 체크포인트 복원은 캐시에 따로 영향이 없다. → Claude Code 세션·체크포인트 다루기
서브에이전트 띄우기: 부모 쪽에서는 호출과 결과가 대화 끝에 붙어 부모 캐시가 그대로다(아래 "서브에이전트와 캐시").

재개, 컴팩션, 시스템 프롬프트 덧붙이기#

세션을 재개하면 대화 전체를 다시 보내고, 바뀌지 않았고 수명 안에 있는 앞부분은 캐시에서 읽는다. Claude Code 프롬프트 캐싱
업그레이드 뒤나, 재개하면서 --append-system-prompt(시작할 때 바탕 지시에 문장을 덧붙이는 옵션)에 다른 텍스트를 주면 시스템 프롬프트가 바뀐다. 기본으로 재개한 대화는 시작할 때의 시스템 프롬프트를 유지하고, 변화는 컴팩션 때나 새 대화에서 반영된다. 매 요청 다시 만드는 예외는 Claude Code CLI 플래그. Claude Code 프롬프트 캐싱 Claude Code CLI 레퍼런스
덧붙인 텍스트는 시스템 프롬프트 층에 들어가므로(원본이 덧붙이기 텍스트 변경을 시스템 프롬프트 변경으로 다룸), 바뀌지 않는 한 다음 요청부터 그 층과 함께 캐시에서 읽힌다. Claude Code 프롬프트 캐싱
/compact의 비용: 요약을 만드는 별도 요청이 시스템 프롬프트·도구·요약할 기록을 다시 보내는데, 캐시가 따뜻하면 앞부분을 캐시에서 읽어 컨텍스트 크기에 비해 적은 비용이 든다. 캐시 수명보다 오래 쉬었다가 하면 기록 전체를 캐시 없이 다시 처리하므로, 오래된 세션을 재개해 /compact할 때 가장 비싸다. 버리고 싶은 길로 갔다면 /compact 대신 /rewind가 이미 캐시된 앞부분으로 돌아간다. Claude Code 프롬프트 캐싱 → 장기 작업 컨텍스트 관리

캐시 수명(TTL)#

캐시는 쓰지 않으면 일정 시간 뒤 만료되고, 캐시를 읽는 요청마다 타이머가 다시 시작된다. API는 5분과 1시간 두 가지를 준다. 1시간은 오래 쉬었다 돌아와도 캐시가 남지만 캐시 쓰기 요율이 더 높아, 5분 넘게 쉬지 않는 짧은 작업에서는 오히려 비싸다. Claude Code 프롬프트 캐싱

요청 묶음	Claude 구독, 플랜 사용량 안	사용량 크레딧, API 키, 클라우드 제공자
메인 대화(대화형 턴, `-p` 실행, Agent SDK 턴)	1시간	5분
나머지(서브에이전트, 워크플로, 팀원, 포크, 컴팩션, 세션 제목 등)	5분. 서버가 정하는 일부 보조 요청만 1시간	5분

구독 사용량 한도를 넘어 사용량 크레딧을 쓰기 시작하면 메인 대화도 5분으로 내려간다. Claude Code 프롬프트 캐싱
직접 고르기(v2.1.242 이상, 값은 5m·1h만, 다른 값은 무시): 메인 대화는 promptCacheTtl 설정이나 CLAUDE_CODE_PROMPT_CACHE_TTL, 나머지는 subagentPromptCacheTtl 설정이나 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL. API 키나 클라우드 제공자로 쓰면서 메인 대화를 1시간으로 하려면 promptCacheTtl을 1h로 둔다. Claude Code 프롬프트 캐싱 → Claude Code 설정 키 레퍼런스
여러 값이 겹치면 이 순서로 처음 맞는 것을 쓴다: FORCE_PROMPT_CACHING_5M=1(두 묶음 모두 5분) → 묶음의 환경 변수 → 묶음의 설정 → 서브에이전트 정의의 experimental.cacheTtl(v2.1.248 이상, 구독이 크레딧을 쓰는 동안 1h는 무시) → ENABLE_PROMPT_CACHING_1H=1 → 묶음 기본값. Claude Code 프롬프트 캐싱 → 서브에이전트 정의 파일 레퍼런스
대화형 터미널에서 1시간 TTL로 쉬고 있는 긴 대화는 Claude Code가 컴팩션할 수 있다. 끄려면 idleCompaction을 false로 둔다(v2.1.290 이상). Claude Code 프롬프트 캐싱

서브에이전트와 캐시#

서브에이전트는 자기 시스템 프롬프트와 도구로 새 대화를 시작해, 첫 요청이 부모 캐시를 읽지 못하고 자기 캐시를 따로 데운다. 메인 대화 묶음 밖이라 구독에서도 직접 고르기 전까지 5분 TTL이다. 부모 캐시는 영향을 받지 않는다. Claude Code 프롬프트 캐싱
포크는 부모의 시스템 프롬프트·도구·대화 기록을 그대로 물려받아 첫 요청이 부모 캐시를 읽는다. Claude Code 프롬프트 캐싱 Claude Code 서브에이전트 → 서브에이전트
재개한 서브에이전트, 같은 앞부분의 워크플로 fan-out(기본으로 첫 에이전트 말고는 최대 5초 기다렸다 출발), /fork로 복사한 세션, 컴팩션 요약 요청도 앞서 캐시된 앞부분을 읽을 수 있다. Claude Code 프롬프트 캐싱

따라 하기: 캐시가 잘 되는지 확인하기#

준비물: Claude Code v2.1.251 이상(원인 표시는 v2.1.260 이상). Claude Code 프롬프트 캐싱

세션에서 /usage를 입력한다. 메인 대화의 첫 응답 뒤 Session 블록에 Prompt cache (main) 줄이 생기고, 세션 적중률, 미스 수, 지금 캐시가 따뜻한지가 보인다.
마지막 미스의 원인을 짐작할 수 있으면 같은 줄에 likely cause: tool definitions changed 같은 문구가 붙는다.
메인 대화의 캐시 쓰기가 어느 TTL이었는지 보려면 claude -p "hello" --output-format json을 돌려 결과의 usage.cache_creation을 본다. 1시간 쓰기는 ephemeral_1h_input_tokens, 5분 쓰기는 ephemeral_5m_input_tokens에 잡힌다.

됐는지 확인하는 법: 원본 기준으로, 캐시 읽기(cache_read_input_tokens) 대 캐시 쓰기(cache_creation_input_tokens)의 비율이 높으면 캐싱이 잘 되는 것이다. 쓰기가 턴마다 계속 높으면 앞부분에서 무언가 계속 바뀌는 것이니 위 "캐시를 깨는 행동" 표를 본다. 실시간으로 보려면 상태 줄(statusline) 스크립트가 current_usage나 prompt_cache 객체를 읽게 한다. 조직 단위로는 OpenTelemetry 내보내기가 사용자·세션별 캐시 토큰을 보고한다. Claude Code 프롬프트 캐싱

습관 두 가지(원본 권고): 모델과 effort는 세션 맨 처음에 고르고, /compact는 자동 컴팩션을 기다리지 말고 작업 사이 쉬는 지점에서 돌린다. 작업 도중 바꾸는 것이 적을수록 적중률이 높다. Claude Code 프롬프트 캐싱

캐싱 끄기#

캐싱 동작을 디버깅할 때만 쓰라고 하고, 평소에는 켜 두라고 한다. DISABLE_PROMPT_CACHING=1은 모든 모델, DISABLE_PROMPT_CACHING_HAIKU·_SONNET·_OPUS는 각 별칭이 가리키는 기본 모델, DISABLE_PROMPT_CACHING_FABLE은 Fable만 끈다. 별칭이 가리키지 않는 다른 버전을 메인 모델로 고정했다면 그 모델은 계속 캐시하므로 DISABLE_PROMPT_CACHING을 쓴다. 조직 전체 정책은 managed settings의 env 블록에 이 변수나 TTL 변수를 둔다. Claude Code 프롬프트 캐싱 → managed settings