Claude Code의 프롬프트 캐싱

기준일: 2026-07-26
공식 기준: How Claude Code uses prompt caching

개요

프롬프트 캐싱은 Claude Code를 더 빠르고 비용 효율적으로 만듭니다. 캐시 없이 API는 매 턴 전체 이력을 재처리합니다. 캐시가 있으면 이미 처리한 접두(prefix)를 재사용하고 변경분만 처리합니다.

Claude Code가 자동 관리합니다(비활성 가능). 일부 동작은 캐시를 무효화해 다음 응답이 느리고 비싸질 수 있습니다. 이 페이지는 그 동작, 일부 설정이 재시작 후에야 적용되는 이유, 사용량이 높아 보일 때 캐시 성능을 확인하는 방법을 다룹니다.

핵심 개념

레이어	내용	바뀔 때
System prompt	핵심 지시, 도구 정의, output style	로드된 도구 집합 변경 또는 Claude Code 업그레이드
Project context	CLAUDE.md, auto memory, unscoped rules	세션 시작, `/clear`, `/compact`
Conversation	메시지·응답·도구 결과	매 턴

캐시 키에 포함되지만 프롬프트 텍스트가 아닌 항목: 모델, effort level. 변경 시 전체 재계산.

상세

캐시 조직

매 메시지마다 새 API 요청. 모델은 요청 간 기억하지 않으므로 Claude Code가 system prompt·프로젝트 컨텍스트·이전 메시지·도구 결과·새 메시지를 다시 보냅니다. 새 내용은 끝에 붙어 대부분 이전 요청과 동일합니다.

API는 요청 시작(prefix)을 최근 처리 내용과 정확히 매칭합니다. prefix 어디든 바뀌면 그 이후 전부 재계산. 파일·세그먼트 단위 캐시 없음. API prompt caching.

Plan mode 지시·skill 로딩은 대화 메시지로 append되어 cached prefix를 유지합니다.

팁: 세션 초반에 모델·effort를 고르고, /compact는 작업 사이 자연스러운 휴식에. mid-task 변경이 적을수록 hit rate↑.

캐시 위치

API 키·구독·Claude Platform on AWS: Anthropic 인프라
Bedrock·Google Agent Platform: 클라우드 공급자 인프라
Microsoft Foundry: 배포 hosting option에 따름
커스텀 ANTHROPIC_BASE_URL·LLM gateway: 전달 대상. 게이트웨이 동작에 의존

mid-conversation 파일 변경 알림 등 system context append는 Bedrock/Mantle, Agent Platform, Foundry에서도 Claude API와 같이 캐시 대상. v2.1.211 이전 3P는 해당 append를 매 요청 uncached로 과금.

게이트웨이가 cache breakpoint를 거부하면 Claude Code가 그 블록 없이 재시도하고 나머지 대화 동안 해당 블록 uncached.

캐시를 무효화하는 동작

다음 요청이 일부·전체 미스 후 새 prefix 캐시. 대부분 mid-task에서 회피 가능.

모델 전환

/model 전환 시 동일 내용이어도 전체 이력 uncached. opusplan은 plan↔실행 시 Opus/Sonnet 전환 = 모델 스위치. Fable 5/Opus 5 automatic fallback도 모델 스위치.

Effort 변경

/effort도 캐시 키. 대화 시작 후 변경 시 확인 대화상자. 동일 레벨 명시 설정은 스킵·캐시 유지.

Fast mode 켜기

요청 헤더가 캐시 키. 다음 턴 전체 이력 uncached, uncached 토큰은 fast mode 요금. 세션 초반 켜는 편이 긴 대화 중간보다 저렴. non-Opus에서 켜면 모델 스위치도 동시. 비용은 대화당 1회; 이후 헤더 유지, speed 설정만 변경(캐시 키 아님). off·rate limit fallback·재활성은 캐시 유지. /clear·/compact는 리셋.

MCP 연결/해제

도구 정의는 system prompt 레이어. advisor 토글은 예외(breakpoint 뒤).

Deferred tools(지원 모델 기본): 연결·해제·목록 변경이 append만 → 기존 캐시 유지
Prefix 로드 도구: 변경 시 캐시 무효. tool search 불가/비활성(Agent Platform, 커스텀 BASE_URL), alwaysLoad, threshold 기반 선행 로드
stdio 종료·HTTP 세션 만료·자동 재연결·dynamic tool update로 mid-session 무효 가능. MCP config 편집만으로는 안 바뀌고 재시작 시 반영.

플러그인 enable/disable

skills/commands/agents/hooks/LSP/monitors/themes는 append → 캐시 유지. MCP 서버 제공 플러그인은 MCP 규칙 동일. 적용 시점: /reload-plugins 또는 새 세션. v2.1.163+ full re-read면 경고 후 미적용, --force로 강제. 세션 중 켠 플러그인 비활성은 이전 request shape 복원 → TTL 내면 구 캐시 hit.

도구 전체 deny

Bash/WebFetch 등 bare 도구명 deny는 도구를 컨텍스트에서 제거 → system prompt 변경 → 캐시 무효. Bash(*), tool-name glob "*" 동일. "mcp__*"는 deferred면 캐시 유지. Bash(rm *) 등 scoped deny·allow/ask는 도구 집합 불변.

Compaction

이력을 요약으로 교체 → conversation 레이어 무효. system prompt 재사용, project context는 디스크 재로드(시작 이후 CLAUDE.md 불변 시 hit). 요약 요청은 기존 prefix를 읽어 대부분 캐시 hit. 요약 생성 시간이 주요 비용. 불필요 경로 포기는 /rewind(이미 캐시된 prefix로 절단).

Claude Code 업그레이드

system prompt/도구 정의 변경 → 첫 요청 전체 재빌드. auto-update는 다음 launch에 적용(mid-session 아님). DISABLE_AUTOUPDATER=1. 업그레이드 후 resume은 전체 이력 uncached.

캐시를 유지하는 동작

저장소 파일 편집: 이전 Read 결과는 그대로, <system-reminder> append
세션 중 CLAUDE.md 편집: 캐시 무효 없음 그리고 적용도 안 됨. /clear//compact/재시작 시 로드. nested/path rules는 로드 전 편집은 반영
Output style 변경: system prompt 일부, 세션 시작 고정. mid-session 미적용
Permission mode: 캐시 안전. 단 opusplan+plan mode는 모델 스위치
Skills/commands: 호출 지점에 user message inject
/recap: 표시용 요약 append, 이력 교체 아님
/rewind: 이전 턴 prefix로 절단 → 그 캐시 hit
Subagent spawn: 부모 prefix 유지

캐시 수명 (TTL)

hit마다 타이머 리셋. 5분 TTL vs 1시간 TTL(write 요금 높음).

구독: 기본 1시간. usage credits 사용 시 5분으로 자동 하향
API 키·3P: 기본 5분. ENABLE_PROMPT_CACHING_1H=1로 1시간. Bedrock은 모델·리전별 지원 상이
강제 5분: FORCE_PROMPT_CACHING_5M=1

캐시 스코프

실질적으로 머신+디렉터리. system prompt에 cwd·플랫폼·셸·OS·auto-memory 경로. worktree도 별도. 같은 디렉터리 병렬 세션은 prefix 공유 가능. 순차 세션은 시작 시 git status 스냅샷이 같을 때만. API 캐시는 org(·workspace) 격리. Agent SDK 플릿 공유: modifying system prompts.

성능 확인

필드	의미
`cache_creation_input_tokens`	이번 턴 캐시 write
`cache_read_input_tokens`	캐시 hit (~표준 input 10% 과금)

statusline의 current_usage. read≫creation이 정상. creation이 매 턴 높으면 prefix 변경. OTel: Monitor usage.

서브에이전트와 캐시

자체 system prompt·도구로 자체 캐시. 첫 호출 uncached. 구독이어도 서브에이전트 TTL 5분. 부모 캐시 무영향. fork는 부모 prefix 상속 → 첫 요청 hit.

프롬프트 캐싱 끄기

변수	효과
`DISABLE_PROMPT_CACHING`	전 모델
`DISABLE_PROMPT_CACHING_HAIKU`	Haiku만
`DISABLE_PROMPT_CACHING_SONNET`	Sonnet만
`DISABLE_PROMPT_CACHING_OPUS`	Opus만
`DISABLE_PROMPT_CACHING_FABLE`	Fable만

조직: managed settings env. 일반 사용은 켠 상태 유지.

체크리스트

세션 초반에 모델·effort·fast mode를 고정했다
mid-task /compact·모델 전환·MCP prefix 로드 변경을 최소화했다
CLAUDE.md/output style mid-session 편집이 즉시 안 먹히는 이유를 이해했다
cache_read vs cache_creation 비율을 확인했다
디버그 시에만 DISABLE_* / TTL 오버라이드를 쓴다

다음 단계

기준일

문서 작성·동기화 기준일: 2026-07-26
원문: https://code.claude.com/docs/en/prompt-caching

Claude Code의 프롬프트 캐싱

기준일: 2026-07-26
공식 기준: How Claude Code uses prompt caching

개요

핵심 개념

레이어	내용	바뀔 때
System prompt	핵심 지시, 도구 정의, output style	로드된 도구 집합 변경 또는 Claude Code 업그레이드
Project context	CLAUDE.md, auto memory, unscoped rules	세션 시작, `/clear`, `/compact`
Conversation	메시지·응답·도구 결과	매 턴

캐시 키에 포함되지만 프롬프트 텍스트가 아닌 항목: 모델, effort level. 변경 시 전체 재계산.

상세

캐시 조직

Plan mode 지시·skill 로딩은 대화 메시지로 append되어 cached prefix를 유지합니다.

팁: 세션 초반에 모델·effort를 고르고, /compact는 작업 사이 자연스러운 휴식에. mid-task 변경이 적을수록 hit rate↑.

캐시 위치

API 키·구독·Claude Platform on AWS: Anthropic 인프라
Bedrock·Google Agent Platform: 클라우드 공급자 인프라
Microsoft Foundry: 배포 hosting option에 따름
커스텀 ANTHROPIC_BASE_URL·LLM gateway: 전달 대상. 게이트웨이 동작에 의존

게이트웨이가 cache breakpoint를 거부하면 Claude Code가 그 블록 없이 재시도하고 나머지 대화 동안 해당 블록 uncached.

캐시를 무효화하는 동작

다음 요청이 일부·전체 미스 후 새 prefix 캐시. 대부분 mid-task에서 회피 가능.

모델 전환

/model 전환 시 동일 내용이어도 전체 이력 uncached. opusplan은 plan↔실행 시 Opus/Sonnet 전환 = 모델 스위치. Fable 5/Opus 5 automatic fallback도 모델 스위치.

Effort 변경

/effort도 캐시 키. 대화 시작 후 변경 시 확인 대화상자. 동일 레벨 명시 설정은 스킵·캐시 유지.

Fast mode 켜기

MCP 연결/해제

도구 정의는 system prompt 레이어. advisor 토글은 예외(breakpoint 뒤).

Deferred tools(지원 모델 기본): 연결·해제·목록 변경이 append만 → 기존 캐시 유지
Prefix 로드 도구: 변경 시 캐시 무효. tool search 불가/비활성(Agent Platform, 커스텀 BASE_URL), alwaysLoad, threshold 기반 선행 로드
stdio 종료·HTTP 세션 만료·자동 재연결·dynamic tool update로 mid-session 무효 가능. MCP config 편집만으로는 안 바뀌고 재시작 시 반영.

플러그인 enable/disable

도구 전체 deny

Compaction

Claude Code 업그레이드

캐시를 유지하는 동작

저장소 파일 편집: 이전 Read 결과는 그대로, <system-reminder> append
세션 중 CLAUDE.md 편집: 캐시 무효 없음 그리고 적용도 안 됨. /clear//compact/재시작 시 로드. nested/path rules는 로드 전 편집은 반영
Output style 변경: system prompt 일부, 세션 시작 고정. mid-session 미적용
Permission mode: 캐시 안전. 단 opusplan+plan mode는 모델 스위치
Skills/commands: 호출 지점에 user message inject
/recap: 표시용 요약 append, 이력 교체 아님
/rewind: 이전 턴 prefix로 절단 → 그 캐시 hit
Subagent spawn: 부모 prefix 유지

캐시 수명 (TTL)

hit마다 타이머 리셋. 5분 TTL vs 1시간 TTL(write 요금 높음).

구독: 기본 1시간. usage credits 사용 시 5분으로 자동 하향
API 키·3P: 기본 5분. ENABLE_PROMPT_CACHING_1H=1로 1시간. Bedrock은 모델·리전별 지원 상이
강제 5분: FORCE_PROMPT_CACHING_5M=1

캐시 스코프

성능 확인

필드	의미
`cache_creation_input_tokens`	이번 턴 캐시 write
`cache_read_input_tokens`	캐시 hit (~표준 input 10% 과금)

statusline의 current_usage. read≫creation이 정상. creation이 매 턴 높으면 prefix 변경. OTel: Monitor usage.

서브에이전트와 캐시

자체 system prompt·도구로 자체 캐시. 첫 호출 uncached. 구독이어도 서브에이전트 TTL 5분. 부모 캐시 무영향. fork는 부모 prefix 상속 → 첫 요청 hit.

프롬프트 캐싱 끄기

변수	효과
`DISABLE_PROMPT_CACHING`	전 모델
`DISABLE_PROMPT_CACHING_HAIKU`	Haiku만
`DISABLE_PROMPT_CACHING_SONNET`	Sonnet만
`DISABLE_PROMPT_CACHING_OPUS`	Opus만
`DISABLE_PROMPT_CACHING_FABLE`	Fable만

조직: managed settings env. 일반 사용은 켠 상태 유지.

체크리스트

세션 초반에 모델·effort·fast mode를 고정했다
mid-task /compact·모델 전환·MCP prefix 로드 변경을 최소화했다
CLAUDE.md/output style mid-session 편집이 즉시 안 먹히는 이유를 이해했다
cache_read vs cache_creation 비율을 확인했다
디버그 시에만 DISABLE_* / TTL 오버라이드를 쓴다

다음 단계

기준일

문서 작성·동기화 기준일: 2026-07-26
원문: https://code.claude.com/docs/en/prompt-caching

Claude Code의 프롬프트 캐싱

개요

핵심 개념

상세

캐시 조직

캐시 위치

캐시를 무효화하는 동작

모델 전환

Effort 변경

Fast mode 켜기

MCP 연결/해제

플러그인 enable/disable

도구 전체 deny

Compaction

Claude Code 업그레이드

캐시를 유지하는 동작

캐시 수명 (TTL)

캐시 스코프

성능 확인

서브에이전트와 캐시

프롬프트 캐싱 끄기

체크리스트

다음 단계

기준일

관련 가이드

Claude Code의 프롬프트 캐싱

개요

핵심 개념

상세

캐시 조직

캐시 위치

캐시를 무효화하는 동작

모델 전환

Effort 변경

Fast mode 켜기

MCP 연결/해제

플러그인 enable/disable

도구 전체 deny

Compaction

Claude Code 업그레이드

캐시를 유지하는 동작

캐시 수명 (TTL)

캐시 스코프

성능 확인

서브에이전트와 캐시

프롬프트 캐싱 끄기

체크리스트

다음 단계

기준일

관련 가이드