[Claude][운영] prompt caching에서 thinking config와 tool_choice가 함께 바뀔 때 cache miss 원인을 어떤 로그 순서로 나누나
IT 리서치 노트
[Claude][운영] prompt caching에서 thinking config와 tool_choice가 함께 바뀔 때 cache miss 원인을 어떤 로그 순서로 나누나
Claude prompt caching을 붙인 뒤 같은 작업처럼 보이는데도 cache hit가 갑자기 끊기는 순간이 있다. 2026년 8월 3일 기준 Anthropic 공식 문서를 다시 보면, thinking configuration 변화와 tool_choice 변화는 서로 다른 층에서 cache prefix를 흔들 수 있고, tool result가 붙은 follow-up 요청은 이전 thinking blocks까지 함께 다시 계산하게 만들 수 있다. 이 글은 thinking config와 tool_choice가 함께 바뀔 때 cache miss 원인을 어떤 로그 순서로 나눠 봐야 운영이 덜 꼬이는지 정리한 것이다.
1. 개요
결론부터 말하면 Claude prompt caching miss는 텍스트 diff보다 settings diff를 먼저 봐야 하는 경우가 많다. thinking mode나 budget이 바뀌면 같은 대화라도 cache_creation이 다시 생길 수 있고, tool_choice가 바뀌면 cached message blocks만 다시 처리되면서 write/read 패턴이 달라질 수 있다.
따라서 운영 로그는 prompt 본문만 남기면 부족하다. thinking 설정, tool_choice, tool result follow-up 여부, input/cache_read/cache_creation 네 묶음을 같이 기록해야 왜 miss가 났는지와 실제 비용이 어디서 늘었는지를 같은 문맥에서 설명할 수 있다.
2. 어디서 실제로 막히는가
실무에서 가장 흔한 혼선은 세 가지다. 첫째, cache miss가 나면 곧바로 사용자 질문이 길어졌다고 생각한다. 둘째, tool loop 뒤 write가 커졌을 때 thinking blocks가 함께 캐시될 수 있다는 사실을 빼먹는다. 셋째, tool_choice를 auto에서 any나 특정 tool로 바꾸고도 cache behavior는 그대로일 것이라고 기대한다.
하지만 Anthropic 문서는 total input을 보려면 input, cache read, cache creation을 합쳐야 한다고 적고, extended thinking 문서는 tool results를 포함한 follow-up 요청에서 thinking blocks도 함께 캐시될 수 있다고 설명한다. 또 tool use 문서는 tool_choice 변화가 cached message blocks를 무효화할 수 있지만 tool definitions와 system prompts는 계속 남을 수 있다고 밝힌다. 이 셋을 같이 읽으면 cache miss는 하나의 스위치가 아니라 여러 층의 상태 변화라는 사실이 분명해진다.
여기서 오래 끄는 이유는 usage 숫자가 비슷하게 보이기 때문이다. cache_creation_input_tokens가 다시 튄 상황, input_tokens만 늘어난 상황, cache hit는 됐지만 window 계산이 줄지 않은 상황이 표면상 모두 “캐시가 이상하다”로 묶인다. 특히 팀이 batch 처리와 tool-use loop를 같이 돌리면 같은 prefix를 쓴다고 믿었는데도 settings 변화 하나 때문에 다른 결과가 나온다.
- 증상: 같은 작업인데 cache_creation이 다시 커진다.
- 실패: prompt 본문만 비교하고 thinking과 tool_choice를 로그에서 뺀다.
- 막힘: tool result follow-up turn을 일반 대화 turn과 같은 방식으로 기록한다.
- 누락: context window 계산과 비용 계산을 같은 메모 한 줄로만 남긴다.
| 겉으로 보이는 현상 | 실제 원인 후보 | 먼저 저장할 값 |
|---|---|---|
| write가 갑자기 다시 생긴다 | thinking config 변화 또는 tool loop 구조 변화 | thinking mode, budget, has_tool_result_followup |
| hit는 있는데 window가 안 준다 | cache read도 window 계산에 남음 | input + cache_read + cache_creation 합계 |
| tool 실행 뒤 miss가 난다 | tool_choice 변경 또는 tool_result 포함 후속 | tool_choice, turn type, current usage |
3. 실무에서 적용하는 순서
가장 짧은 운영 순서는 여섯 단계다. 첫째, 매 요청마다 input_tokens, cache_creation_input_tokens, cache_read_input_tokens를 그대로 저장한다. 둘째, 그 turn이 tool result follow-up인지 표시한다. 셋째, thinking mode와 budget 또는 effort를 함께 기록한다. 넷째, tool_choice를 auto, any, tool 중 무엇으로 보냈는지 남긴다. 다섯째, context window 해석은 세 입력 필드의 합으로 본다. 여섯째, miss가 흔들릴 때는 텍스트 diff보다 settings diff를 먼저 비교한다.
- usage 세 필드를 항상 원문 그대로 저장한다.
- tool result follow-up 여부를 turn 속성으로 분리한다.
- thinking mode와 budget 또는 effort를 같은 레코드에 둔다.
- tool_choice 값을 별도 필드로 남긴다.
- window 계산은 세 입력 필드 합으로 다시 본다.
- miss 원인 분기는 settings diff부터 시작한다.
이 순서가 좋은 이유는 rollback이 빠르기 때문이다. 예를 들어 tool_choice만 바뀌었고 thinking은 그대로라면 cache prefix 전체를 다시 설계할 필요가 없고, 반대로 thinking budget이 바뀌었다면 message block을 아무리 고정해도 write가 다시 생길 수 있다. 또 batch 처리에서 cache hit를 높이고 싶다면 text를 자르기 전에 settings가 일정한지부터 확인하는 편이 더 실용적이다.
이렇게 적어 두면 “같은 작업인데 왜 hit가 안 났나”라는 질문이 “thinking budget이 바뀌었는가”, “tool_choice가 바뀌었는가”, “tool results가 붙은 follow-up인가”로 빠르게 번역된다. 운영자는 추상적인 체감이 아니라 재현 가능한 diff 순서로 문제를 좁힐 수 있다.
4. 공식 문서와 예시 화면으로 확인하기
첫 자료는 Anthropic prompt caching 문서의 usage 해석 구간이다. 여기서는 input_tokens가 요청 전체가 아니라 마지막 cache breakpoint 뒤 구간만 뜻하고, cache read와 cache creation을 합쳐야 전체 입력량을 계산할 수 있다고 설명한다.
이 전제를 먼저 고정해야 cache miss를 텍스트 길이 변화로만 잘못 해석하지 않는다. settings가 바뀌어 cache_creation이 다시 생긴 상황과, 실제 uncached input이 늘어난 상황은 같은 숫자로 보이지 않는다.
두 번째 공식 화면은 extended thinking 문서다. tool result를 포함한 follow-up 요청에서 이전 대화와 thinking blocks가 함께 캐시될 수 있다는 문장을 먼저 확인해야 한다.
즉 tool loop에서 갑자기 cache write가 커졌다면 사용자 질문이 길어진 것이 아니라 thinking과 tool result가 같이 prefix에 묶였을 가능성을 먼저 봐야 한다. 이미 tool use 루프 usage 글이 큰 그림을 다뤘다면, 이번 글은 그 안에서 settings 변수가 miss를 만들 때의 분기다.
세 번째 자료는 tool use 구현 문서의 cache invalidation 설명이다. 여기서는 tool_choice 변화가 cached message blocks를 다시 처리하게 만들지만, tool definitions와 system prompts는 계속 남을 수 있다고 짚는다.
따라서 tool_choice를 auto에서 tool 또는 any로 바꿨을 때 모든 miss를 프롬프트 전체 재작성으로 볼 필요는 없다. 어떤 층이 다시 계산됐는지 나눠 적으면 원인을 훨씬 짧게 좁힐 수 있다.
네 번째 공식 화면은 context window 문서다. input_tokens, cache_read_input_tokens, cache_creation_input_tokens가 모두 window 계산에 들어간다는 점이 핵심이다.
이 문장을 놓치면 cache hit가 늘었는데도 context window가 줄지 않는 이유를 설명하지 못한다. 비용 해석과 window 해석은 같은 필드를 보지만 의미가 완전히 같지는 않다는 점을 운영 메모에 분리해 적어야 한다.
다섯 번째 자료는 실제 triage 표다. same prompt처럼 보여도 miss 원인은 text diff, thinking diff, tool_choice diff, tool result follow-up diff로 갈라진다.
이미 TTL과 cache_control 글이 캐시 수명 판단을 다뤘고, automatic caching과 explicit breakpoints 글이 prefix 설계를 다뤘다면, 이번 표는 settings 때문에 miss가 생겼을 때 무엇부터 의심해야 하는지의 운영판이다.
마지막 자료는 운영 로그 예시다. prompt 본문 diff만 남기지 말고 thinking과 tool_choice와 tool result follow-up 상태를 같은 레코드에 두는 편이 낫다.
이 정도만 남겨도 같은 프롬프트인데 왜 hit가 끊겼는지 회고가 쉬워진다. 특히 batch 작업과 tool loop가 섞인 환경에서는 TTL 메모보다 settings diff가 먼저 원인으로 잡히는 경우가 많다.
5. 주의사항과 리스크
첫 번째 리스크는 cache miss를 모두 prompt wording 문제로 돌리는 것이다. 두 번째는 tool loop에서 thinking blocks가 write 폭증 원인일 수 있다는 점을 빼먹는 것이다. 세 번째는 cache hit가 있었으니 context window도 같이 줄었다고 잘못 믿는 것이다.
또 팀 문서에서 TTL 판단과 settings 판단을 같은 표 한 칸에 섞어 두면 회고가 꼬인다. TTL은 수명 문제고, thinking과 tool_choice는 prefix invalidation 문제다. 둘은 둘 다 caching 이슈지만 조정 손잡이가 다르다. 운영 전에 최소한 settings diff 표와 TTL 표를 따로 두는 편이 안전하다.
- miss 원인 추적은 텍스트보다 settings diff부터 본다.
- tool loop는 thinking과 tool results가 같이 움직이는 turn으로 취급한다.
- window 사용량과 비용 사용량은 같은 필드를 보더라도 설명을 따로 남긴다.
6. 결론
Claude prompt caching에서 thinking config와 tool_choice가 함께 바뀌는 순간은 텍스트 diff보다 운영 상태 diff를 읽어야 한다. usage 세 필드, tool result follow-up 여부, thinking 설정, tool_choice를 같은 로그에 두면 cache miss 원인을 훨씬 빨리 자를 수 있다.
정리하면 tool loop와 batch 처리 공통으로 필요한 값은 많지 않다. settings와 usage를 함께 남기고, context window 합계를 따로 계산하면 왜 hit가 끊겼는지와 어디서 비용이 다시 생겼는지를 한 번에 설명할 수 있다.
같은 가지의 후속편으로는 batch processing에서 shared prefix와 작업별 tail을 어떻게 쪼개는지 정리한 글이 바로 이어진다. tool loop에서 settings diff를 잡은 뒤 batch hit를 높이는 순서까지 붙여 보면 운영 로그 설계가 한 줄로 연결된다.