🔥 Claude Code 2.1.108이 조용히 꽂아둔 캐시 플래그, 왜 지금 필요해졌나

#Claude Code#Anthropic#프롬프트 캐싱#CHANGELOG#환경변수

1216자

15분

강의 목차

2.1.108이 추가한 네 가지
왜 TTL이 그렇게 중요한가
3월의 조용한 회귀
ENABLE_PROMPT_CACHING_1H 실제 동작
DISABLE_TELEMETRY가 TTL을 잡아먹던 버그
DISABLE_PROMPT_CACHING 경고
recap — 돌아왔을 때를 위한 장치
그 이전 버전들에서 이어진 패턴
내가 바꿀 workflow
참고 자료

Claude Code 2.1.108 프롬프트 캐시 TTL 비교 — 5분 vs 1시간

어젯밤에 claude 커맨드를 업데이트하고 습관처럼 CHANGELOG를 열어봤는데, 2.1.108 섹션에서 눈이 잠깐 멈췄다. 캐시 관련 항목이 한 줄짜리 버그픽스가 아니라 네 개나 몰려 있었다. 새 환경변수 하나, 경고 로그 하나, 버그 픽스 하나, 그리고 recap이라는 생소한 기능. 한 버전에서 이렇게 캐시를 만지작거리는 건 흔한 일이 아니다.

뭐가 바뀌었는지, 그리고 왜 하필 지금 바뀌어야 했는지 정리해 두고 싶었다. 최근 두 달 사이 Anthropic은 프롬프트 캐싱 쪽에서 꽤 시끄러운 일을 겪었다. 이번 릴리스의 플래그 몇 개는 그 사건들에 대한 뒤늦은 조치처럼 보인다.

2.1.108이 추가한 네 가지

공식 CHANGELOG에서 2.1.108의 캐시/세션 관련 항목만 추려보면 이렇다.

ENABLE_PROMPT_CACHING_1H 환경변수 추가 — 1시간짜리 prompt cache TTL에 옵트인
DISABLE_PROMPT_CACHING* 설정 시 시작 시점에 경고 노출
DISABLE_TELEMETRY를 켠 구독자가 5분 TTL로 폴백되던 문제 수정
세션 복귀 시 맥락을 알려주는 recap 기능 도입

각각이 독립적으로 보이지만, 실은 전부 "캐시가 엉뚱하게 풀려서 비용이 튀는" 이야기의 다른 얼굴이다.

왜 TTL이 그렇게 중요한가

Anthropic 공식 문서에 따르면 prompt cache는 기본적으로 5분 TTL을 가진다. 5분 동안 같은 프롬프트 prefix로 들어온 요청은 이미 기억된 KV를 재사용해서 input 비용의 10분의 1 값(0.1×)만 내고 지나간다. 대신 캐시에 적재할 때는 1.25배를 낸다.

1시간 TTL은 별도 옵트인 옵션이다. 캐시 write는 2×로 비싸지지만, 읽기는 여전히 0.1×. 계산이 단순하다. 한 시간짜리 작업 세션에서 캐시가 2~3번 이상 재활용된다면 1시간 TTL이 무조건 이득이다. 반대로 5분 안에 세션이 끝나면 5분 TTL이 싸다.

Claude Code처럼 평균 세션이 수십 분에서 몇 시간 단위로 늘어지는 도구에서는 5분 TTL이 의외로 잘 안 맞는다. 파일 하나 읽고, 생각하고, 테스트 돌리고, 다시 수정하다 보면 5분은 금방 지나간다. 그 사이에 TTL이 만료되면 수십만 토큰짜리 CLAUDE.md와 파일 맥락이 다시 캐시에 적재된다. 그게 바로 2× 과금 구간이다.

3월의 조용한 회귀

여기서 배경을 좀 짚고 가야 한다. 2026년 3월 6일경, Anthropic이 공지 없이 prompt cache TTL을 1시간에서 5분으로 되돌린 사건이 있었다. 사용자들은 갑자기 쿼터가 빨리 닳고 Bedrock/Vertex 청구서가 튀는 걸 보고서야 뭔가 잘못됐다는 걸 알아차렸다.

byteiota가 공개한 분석에 따르면 십수만 건 규모의 API 호출을 비교한 결과 비용이 17~32% 증가한 것으로 측정됐다. 한 회사는 며칠 만에 수천 달러가 더 빠져나간 사실을 확인했다고 한다. GitHub issue #46829에 쌓인 재현 사례들을 보면 모든 주요 플랫폼(Bedrock, Vertex, Foundry)에서 같은 증상이 나타났다.

이 사건 이후 Anthropic이 어떤 형태로든 명시적 제어권을 사용자에게 돌려주리라는 건 예상 가능한 수순이었다. 4월 중순에 등장한 ENABLE_PROMPT_CACHING_1H는 그 답안지에 가깝다.

ENABLE_PROMPT_CACHING_1H 실제 동작

이 환경변수는 API 키, Bedrock, Vertex, Foundry 전 프로바이더에서 동작하도록 설계됐다. 사용법도 딱히 복잡하지 않다.

bash

export ENABLE_PROMPT_CACHING_1H=1
claude

bash

export ENABLE_PROMPT_CACHING_1H=1
claude

Claude Code가 요청을 만들 때 cache_control의 ttl 필드를 "1h"로 붙여서 보낸다. AWS가 설명한 것처럼 Bedrock에서는 기존에 TTL이 5분으로 하드코딩돼서 #32671 이슈로 오래 민원이 쌓여있었는데, 이번 플래그가 그걸 정리했다.

눈에 띄는 건 이름이 ENABLE_PROMPT_CACHING_1H_BEDROCK이 아니라 그냥 _1H라는 점이다. 이전의 Bedrock 전용 플래그는 deprecated 상태로 남아 호환성만 유지된다. 프로바이더별로 분리된 플래그를 한 깃대 아래로 묶었다는 뜻이고, 그건 내부적으로 캐시 제어 로직이 통합됐다는 신호이기도 하다.

단순 비율로 따져봐도 차이가 확연하다. 5분 TTL은 write 1.25×, 1시간 TTL은 write 2×. read는 둘 다 0.1×. 100번 요청을 도는 긴 세션에서 5분 TTL이 10번 만료되면 매번 1.25×로 재적재된다. 1시간 TTL은 write를 한 번 찍고 남은 99번을 0.1×로 처리한다. 2× 더 비싼 write 한 번이 10× 더 싼 read 뭉치로 뒤바뀌는 구조다.

DISABLE_TELEMETRY가 TTL을 잡아먹던 버그

2.1.108이 조용히 고친 또 다른 항목이 이거다. GitHub issue #45381에서 잡혀 있던 버그인데, 요지는 이렇다.

DISABLE_TELEMETRY=1 또는 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1을 켜둔 구독자들의 세션이 원래 1시간 TTL을 받아야 하는데도 5분 TTL로 떨어지고 있었다. 프라이버시 설정 하나 켰을 뿐인데 캐시 비용이 튀는 구조였던 셈이다. 보안에 예민한 기업 사용자일수록 이 조합을 쓸 가능성이 높은데, 이들이 오히려 더 비싸게 쓰고 있었다는 얘기다.

내부 구현을 짐작해 보면, 1시간 TTL 할당 여부를 결정하는 로직이 텔레메트리 시그널과 결합돼 있었던 것 같다. 텔레메트리가 꺼져 있으면 사용자 분류가 안 돼서 "보수적인" 기본값(5분)으로 떨어진 모양이다. 이번 픽스로 TTL 결정 경로와 텔레메트리 경로가 분리됐다는 뜻이고, 이건 구조적으로 맞는 방향이다.

덧붙이면, recap 기능도 텔레메트리 비활성화 사용자에게는 기본 비활성화인데 CLAUDE_CODE_ENABLE_AWAY_SUMMARY로 강제 활성화할 수 있다. 이번 릴리스 전반에 "텔레메트리 끈 사람도 기능을 잃지 말자"는 의도가 깔려 있다.

DISABLE_PROMPT_CACHING 경고

세 번째 변경은 미묘하지만 의미가 있다. DISABLE_PROMPT_CACHING* 계열 환경변수를 켜둔 상태로 Claude Code를 시작하면 이제 경고가 뜬다.

이게 왜 중요할까. 이슈 #8632를 보면 예전에 DISABLE_PROMPT_CACHING을 끄려다 401 오류로 튀어버린 사례가 있었다. 그보다 더 자주 발생하는 문제는 "캐시가 꺼진 줄 모르고 비싸게 쓰는 케이스"다. .envrc나 direnv에 한 번 설정해두고 까먹으면, 캐시 재사용으로 얻을 이득을 전부 날리면서 청구서만 두껍게 받는다.

시작 시 경고 한 줄은 비용이 0인 안전망이다. 누군가 팀원의 dotfile을 복사해 왔을 때, 또는 도커 이미지에 오래된 env가 박혀 있을 때 딱 한 번 경고가 뜨는 것만으로 "어? 이거 내가 왜 켜뒀지?"라는 순간을 만들어준다.

recap — 돌아왔을 때를 위한 장치

recap은 캐시 플래그는 아니지만 같은 맥락에 있다. 세션을 떠났다가 돌아올 때 Claude Code가 그동안의 맥락을 짧게 요약해 보여준다. /recap 커맨드로 수동 호출할 수 있고, /config에서 설정 가능하다.

이 기능이 캐시와 묶이는 지점은 이렇다. 장시간 자리를 비우면 1시간 TTL조차 만료된다. 돌아와서 다시 세션을 이어가려면 어차피 전체 프롬프트가 재적재되는 걸 피할 수 없다. 이때 recap이 "아까 뭘 하다가 멈췄는지"를 요약해 보여주면, 내가 장황하게 맥락을 다시 설명할 필요 없이 바로 다음 작업을 이어갈 수 있다. 캐시가 풀리는 비용은 어쩔 수 없지만, 재적재 후 불필요한 왕복을 줄여주는 UX다.

그 이전 버전들에서 이어진 패턴

이번 릴리스만 본 게 아니라, 2.1.x 구간을 쭉 훑어보면 캐시를 개선하려는 집요한 흐름이 보인다.

2.1.70 — MCP 서버가 첫 턴 이후 연결될 때 prompt-cache bust가 나던 문제 수정
2.1.86 — Bedrock, Vertex, Foundry에서 동적 콘텐츠를 제거해 캐시 히트율 향상
2.1.90 — --resume 첫 요청에서 전체 캐시 미스가 나던 버그 픽스
2.1.98 — Bedrock/Vertex/Foundry 캐시 히트율 재개선
2.1.101 — p90 prompt cache rate 개선
2.1.108 — ENABLE_PROMPT_CACHING_1H, 경고, 텔레메트리 버그 픽스

이걸 한 줄로 요약하면 Anthropic이 반년 가까이 "캐시 히트율"을 북극성 지표로 잡고 돌리고 있다는 뜻이다. 개선 → 버그 발견 → 수정 → 다시 개선의 사이클이 촘촘하다. 프롬프트 캐싱이 Claude Code의 비용 경제 전체를 떠받치고 있다는 걸 Anthropic도 알고 있고, 사용자들이 3월에 조용한 회귀로 그걸 체감했다.

흥미로운 건 2.1.80에서 /cost에 모델별/캐시 히트 분해 정보가 추가된 점이다. 사용자가 "내 세션에서 캐시가 얼마나 일하는가"를 직접 확인할 수 있게 해주는 장치. 이번 2.1.108의 플래그들과 합치면, Anthropic은 이제 캐시를 블랙박스가 아니라 "명시적으로 제어할 수 있고, 측정도 가능한 자원"으로 드러내는 방향으로 움직이고 있다.

내가 바꿀 workflow

이 글을 쓰면서 정리된 내 액션 아이템은 이렇다.

첫째, .zshrc에 export ENABLE_PROMPT_CACHING_1H=1을 박아두기로 했다. 내 평균 코딩 세션은 짧아도 40분은 간다. 1시간 TTL이 손해일 확률이 거의 없다.

둘째, DISABLE_PROMPT_CACHING 계열이 어딘가에 숨어있지 않은지 env | grep PROMPT_CACHING으로 확인했다. 다행히 깨끗했다.

셋째, 팀원들에게 이 플래그를 공유할 때 "1시간 TTL 옵트인"이라고만 적지 않고, write 비용이 2×가 된다는 트레이드오프까지 명시할 생각이다. 초단기 배치 작업처럼 캐시를 한 번밖에 못 쓰는 상황이라면 오히려 손해일 수 있으니까.

3월의 그 조용한 회귀 사건이 없었으면 이번 릴리스의 의미가 이렇게 또렷하게 보이지 않았을 것 같다. 플래그 하나 추가된 게 전부라고 넘길 수도 있는데, 그게 하나 나오기까지 어떤 사건들이 쌓였는지 알면 changelog 한 줄이 짧은 사건 기록처럼 읽힌다. Claude Code의 캐시는 이제 "알아서 잘 돌아가는 것"이 아니라 "내가 제어 가능한 것"에 가까워졌다. 당분간은 이 플래그를 켠 채로 청구서를 지켜볼 생각이다.