2026년 6월 2일, Anthropic은 여러 중요한 문서 업데이트와 API 변경을 실시했습니다. 그중에서도 Claude Opus 4 / Sonnet 4의 폐지가 2026년 6월 15일로 다가왔으며, 권장 이행 모델이 Opus 4.7에서 Opus 4.8로 변경된 것은 해당 모델을 이용 중인 개발자에게 즉각적인 대응이 필요합니다.

또한, Claude Opus 4.8의 1M 토큰 컨텍스트 윈도우 (Context Window)를 이용할 수 있는 플랫폼이 명시되었고, stop_details 필드의 공식 문서화, advisor tool에 max_tokens 파라미터 추가 등 실용적인 개선 사항도 여러 개 출시되었습니다.

📌 영향을 받는 사람

• claude-opus-4-20250514 또는 claude-sonnet-4-20250514를 운영 환경에서 이용 중인 개발자 (대응 필요)
• Claude Opus 4.8을 대규모 컨텍스트로 이용 중인 개발자
• 거부 응답 (Refusal Response) 핸들링 로직을 구현하고 있는 개발자

⚠️ Breaking Change

claude-opus-4-20250514 및 claude-sonnet-4-20250514는 2026년 6월 15일에 Claude API에서 퇴역합니다. 하드코딩되어 있는 경우 지금 바로 이행하십시오.

권장 이행 모델이 업데이트되었습니다:

Opus 4를 이용하고 있었다면, 이행 대상이 Opus 4.7에서 Opus 4.8로 바뀌었다는 점에 주의하십시오. Opus 4.8은 Opus 4.7과 동등한 툴 및 플랫폼 기능을 가지면서도, 기본적으로 1M 토큰 컨텍스트와 128k 최대 출력 토큰을 지원합니다.

Claude Opus 4.8의 기본 1M 토큰 컨텍스트 윈도우는 모든 플랫폼에서 이용할 수 있는 것은 아닙니다.

💡 Tips

Microsoft Foundry를 통해 Opus 4.8을 이용하고 있는 경우, 방대한 문서 처리 등으로 인해 예상치 못한 컨텍스트 끊김이 발생할 가능성이 있습니다. 입력 길이에 상한을 두거나 다른 플랫폼으로의 이행을 검토하십시오.

Claude Opus 4.8이 요청을 거부했을 때 반환하는 stop_details 필드가 공식적으로 문서화되었습니다. beta 헤더는 필요하지 않으며, 현재 이미 이용 가능합니다.

stop_details의 구조:

거부 카테고리를 판별하여 라우팅 처리를 구현함으로써, 사용자에게 적절한 피드백을 제공하거나 대체 플로우로 유도할 수 있습니다.

Claude Opus 4.8에서 지원되는 대화 도중의 시스템 메시지 삽입에 대해, 배치 규칙 (Placement Rules)이 명확해졌습니다.

변경 전 표현:

messages 배열의 선두가 아닌 위치에 role: "system"을 전송 가능

변경 후 표현:

사용자 턴(User Turn) 이후 (배치 규칙에 따름)에 role: "system"을 전송 가능

즉, role: "system"

메시지는 사용자 턴 (User Turn) 직후에 배치해야 합니다. 장시간 세션 중에 지시 사항이 바뀌더라도, 이 배치 규칙을 준수함으로써 프롬프트 캐시 (Prompt Cache) 히트율을 유지할 수 있습니다.

tools[].max_tokens를 설정함으로써, advisor 모델이 1회 호출 시 생성하는 출력의 최대 길이를 제한할 수 있게 되었습니다.

전체 길이의 advisor 응답이 필요하지 않은 워크로드 (판정, 분류, 짧은 보완 등)에서 레이턴시 (Latency)와 비용을 절감할 수 있습니다.

🔴 즉시 대응 필요 (2026-06-15까지)

• claude-opus-4-20250514 사용처를 claude-opus-4-8로 교체
• claude-sonnet-4-20250514 사용처를 claude-sonnet-4-6로 교체
• 모델 ID를 하드코딩(Hard-code)하고 있는 설정 파일 및 환경 변수 확인

🟡 권장 대응

• Microsoft Foundry에서 Opus 4.8을 사용하는 경우, 200k 제한 영향 조사
• 거부 응답 핸들링 (Refusal handling)에 stop_details.category를 활용한 분기 처리 추가

🔵 선택 사항

• advisor tool 이용 시 max_tokens를 통한 비용 최적화 검토
• Opus 4.8의 대화 중간 시스템 메시지 (mid-conversation system messages) 활용을 통한 캐시 히트율 개선

import anthropic
client = anthropic.Anthropic()
# Before（2026-06-15 에 퇴역）
...

import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
...

tools = [
{
"type": "advisor",
...

messages = [
{"role": "user", "content": "タスクを開始してください"},
{"role": "assistant", "content": "了解しました。処理を開始します。"},
...

이번 변경에서 가장 중요한 점은 Opus 4 / Sonnet 4의 퇴역(2026년 6월 15일)과 이행처가 Opus 4.8로 업데이트되었다는 점입니다. 이행은 단순한 모델 ID 교체로 완료되지만, 기한까지 약 2주밖에 남지 않았으므로 신속하게 대응해 주시기 바랍니다.

또한, Microsoft Foundry에서 Opus 4.8을 이용하는 경우 컨텍스트 윈도우 (Context Window)가 200k로 제한된다는 점, stop_details 필드가 공식화되어 에러 핸들링 (Error handling)을 더욱 세밀하게 제어할 수 있게 되었다는 점도 시스템 설계 검토에 활용할 수 있습니다.