Claude Sonnet 5.5로 넘어가기: Anthropic 공식 빌딩 가이드 요약

Anthropic 개발자 가이드 정리

Claude Sonnet 5.5로 넘어가기: Anthropic 공식 빌딩 가이드 요약

Anthropic은 2026년 9월 28일, 자사 개발자 블로그(claude.dev)에 “Building with Claude Sonnet 5.5”라는 가이드를 올렸습니다. Addy Osmani가 작성한 이 글은 Sonnet 5에서 Sonnet 5.5로 모델 이름만 바꾼다고 마이그레이션이 끝나는 게 아니라고 말합니다. 이 글은 그 원문 내용을 그대로 정리한 것입니다.

언제 Sonnet 5.5, 언제 Opus 5.5를 쓸까

Claude 5.5 패밀리에서 Opus 5.5는 신중한 판단이 필요한 복잡한 작업용이고, Sonnet 5.5는 범위가 명확한 일상적인 작업용입니다. 가까운 시일 안에 대용량·저지연 작업을 위한 Claude Haiku 5.5도 합류할 예정입니다.

작업 유형	추천 모델
버그 수정, 빠른 기능 반복, 요구사항 검증 등 범위가 명확한 일상 코딩	Sonnet 5.5
대용량 일상 개발	Sonnet 5.5
한 페이지 문서, 다이어그램, 슬라이드 요약, 문서 편집, 스프레드시트 정리 등 디자인 감각이 필요한 작업	Sonnet 5.5
조사·리뷰·초안 작성처럼 반복 실행하는 정형화된 에이전트 작업	Sonnet 5.5
장시간에 걸친 에이전트형 코딩, 신중한 판단이 필요한 지식노동	Opus 5.5
가장 높은 수준의 지능이 필요한 난제	Opus 5.5

"Epic의 초기 테스트에서 Sonnet 5.5는 상위 티어 모델에 준하는 품질 기준을 통과했고, 시스템 설계 감사와 데이터 흐름 리뷰에서도 제 몫을 했습니다. 게임플레이 시스템 아키텍처를 위한 수만 줄의 코드를 관리하면서도 응답이 빨랐고, 여러 시간에 걸친 작업도 처리했으며, 덜 구체적인 프롬프트로도 결과물을 냈습니다." — Daniel Vogel, Epic Games COO

Anthropic의 프롬프팅 가이드는 “가장 까다로운 장기 작업에는 Opus 모델이 더 나은 선택”이라고 밝히고 있습니다.

가격

토큰당 가격은 Sonnet 5와 동일합니다. 다만 Sonnet 5.5는 같은 작업을 더 적은 토큰으로 끝내는 경우가 많아, 대부분의 작업에서 실제 비용은 최대 30%까지 줄어듭니다.

100만 토큰당	Sonnet 5.5	Opus 5.5
입력	$2	$4
출력	$10	$20
캐시 쓰기 (5분)	$2.50	$5
캐시 쓰기 (1시간)	$4	$8
캐시 읽기	$0.20	$0.20

미국 전용 추론(inference_geo: "us")은 표준가의 1.1배입니다. 이미지는 긴 변 기준 최대 2576픽셀의 고해상도 티어를 쓰기 때문에, 2000×1500 이미지 한 장은 Sonnet 4.6 대비 약 2.5배의 토큰을 소모합니다. 세부 묘사가 필요 없다면 전송 전에 이미지를 축소하는 게 좋습니다.

모델 세부 정보

항목	Sonnet 5.5
모델 ID	Claude API/AWS·Google Cloud·Microsoft Foundry의 Claude Platform은 `claude-sonnet-5-5`, Amazon Bedrock은 `anthropic.claude-sonnet-5-5`
컨텍스트 윈도우	100만 토큰, 베타 헤더 불필요
최대 출력	128,000 토큰(Message Batches API에서 베타 헤더 사용 시 최대 300,000)
지식 컷오프	2026년 6월
thinking(사고 과정)	기본적으로 켜짐(adaptive thinking); between_tools로 사전 사고를 끌 수 있음
Effort(노력) 단계	low, medium, high, xhigh, max
기본 effort	Claude API는 high, Claude Code는 medium
최소 캐시 가능 프롬프트	512 토큰(Sonnet 5는 1,024)

Sonnet 5에서 넘어올 때 막히는 지점 6가지

모델 ID를 claude-sonnet-5-5로 바꾸는 순간, 기존 코드가 곧바로 400 에러를 내는 지점이 여럿 있습니다. Claude Code를 쓴다면 /claude-api migrate this project to claude-sonnet-5-5 명령으로 내장된 Claude API 스킬이 이 작업을 대신 처리해줍니다.

1. thinking을 끄려면 between_tools를 써야 한다

Sonnet 5.5는 요청에 thinking 필드가 없으면 자동으로 adaptive thinking이 작동하고, 기존처럼 thinking={"type": "disabled"}를 보내면 400 에러가 납니다. 대신 새로운 between_tools 설정을 쓰면 도구 호출 사이에서만 사고하며, 전체 응답 시간은 그대로거나 더 빠릅니다. 단, low/medium/high effort에서만 동작하고 xhigh·max에서는 에러가 나며, display·budget_tokens 같은 다른 필드는 함께 보낼 수 없습니다.

2. 강제 tool_choice 대신 auto + strict 도구

tool_choice를 any나 특정 도구로 지정하면 토큰 카운팅 엔드포인트를 포함해 400 에러가 납니다. auto로 바꾸고 도구에 strict: true를 설정해 입력이 스키마를 따르게 해야 하며, 언제 그 도구를 쓸지는 프롬프트에서 지시합니다.

3. 대화는 append-only로 유지

thinking 블록은 모델과 대화에 종속됩니다. Sonnet 5.5는 Sonnet 5의 thinking 블록을 읽을 수 있어 대화 중간에 모델을 바꿔도 추론 맥락이 유지되지만, 다른 어떤 모델도 Sonnet 5.5의 thinking 블록은 읽지 못합니다.

4. computer use는 새 toolset으로

Claude API와 Google Cloud에서 컴퓨터 사용 기능은 이제 computer_toolset_20260801 타입으로만 지원되며, 기존 computer_20251124 선언은 400 에러를 냅니다. 다만 Amazon Bedrock은 여전히 기존 형식을 받아줍니다.

5. advisor 도구 조합 확인

advisor 도구를 쓸 때 Sonnet 5.5 실행 모델은 Opus 4.8, Opus 4.7, Sonnet 5를 advisor로 거부합니다. Opus 5.5, Opus 5, Sonnet 5.5 자신은 advisor로 허용되며, 이들의 조언은 암호화된 형태(advisor_redacted_result)로 돌아와 코드에서 직접 읽을 수 없습니다.

6. 도구 호출 사이의 메모는 thinking 블록에서 읽기

에러는 나지 않지만, 도구 호출 사이에 모델이 남기는 짧은 메모가 이제 thinking 블록(progress-update)으로 오기 때문에 기본 설정에서는 화면에 표시되지 않을 수 있습니다. thinking.display를 "updates"(베타) 또는 "summarized"로 설정해 읽어야 합니다.

튜닝 요령

Effort를 다시 조정하라. Effort 단계는 재조정되어서 Sonnet 5 때 쓰던 설정이 같은 양의 사고를 만들지 않습니다. 에이전트형 코딩·멀티스텝 도구 사용은 medium에서 시작해 어렵거나 긴 작업만 high로 올리고, 채팅처럼 지연에 민감한 작업은 medium이나 low에서 시작하는 것을 권장합니다.
Sonnet 5용 임시방편을 제거하라. "게으르게 굴지 마라" 같은 프롬프트 워크어라운드는 제거하고 평가를 다시 돌려야 합니다.
저효율(low effort)에서는 실제 검증을 요청하라. low effort에서는 변경 사항을 실제로 실행해보는 검증을 건너뛸 수 있어, 시스템 프롬프트에 "테스트·빌드·타입체크 등 실제 검증을 거친 뒤에만 완료로 보고하라"는 문구를 넣을 것을 권합니다.
캐시 활용을 늘려라. 최소 캐시 가능 프롬프트가 512 토큰으로 낮아져 짧은 시스템 프롬프트·도구 정의도 캐싱 대상이 됩니다. 단, 최상위 effort 값을 요청마다 바꾸면 캐시가 무효화됩니다.

거부(refusal)와 폴백

자체 행동 감사에서 Sonnet 5.5는 정합성·정직성 대부분의 지표에서 Sonnet 5와 같거나 더 나은 결과를 보였습니다. 또한 가장 강력한 모델들에 적용되던 것과 유사한 사이버보안 안전장치를 갖춘 첫 Sonnet 모델입니다. 요청이 거부되면 HTTP 200과 함께 stop_reason: "refusal"이 반환되고, cyber·bio·frontier_llm·reasoning_extraction·general_harms 다섯 카테고리 중 하나가 표시됩니다. 서버 측 폴백은 cyber와 frontier_llm 거부만 Sonnet 5로 재시도하며 나머지 세 카테고리는 재시도하지 않습니다.

어디서 쓸 수 있나

Claude API(claude-sonnet-5-5), Amazon Bedrock(anthropic.claude-sonnet-5-5), AWS·Google Cloud의 Claude Platform, Microsoft Foundry(Global Standard 배포에서만) 등에서 바로 사용할 수 있습니다. Claude Code에서는 v2.1.284부터 sonnet 별칭이 Sonnet 5.5를 가리키며 기본 medium effort로 동작하고, thinking을 끌 수 없고 fast 모드도 없습니다. 기본 모델은 여전히 Opus 5.5이므로 /model sonnet으로 전환해서 씁니다.

찰리초이 스토리 블로그

이 블로그 검색