[Claude][운영] Claude Opus 5에서 mid-conversation system message와 tool changes를 같이 쓸 때 cache breakpoint와 금지 변경을 어떤 순서로 먼저 고정하나

IT 리서치 노트

[Claude][운영] Claude Opus 5에서 mid-conversation system message와 tool changes를 같이 쓸 때 cache breakpoint와 금지 변경을 어떤 순서로 먼저 고정하나

Claude Opus 5에서 mid-conversation system message와 tool changes를 같이 쓰기 시작하면 prompt cache를 살리면서도 지시와 도구 노출을 바꿀 수 있다는 장점이 생긴다. 다만 2026년 8월 9일 기준 Anthropic 공식 문서를 다시 보면 system message와 tool changes는 지원 범위와 beta 요구사항이 다르고, tools 배열과 이전 system message를 함부로 고치면 cache hit가 크게 흔들린다. 이 글은 cache breakpoint와 금지 변경을 어떤 순서로 먼저 고정해야 운영이 덜 꼬이는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 Claude Opus 5에서 이 기능을 안정적으로 쓰려면 기능별 지원 범위, tools 배열 고정, cache breakpoint 위치, append-only system message 규칙, rollback 메모 순서로 먼저 정하는 편이 맞다. system message는 beta header가 필요 없지만, tool changes는 beta 기능이고 tools 배열을 바꾸면 prompt cache가 다시 계산된다.

이미 prompt caching 512-token 기준 글, stop_reason과 beta header 검증 글, mid-conversation tool changes 초기 검증 글을 읽었다면, 이번 글은 그 위에 cache breakpoint와 금지 변경을 묶어 놓는 운영 표준이다.

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

현장에서 자주 생기는 문제는 세 가지다. 첫째, system message와 tool changes를 하나의 기능처럼 취급해 Sonnet 5 같은 미지원 모델에서 기대 동작을 가정한다. 둘째, tools 배열에 새 tool을 뒤늦게 추가해 캐시 미스를 만든 뒤 원인을 beta header나 thinking 설정으로 오해한다. 셋째, 이미 보낸 mid-conversation system message를 덮어써 rollback하려다 cache invalidation과 감사 추적 붕괴를 동시에 만든다.

Anthropic 문서는 tools 배열이 top-level system보다 더 앞쪽 hashed prefix에 있다고 설명하고, tool changes를 쓸 때는 전체 tool set을 처음부터 선언하라고 적는다. 또 이미 보낸 mid-conversation system message는 수정하지 말고 새 message를 append하라고 권한다. 따라서 cache 문제와 정책 변경 문제를 같은 수정 방식으로 다루면 안 된다. 실제로는 요청 JSON 필드, 로그 응답, 모델 상태, beta 설정 값을 하나씩 확인하고 실행 결과를 비교해야 한다.

• 증상: 기능은 비슷한데 모델마다 cache hit와 지원 여부가 다르게 보인다.
• 실패: tools 배열을 뒤늦게 수정해 cache miss를 만든다.
• 막힘: 예전 system message를 덮어쓰며 rollback한다.
• 누락: support 범위와 beta header를 기능별로 분리해 기록하지 않는다.

증상	먼저 볼 곳	판단 기준
tool change 뒤 cache hit가 사라진다	tools 배열 변경 여부	tool_addition인지 배열 재정의인지 구분한다
model별 동작이 다르다	지원 모델과 beta 요구사항	system message 지원과 tool changes 지원을 나눠 본다
rollback 뒤 더 많이 꼬인다	이전 system message 수정 여부	append-only 규칙을 지켰는지 본다

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

실무 적용 순서는 다섯 단계가 가장 실용적이다. 먼저 mid-conversation system message와 tool changes의 지원 범위를 모델별로 분리한다. 두 번째로 사용할 전체 tool set을 tools 배열에 고정한다. 세 번째로 stable prefix가 끝나는 지점에 cache breakpoint를 둔다. 네 번째로 이후 정책 변경은 새 system message append로만 처리한다. 마지막으로 rollback memo도 이전 기록 수정이 아니라 새 message 추가 방식으로 남긴다.

1. 기능별 지원 범위와 beta 요구사항을 먼저 표로 나눈다.
2. 전체 tool set을 tools 배열에 고정한다.
3. cache breakpoint를 stable prefix 끝에 둔다.
4. 새 정책과 새 도구 노출은 append-only message로 추가한다.
5. rollback도 이전 기록 수정 대신 새 정정 message로 남긴다.

이 구조를 잡아 두면 cache miss 원인이 빨리 분리된다. 요청 필드를 확인하고, tools 배열 설정을 확인하고, system message 위치를 확인하고, 응답 로그를 조회하고, cache 결과를 비교하고, 필요한 명령이나 테스트를 다시 실행하는 순서가 고정되기 때문이다. 반대로 이 규칙이 없으면 beta header, cache_control, model 지원, tool declaration이 한 덩어리로 섞여 같은 실수를 반복하기 쉽다.

check_1=model_support
check_2=tools_array_changed
check_3=cache_breakpoint_before_tail
check_4=appended_new_system_message
check_5=rollback_note_is_append_only

특히 incident 중에는 예전 message를 고치고 싶은 유혹이 크다. 하지만 공식 문서가 이미 금지 변경으로 짚은 부분이라면, 그 유혹을 이기는 편이 장기적으로 낫다. 나중에 replay나 비용 비교를 할 때도 append-only 기록이 훨씬 읽기 쉽다.

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

첫 공식 화면은 mid-conversation system message의 지원 범위다. Anthropic은 이 기능에는 beta header가 필요 없고, Claude Sonnet 5에서는 지원하지 않는다고 분명히 적어 둔다. 이 화면에서는 지원 상태와 모델명을 확인하고, 어떤 필드를 바꾸면 안 되는지 메모해야 한다.

mid-conversation system message는 beta header가 필요 없지만 Sonnet 5에서는 지원되지 않는다.

즉 system message와 tool changes를 함께 쓴다면 두 기능을 같은 가정으로 다루면 안 된다. system message 지원 여부와 tool changes beta 요구사항을 먼저 분리해야 한다.

두 번째 자료는 mid-conversation tool changes의 핵심 전제다. Anthropic은 전체 tool set을 처음부터 tools 배열에 선언하고 이후에는 tool_addition과 tool_removal로만 노출 범위를 바꾸라고 설명한다. 이 문구에서는 tools 필드와 content block 경로를 확인하고, 어떤 변경이 prefix를 깨는지 바로 읽어야 한다.

tool changes를 쓸 때는 전체 tool set을 tools 배열에 먼저 선언하고 이후에는 tool_addition·tool_removal로만 바꾼다.

이 규칙이 깨지면 cache breakpoint를 잘 잡아도 의미가 줄어든다. tools 배열 자체를 바꾸면 hashed prefix가 달라져 prompt cache를 다시 태우기 때문이다.

세 번째 화면은 실제 운영에서 가장 자주 놓치는 금지 변경이다. Anthropic은 이미 보낸 mid-conversation system message를 수정하거나 제거하지 말고 새 system message를 append하라고 적는다. 이 화면에서는 버튼이나 메뉴가 아니라 메시지 순서와 필드 변경 금지를 확인하는 것이 핵심이다.

이미 보낸 mid-conversation system message는 수정하지 말고 새 system message를 append해야 cache invalidation을 줄일 수 있다.

이 문장은 rollback runbook의 기준이 된다. 문제가 생겼을 때 예전 system message를 덮어쓰기보다 새로운 정정 message를 뒤에 붙이는 편이 cache hit와 감사 추적 모두에 유리하다.

실무에서는 stable prefix와 mutable tail을 표로 나눠 두는 편이 좋다. 그래야 어떤 변경이 cache hit를 깨는지와, 어떤 변경은 뒤쪽 append로 해결되는지 한 번에 보인다.

Claude Opus 5에서 stable prefix와 mutable tail을 나누는 기준표다.

이미 prompt caching 최소 길이 글이 prefix 재분리 기준을 다뤘다면, 이번 표는 mid-conversation system message와 tool changes를 추가한 뒤의 운영 경계다.

마지막 자료는 cache breakpoint와 금지 변경을 같이 남기는 예시다. 중요한 점은 tool definition을 뒤늦게 덧붙이지 않고, 새 지시는 system message로 뒤에 append한다는 것이다.

Claude Opus 5에서 cache breakpoint와 tool change를 같이 남기는 예시다.

이 구조를 남겨 두면 stop_reason과 beta header 검증 글과 mid-conversation tool changes 초기 검증 글 위에 바로 이어 붙일 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 system message와 tool changes의 지원 범위를 같은 것으로 오해하는 것이다. 두 번째는 tools 배열 재정의와 tool_addition을 같은 작업처럼 다루는 것이다. 세 번째는 이미 보낸 system message를 지워서 rollback 기록과 cache history를 함께 잃는 것이다.

또 Anthropic은 Sonnet 5에서 mid-conversation system message를 지원하지 않는다고 밝히고 있으므로, 모델 교체 시에는 기능 fallback을 top-level system 쪽으로 되돌릴 준비가 필요하다. 이때도 어떤 필드를 수정했고 어떤 로그 응답을 확인했는지, 어떤 결과가 나왔는지, 어떤 설정을 저장했는지를 같이 남겨야 한다. 반면 Opus 5 branch에서 tool changes를 쓰려면 beta header를 계속 관리해야 한다.

• 모델 지원 범위를 기능별로 분리하지 않으면 같은 코드가 환경마다 다르게 보인다.
• tools 배열을 바꾸면 cache breakpoint 설계가 무너진다.
• rollback은 rewrite보다 append-only 기록이 안전하다.

6. 결론

Claude Opus 5에서 mid-conversation system message와 tool changes를 함께 쓰려면 지시 변경보다 먼저 cache 구조를 고정해야 한다. 지원 범위, tools 배열, breakpoint, append-only 규칙, rollback 메모를 먼저 정해 두면 이후 정책 변경이 훨씬 덜 꼬인다.

• tools 배열은 처음부터 고정한다.
• 정책 변경은 새 system message append로 처리한다.
• 기능 지원 범위와 beta 요구사항을 함께 기록한다.

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/about-claude/models/whats-new-opus-5
4. https://platform.claude.com/docs/en/release-notes/overview
5. https://platform.claude.com/docs/en/about-claude/models/migration-guide