[Claude][운영] mid-conversation tool changes를 롤백할 때 beta header와 append-only system message를 어떤 순서로 되돌리나

IT 리서치 노트

[Claude][운영] mid-conversation tool changes를 롤백할 때 beta header와 append-only system message를 어떤 순서로 되돌리나

Claude 세션에서 mid-conversation tool changes를 쓰다 보면 rollout만큼 rollback이 더 헷갈릴 때가 많다. 2026년 8월 18일 기준 Anthropic 공식 문서를 다시 보면 tool changes는 beta header를 요구하고, system 정책 변경은 append-only system message로 처리해야 cache prefix를 지키기 쉽고, cache diagnostics는 대화 기록을 append-only로 유지하라고 적고 있다. 이 글은 기능을 빼거나 고정 tool 목록으로 돌아갈 때 어떤 층부터 어떤 순서로 되돌리면 triage가 덜 꼬이는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 Claude의 mid-conversation tool changes rollback은 beta header 제거와 tools 고정을 먼저 하고, 기존 system/history를 수정하지 않는 append-only 규칙을 그다음에 고정하는 편이 맞다. 기능을 끄는 일과 과거 turns를 편집하는 일을 섞으면 cache miss 원인이 사라진다.

즉 rollback의 핵심은 tools delta를 그만 보내는 것보다, 그 과정에서 top-level system을 덮어쓰거나 과거 assistant content를 다시 직렬화하지 않는 데 있다. 기능 gate와 history gate를 나눠 적어야 다음 세션 비교가 쉬워진다.

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

실무에서 먼저 막히는 지점은 네 가지다. 첫째, beta header만 빼면 자동으로 안전하게 이전 상태로 돌아갈 것이라고 생각한다. 둘째, tools를 고정 목록으로 되돌리면서 동시에 top-level system을 다시 써 cache 경계를 바꾼다. 셋째, 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. 실무에서 적용하는 순서

가장 짧은 rollback 순서는 다섯 단계다. 먼저 해당 surface에서 beta header를 제거할지 여부를 명시한다. 두 번째로 tools 목록을 세션별 고정 리스트로 되돌린다. 세 번째로 top-level system을 수정하지 않고, 필요한 정책 철회는 새 system message append로만 남긴다. 네 번째로 기존 assistant content와 tool results는 그대로 resend한다. 마지막으로 cache diagnostics에서 tools mismatch와 messages_changed를 별도 필드로 저장한다.

1. beta header 제거 대상을 surface별로 먼저 적는다.
2. tools를 고정 목록으로 되돌린다.
3. top-level system 편집 대신 새 system message만 append한다.
4. assistant content와 tool results는 그대로 유지한다.
5. cache miss 원인을 tools와 messages 두 필드로 나눠 기록한다.

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

rollback 점검 메모 예시

beta_header_after=none
tools_mode_after=fixed_list
system_message_action=append_only
assistant_turns_rewritten=false
cache_diag_watch=tools_mismatch,messages_changed

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

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 기준을 더 좁힌 후속편이다.

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

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

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

5. 주의사항과 리스크

첫 번째 리스크는 기능을 끄며 top-level system도 같이 다시 써 버리는 것이다. 두 번째는 tool rollback을 위해 과거 assistant turn을 요약해 다시 보내는 것이다. 세 번째는 beta header 누락과 append-only 위반을 같은 incident 줄에 적는 것이다.

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

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

6. 결론

Claude의 mid-conversation tool changes rollback은 header를 빼는 일과 history를 보존하는 일을 같은 동작으로 다루면 실패한다. 먼저 beta header와 fixed tools 전환을 닫고, 그다음 append-only system message와 assistant/tool result 보존 규칙을 지키면 기능 철회와 cache triage를 훨씬 짧게 분리할 수 있다.

• beta header 제거와 tools 고정을 먼저 한다.
• 과거 system/history는 수정하지 않는다.
• diagnostics는 tools mismatch와 messages_changed로 나눠 저장한다.

7. 참고 링크

1. https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages
2. https://platform.claude.com/docs/en/build-with-claude/prompt-caching
3. https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics
4. https://platform.claude.com/docs/en/about-claude/models/whats-new-opus-5
5. https://platform.claude.com/docs/en/about-claude/models/migration-guide