[Claude][운영] Claude Opus 5에서 rollback 뒤 cache_diag_watch 필드를 어떤 incident template으로 남기나

IT 리서치 노트

[Claude][운영] Claude Opus 5에서 rollback 뒤 cache_diag_watch 필드를 어떤 incident template으로 남기나

Claude Opus 5 운영에서 mid-conversation tool changes를 한 번 켰다가 되돌리면, 실제로 오래 남는 문제는 rollback 자체보다 rollback 뒤 cache miss를 어떤 필드로 기록하느냐다. 2026년 8월 24일 기준 Anthropic 공식 문서를 다시 보면 tool changes는 beta header를 요구하고, system 정책 변경은 append-only system message로 처리해야 cache prefix를 지키기 쉽고, cache diagnostics는 대화 기록을 append-only로 유지하라고 적고 있다. 이 글은 기능 철회 후 incident memo에 cache_diag_watch, header_state, tools_mode, messages_changed를 어떤 순서로 남기면 triage가 덜 꼬이는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 Claude rollback 뒤 incident template은 header_state, tools_mode, top_level_system_edited, messages_changed를 먼저 고정하고, 그 묶음을 cache_diag_watch 한 줄로 다시 요약하는 편이 맞다. 기능을 끄는 순서만 적고 진단 필드를 남기지 않으면 다음 miss를 같은 증상으로 묶어 버리기 쉽다.

즉 핵심은 tools delta를 그만 보내는 사실보다, rollback 직후 어떤 cache miss가 요청 계층 문제인지 대화 계층 문제인지 분리해서 남기는 데 있다. 기능 gate와 history gate를 나눠 적어야 다음 세션 비교와 재현이 쉬워진다.

2. 어디서 실제로 막히는가

실무에서 먼저 막히는 지점은 네 가지다. 첫째, beta header만 빼면 incident memo도 끝났다고 생각한다. 둘째, tools를 고정 목록으로 되돌린 뒤에도 어떤 surface가 old header를 탔는지 안 남긴다. 셋째, assistant turn이나 tool result를 보기 좋게 다시 직렬화해 resend한다. 넷째, cache diagnostics에서 messages_changed와 tools mismatch를 같은 miss로 묶는다.

Anthropic 문서는 mid-conversation tool changes가 beta header를 요구한다고 분리해 적고, prompt caching 문서는 system 정책 변경을 append-only system message 방식으로 처리하라고 설명한다. cache diagnostics 문서는 history가 편집되면 messages_changed가 발생할 수 있으니 assistant content와 tool results를 그대로 되돌려 보내라고 적는다. 이 셋을 같이 읽으면 rollback은 단순 토글이 아니라 요청 계층과 대화 계층을 따로 닫는 작업이라는 점이 드러난다.

특히 장애가 난 뒤 tool changes를 철회할 때 과거 세션을 깔끔하게 정리하고 싶은 유혹이 큰데, 바로 그 정리 편집이 cache 경계를 더 크게 흔드는 경우가 많다. 기능을 되돌리는 메모와 대화 기록 보존 메모를 나눠야 하는 이유가 여기 있다.

• 증상: rollback 뒤 cache hit가 예상보다 더 크게 떨어진다.
• 실패: beta header 제거와 history 편집을 같은 배포에서 함께 수행한다.
• 막힘: tools delta miss와 messages_changed miss를 같은 원인으로 읽는다.
• 재발: 어느 세션이 old header를 탔는지, 어느 세션이 fixed tools로 돌아갔는지 남기지 않는다.

증상	먼저 볼 곳	판단 기준
rollback 뒤 hit 급감	messages_changed, tools mismatch	기능 철회인지 history 편집인지 분리한다
일부 세션만 흔들림	beta header 존재 여부	header가 남은 surface가 있는지 본다
tool path는 껐는데 miss가 계속 큼	system/history 수정 여부	append-only 규칙을 깼는지 본다

3. 실무에서 적용하는 순서

가장 짧은 incident-template 순서는 다섯 단계다. 먼저 해당 surface의 header_state를 적는다. 두 번째로 tools_mode를 fixed인지 delta인지 남긴다. 세 번째로 top_level_system_edited와 messages_changed를 예/아니오로 저장한다. 네 번째로 assistant content와 tool results를 그대로 resend했는지 적는다. 마지막으로 cache_diag_watch에 tools_mismatch와 messages_changed 중 무엇을 봐야 하는지 한 줄로 요약한다.

1. surface별 header 상태를 먼저 적는다.
2. tools mode가 fixed인지 delta인지 분리한다.
3. system/history 편집 여부를 예/아니오로 저장한다.
4. assistant content와 tool results resend 여부를 남긴다.
5. cache_diag_watch에 볼 miss 종류를 한 줄로 요약한다.

이 순서를 지키면 rollback 이후 triage가 훨씬 짧아진다. tools feature gate는 요청 계층에서 닫히고, append-only rule은 cache 계층을 안정시키며, diagnostics 필드 분리는 이후 복기를 쉽게 만든다. 특히 여러 surface에서 같은 Claude 세션 규칙을 운영한다면 header 제거 시점과 fixed tools 전환 시점을 따로 남겨야 한다.

rollback 뒤 incident template 예시

header_state=beta_removed
tools_mode=fixed_list
top_level_system_edited=false
messages_changed=false
cache_diag_watch=tools_mismatch,messages_changed

실제 운영에서는 요청 샘플을 저장하고, beta header 값을 확인하고, tools 배열 diff를 비교하고, 새 system message를 append하고, assistant turn을 그대로 되돌려 보내고, diagnostics 필드를 조회하는 순서를 팀 메모에 고정해 두는 편이 좋다. 운영자는 콘솔에서 요청 로그를 조회하고, trace 파일을 저장하고, header 제거 시각을 기록하고, cache miss 로그를 확인하고, surface별 설정값을 비교해야 한다. 이 다섯 동작을 한 incident template에 같이 적어 두면 재배포와 재확인이 빨라진다.

4. 공식 문서와 예시 화면으로 확인하기

첫 공식 화면은 mid-conversation tool changes가 여전히 beta header를 요구한다는 문장이다. 롤백 순서를 잡을 때 가장 먼저 확인해야 하는 이유는, 이 기능이 단순한 tools 배열 변경이 아니라 feature gate 자체를 타기 때문이다.

mid-conversation tool changes는 beta 기능이며 `mid-conversation-tool-changes-2026-07-01` header가 있어야 동작한다.

즉 세션에서 이 기능을 끄려면 tools delta만 지우는 것으로 끝나지 않는다. 요청 레벨에서 beta header를 언제 빼고, tools를 언제 고정 목록으로 되돌릴지를 분리해 적어야 한다.

두 번째 자료는 prompt caching 문서다. Anthropic은 top-level system을 덮어쓰지 말고 `messages`에 system 메시지를 append하라고 설명한다.

cached prefix를 보존하려면 top-level system 편집보다 append-only system message 방식이 권장된다.

이 문장은 롤백 때도 중요하다. 정책을 철회할 때 이전 system을 수정해 버리면 cache 경계가 바뀌고, 이후 miss 진단이 tools 문제인지 history 편집 문제인지 섞인다.

세 번째 자료는 cache diagnostics다. 여기서는 messages_changed 원인을 줄이려면 대화 기록을 append-only로 유지하고 assistant content와 tool result를 그대로 되돌려 보내라고 적고 있다.

cache miss 진단에서는 history를 append-only로 유지하고 assistant turns와 tool results를 그대로 재전송하라고 안내한다.

그래서 rollback runbook도 `tool delta 중단`과 `history 수정 금지`를 분리해 적는 편이 맞다. 기능을 끈다고 해서 직전 assistant turn이나 tool result를 정리 편집하면, 롤백보다 더 큰 cache miss가 생길 수 있다.

실무에서는 rollback을 두 층으로 나눠 적는 편이 가장 짧다. 첫 층은 feature gate와 tools 목록, 두 번째 층은 append-only history와 cache 경계다.

mid-conversation tool changes rollback을 feature gate 층과 history 층으로 나누는 판단표다.

이미 mid-conversation tool changes를 켤 때 prompt cache 보존과 beta header를 나누는 글이 rollout 기준을, rollback 순서를 다룬 기존 Claude 글이 기능 철회 순서를 다뤘다면, 이번 표는 그 뒤에 남겨야 할 incident fields를 더 좁힌 후속편이다.

마지막 자료는 실제로 남기면 좋은 최소 rollback 메모다. 기능 해제와 history 보존을 같은 줄에 분리해 두면 세션별 사고 반경을 빠르게 자를 수 있다.

beta header 제거, tools 고정, append-only history 유지를 한 번에 남기는 최소 메모 예시다.

이 정도만 있어도 `header를 뺐는지`, `tools를 언제 고정했는지`, `history를 건드렸는지`를 바로 비교할 수 있다. Claude 세션을 여러 surface에 나눠 운영할수록 이 세 칸이 중요해진다.

5. 주의사항과 리스크

첫 번째 리스크는 기능을 끈 사실만 적고 어떤 surface가 old header를 탔는지 비워 두는 것이다. 두 번째는 tool rollback을 위해 과거 assistant turn을 요약해 다시 보내는 것이다. 세 번째는 beta header 누락과 append-only 위반을 같은 incident 줄에 적는 것이다.

운영 전에 확인할 때는 최소한 header_state, tools_mode, top_level_system_edited, messages_changed 네 칸을 같은 표에 두는 편이 좋다. 이 네 칸이 없으면 rollback 이후 miss 폭증을 원인별로 자르기 어렵다. 팀은 배포 전 표를 열고, header 상태를 확인하고, tools 모드를 비교하고, history 편집 여부를 저장하고, cache 진단 필드를 조회하는 순서를 반복 점검해야 한다.

만약 rollback 직후 refusal 증가나 fallback 전환까지 함께 흔들린다면, Claude Opus 5에서 refusal 응답과 fallback 전환이 함께 흔들릴 때 stop_reason 로그와 beta header 검증을 어떤 순서로 분리하나 글처럼 응답 품질 신호와 tool/cache 신호를 분리해서 incident를 나눠 보는 편이 안전하다.

• 기능 철회와 history 수정은 별개 사건으로 저장하고 로그를 분리한다.
• append-only 규칙을 지켜야 cache miss 원인을 확인하고 비교할 수 있다.
• incident template에는 surface별 header 상태와 tools 설정값을 꼭 남긴다.

6. 결론

Claude rollback 뒤 incident template은 header를 빼는 일과 history를 보존하는 일을 같은 동작으로 적지 않는 데서 시작한다. 먼저 surface별 header 상태와 fixed tools 전환 여부를 적고, 그다음 append-only system message와 assistant/tool result 보존 규칙을 남기면 기능 철회와 cache triage를 훨씬 짧게 분리할 수 있다.

• surface별 header 상태와 tools mode를 먼저 적는다.
• 과거 system/history는 수정하지 않는다.
• cache_diag_watch는 tools mismatch와 messages_changed로 나눠 저장한다.

7. 참고 링크

1. https://docs.anthropic.com/en/docs/build-with-claude/mid-conversation-system-messages
2. https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
3. https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching#troubleshooting-common-issues
4. https://docs.anthropic.com/en/docs/about-claude/models/whats-new-claude-4-8
5. https://docs.anthropic.com/en/docs/about-claude/models/migrating-to-claude-4