2026년 7월, Anthropic은 Claude Opus 5와 Claude Sonnet 5라는 두 가지 신규 모델을 연달아 출시했습니다. 이에 따라 기존 코드가 그대로는 작동하지 않게 되는 파괴적 변경 (Breaking Change) 도 여러 건 발생하고 있습니다.

특히 주의해야 할 점은 다음 3가지입니다.

• Claude Opus 5에서 effort: "xhigh" 또는 "max"를 지정한 상태로 thinking을 무효화하면 400 에러 발생
• Claude Opus 4.7의 fast mode가 삭제되어 speed: "fast" 지정 시 즉시 에러 발생
• Claude Sonnet 4 / Opus 4 등 구세대 모델의 제공 종료 (EOL), 레거시 Workbench도 2026년 8월 17일에 폐지

"버전 업그레이드니까 작동하겠지"라고 방심하여 배포했다가는, 운영 환경에서 일제히 요청이 실패할 리스크가 있습니다. 이 기사에서는 Claude API를 업무에 사용하고 있는 개발자 및 SRE 분들을 위해, 최근 반년 동안의 변경점을 정리하고 대응해야 할 액션을 정리합니다.

📌 영향을 받는 사람

• claude-opus-4-7 / claude-sonnet-4 / claude-opus-4 / claude-opus-4-1을 운영 환경에서 사용 중인 사람
• effort 파라미터나 수동 thinking 설정을 코드에 하드코딩(Hard-code)하고 있는 사람
• 레거시 Workbench (platform.claude.com/workbench)에 저장된 프롬프트나 평가 데이터가 있는 사람

먼저 2026년 전반기 ~ 7월 말까지의 주요 릴리스를 시계열로 정리합니다.

이어서, 파괴적 변경이 발생하고 있는 부분의 관계를 정리합니다.

⚠️ Breaking Change

Opus 5에서 effort: "xhigh" 또는 "max"와 thinking: {"type": "disabled"}를 동시에 지정하면, Opus 4.8까지는 통과되었던 요청이 400 에러가 됩니다.

대응이 필요한 항목을 체크리스트 형식으로 정리합니다.

• Opus 5 이행 전: effort를 xhigh / max로 설정한 상태에서 thinking을 무효화하고 있는 코드가 없는지 grep 수행
• Opus 4.7 이용 중: speed: "fast"

사용 중인 부분을 찾아내어 Opus 5 또는 Opus 4.8로 전환 -
Sonnet 5 이전: 수동 thinking 설정 (budget_tokens) 및 temperature / top_p / top_k 명시적 지정 제거 -
비용 산정: Sonnet 5의 토크나이저 변경(약 +30%)을 고려하여 컨텍스트 길이 및 과금 산정 재검토 -
Workbench 이용자: 저장된 프롬프트, 변수, evals를 2026/8/17까지 내보내기(export) -
실험적 prompt tools API 이용자: /v1/experimental/* 엔드포인트 사용 부분을 찾아내어 8/17까지 대체 구현으로 전환 -
MCP tunnels 이용자: 관리 API(Admin API) 호출 대상을 /v1/organizations/tunnels에서 /v1/tunnels (Claude API)로 전환

💡 Tips

claude-sonnet-4-20250514와 같이 날짜가 고정된 모델 ID를 직접 하드코딩(hard-code)해 두면, 서비스 종료 시 이를 인지하지 못해 운영 환경에서 에러가 발생하기 쉽습니다. 모델 ID는 설정 파일이나 CLAUDE.md 등 한 곳에서 관리하고, 릴리스 노트(release notes)를 정기적으로 확인하는 운영 방식을 갖추는 것이 안전합니다.

# Before（Opus 4.8까지는 동작했음）
response = client.messages.create(
model="claude-opus-5",
...

# After（effort를 high 이하로 낮추거나, thinking을 무효화하지 않음）
response = client.messages.create(
model="claude-opus-5",
...

# Before（Sonnet 4.6까지는 동작했음）
response = client.messages.create(
model="claude-sonnet-5",
...

# After（샘플링 파라미터와 budget_tokens를 삭제하고, adaptive thinking에 맡김）
response = client.messages.create(
model="claude-sonnet-5",
...

# Before（2026/7/24 이전에는 빠른 응답이 반환되었음）
response = client.messages.create(
model="claude-opus-4-7",
...

# After（Opus 5 또는 Opus 4.8로 전환）
response = client.messages.create(
model="claude-opus-5",
...

2026년 7월은 Claude Opus 5와 Sonnet 5라는 대규모 출시가 겹치면서, 그에 따른 파괴적 변경(breaking changes)도 많은 달이었습니다. 특히 다음 3가지 사항은 운영 환경에 미치는 영향이 크므로 우선적으로 확인하시기 바랍니다.

Opus 5: effort: xhigh/max와 thinking: disabled의 병용 불가 (400 에러) -
Sonnet 5: 수동 thinking 및 샘플링 파라미터 지정 불가, 토큰 수는 약 30% 증가 -
기한이 임박한 폐지 항목: Opus 4.1 (8/5 EOL), 레거시 Workbench 및 실험적 prompt tools API (8/17 폐지)

모두 "동작하던 코드가 갑자기 동작하지 않게 되는" 유형의 변경입니다. 모델 ID나 파라미터를 하드코딩하지 말고, 릴리스 노트를 정기적으로 체크하는 체계를 갖추어 두는 것을 권장합니다.