Claude Code에서 Sonnet 5.5 사용하기: 모델·effort·권한 확인

Claude Code에서 Sonnet 5.5를 명시적으로 선택하려면 해당 ID를 지원하는 공급사에서 새 세션은 claude --model claude-sonnet-5-5, 기존 세션은 /model claude-sonnet-5-5를 사용하세요. 먼저 클라이언트 버전과 계정의 모델 권한을 확인해야 합니다. Anthropic의 현재 문서는 Claude Code v2.1.284 이상을 요구합니다.

클라이언트가 모델을 인식하는 것, 공급사가 모델을 제공하는 것, 계정이 사용 권한을 갖는 것은 별개입니다. 이 안내는 2026년 9월 29일 Claude Code 모델 설정 문서와 대조했습니다. 모든 구독이나 타사 엔드포인트에서 접근할 수 있다고 확인한 것은 아닙니다.

모델 확인과 선택

터미널에서 다음 명령을 사용합니다.

claude --version
claude update
claude --model claude-sonnet-5-5 --effort medium

claude update는 설치된 클라이언트를 변경합니다. 조직이 설치를 관리한다면 해당 소프트웨어 관리 절차를 따르세요. 기존 대화형 세션에서는 다음을 입력합니다.

/model claude-sonnet-5-5
/status

명령이 성공했다고 가정하지 말고 표시된 모델과 공급사를 확인하세요. 생성 답변의 자기소개를 실제 응답 모델의 증거로 쓰지 마세요. 클라이언트 상태와 응답 메타데이터가 더 유용합니다.

짧은 별칭 sonnet은 편리하지만 공급사와 클라이언트 버전에 따라 의미가 달라집니다. 현재 문서는 Anthropic API에서 Sonnet 5.5로 매핑하지만 일부 클라우드 공급사의 별칭은 이전 Sonnet 모델을 가리킵니다. 전체 모델 이름은 의도를 분명히 하지만 해당 공급사가 지원하는 ID와 접근 경로를 써야 한다는 조건은 그대로입니다.

기본값만 바꾸면 충분하지 않은 이유

Claude Code 기본 모델이 반드시 최신 Sonnet인 것은 아닙니다. 현재 문서는 여러 계정·공급사 범주에서 Opus 5.5를 기본값으로 안내합니다. Sonnet은 직접 선택해야 합니다. 조직이 모델을 제한하면 공개 가이드와 선택 목록이 다를 수 있습니다.

ANTHROPIC_DEFAULT_SONNET_MODEL 같은 환경 변수도 별칭의 대상 모델을 바꿀 수 있습니다. 설정을 수정하기 전에 사용자, 프로젝트, 관리 설정을 확인하세요. 실험을 되돌릴 수 있도록 기존 값을 남기고, 한 세션을 고치려고 팀 전체의 공급사 설정을 덮어쓰지 마세요.

재현 가능한 테스트에는 명시적 선택을 사용한 뒤 영구 기본값으로 둘지 결정합니다. 한 번 시험하기 위해 모든 저장소나 에이전트 정의를 변경할 필요는 없습니다.

작업에 맞는 effort 선택

Sonnet 5.5 API의 기본 effort는 high입니다. 반면 Claude Code 모델 설정 문서는 그 클라이언트에서 Sonnet 5.5의 기본값을 medium으로 설명합니다. 서로 다른 진입점에 관한 설명이므로 혼용하면 안 됩니다.

요구사항이 명확한 코드 변경이라면 medium이 문서에 따른 합리적인 출발점입니다. 작업과 결과가 뒷받침할 때만 높이세요. 계정 제한 안에서 대화형 /effort 또는 실행 시 --effort를 사용합니다. 관리되는 effort 상한 때문에 요청보다 낮은 값이 실제로 적용될 수 있으니 확인 가능한 적용 설정을 기록하세요.

Effort 가이드는 높은 이름이 더 나은 결과를 보장하지 않는 이유를 설명합니다. 분리된 브랜치, 명확한 합격 기준, 검토 가능한 diff부터 준비하세요. 모델은 도구 실행 권한이 필요하고, 병합 전에는 변경 내용을 검토해야 합니다.

구독 접근과 API 과금 구분

Claude 구독 로그인과 API 키는 다른 접근 경로입니다. 조직이 Claude Code 구독 접근을 비활성화했다는 메시지는 계정 정책에 따른 차단이며 Sonnet 장애의 증거가 아닙니다. 관리자에게 승인된 접근 경로를 확인하고 관리 제한을 우회하지 마세요.

이 글을 준비하면서 실행한 로컬 Claude Code v2.1.281은 해당 조직 접근 메시지를 반환했고 Sonnet 작업을 실행하지 못했습니다. 문서의 최소 버전보다도 낮았습니다. 따라서 이 시도로 성공적인 모델 테스트, 속도 결과, 비용 측정을 주장하지 않습니다. 위 명령은 문서로 확인한 사용 절차입니다.

승인된 API 경로가 있다면 요청에는 API 요금이 적용됩니다. 구독을 가지고 있다는 이유로 무료가 되지는 않습니다. 시험 전 정확한 엔드포인트, 모델, 계정, 현재 요금을 확인하세요. 공급사 요금표 계산은 Sonnet API 비용 가이드에 정리했습니다.

코드를 맡기기 전에 기준 상태 기록하기

운영 자격 증명이나 무관한 미커밋 변경이 없는 작은 저장소를 사용합니다. Claude Code를 열기 전에 현재 commit을 기록하고 기존 테스트를 실행합니다. 그렇지 않으면 기존 실패를 Sonnet 회귀로 오해하거나 다른 변경을 모델 성과로 셀 수 있습니다. 아래는 로컬 상태 확인 명령입니다. 테스트는 프로젝트의 실제 명령을 쓰고 임의의 프레임워크를 설치하지 않습니다.

git status --short
git rev-parse HEAD
claude --version
claude auth status

인증 출력은 로컬에서 확인하고 기록에는 필요한 계정 유형과 승인 상태만 남깁니다. 자격 증명이나 전체 환경 변수를 블로그·issue·프롬프트에 붙이지 마세요. 조직이 설치와 인증을 관리한다면 승인된 관리자 절차를 먼저 따릅니다. 클라이언트 업데이트로 조직의 구독 사용 금지를 해제할 수는 없습니다.

승인된 업데이트 뒤에 claude --version을 다시 실행합니다. update 명령을 내렸다고 shell이 쓰는 실행 파일이 바뀌었다는 뜻은 아닙니다. 여러 설치본이 있으면 오래된 바이너리가 경로 앞에 남을 수 있습니다. 버전이 그대로라면 command -v claude를 확인하세요. 특히 터미널과 IDE가 다르게 동작하면 경로와 버전을 함께 기록합니다.

기본값을 의도치 않게 바꾸지 않는 모델 선택

현재 모델 설정 문서의 우선순위는 세션 내 선택, 시작 플래그, ANTHROPIC_MODEL, settings의 model, 기본 모델 설정 순입니다. 관리 제한은 여전히 적용됩니다. 더 높은 우선순위의 선택이 있으면 설정 파일 하나를 수정해도 결과가 바뀌지 않을 수 있습니다.

격리된 시험은 지원되는 전체 ID와 명시적 effort로 시작합니다.

claude --model claude-sonnet-5-5 --effort medium

세션 안에서 /status와 모델 선택기를 확인합니다. 현재 문서는 /model <name>을 직접 입력하면 사용자 설정에 저장되어 다음 세션에도 영향을 준다고 설명합니다. 현재 세션만 바꾸려면 /model을 열고 세션 전용 동작을 사용합니다. 문서상 기본 키는 s입니다. 저장 동작을 확인하지 않고 직접 /model 명령을 임시 변경이라고 설명하면 안 됩니다.

영구 변경이라면 이전 값을 적고 현재 세션뿐 아니라 새 세션도 확인합니다. 한 번만 시험하려면 시작 플래그를 쓰고 공유 저장소 설정은 건드리지 않는 편이 좋습니다. 별칭은 제공자의 권장 버전을 따라가고 전체 ID는 시험에서 요청한 버전을 명시합니다. 둘 다 게이트웨이가 실제 제공한 모델의 증거는 아니므로 가능한 클라이언트·제공자 메타데이터를 확인합니다.

첫 작업에는 범위와 검증 가능한 정답이 필요하다

첫 코딩 작업은 “프로젝트 개선”보다 실패 테스트가 있는 작은 산술 버그가 적합합니다. 다음은 편집용 합성 연습 fixture이며, 기사 준비 중 Sonnet이 만든 패치가 아닙니다.

# expenses.py: intentionally incorrect practice function
def total(rows):
    return sum(row["unit_price"] for row in rows)

$4.50짜리 노트 3권과 $1.25짜리 펜 2개에서 잘못된 함수는 $5.75를 반환합니다. 각 행에서 수량을 곱한 뒤 합쳐야 하므로 정답은 $16.00입니다. 함수 옆에 아래 테스트를 저장합니다.

# test_expenses.py
from decimal import Decimal
from expenses import total

def test_total():
    rows = [
        {"quantity": 3, "unit_price": Decimal("4.50")},
        {"quantity": 2, "unit_price": Decimal("1.25")},
    ]
    assert total(rows) == Decimal("16.00")

def test_empty():
    assert total([]) == 0

if __name__ == "__main__":
    test_total()
    test_empty()

모델을 호출하기 전에 python3 test_expenses.py를 실행하면 첫 assertion이 실패해야 합니다. 실패하지 않으면 파일과 import 경로를 확인하세요. 의도한 시작 상태가 아직 만들어지지 않은 것입니다. traceback의 세부 문구보다 잘못된 계산을 확인합니다.

오류만 던지지 말고 완전한 작업을 제공합니다.

expenses.py의 total(rows)를 수정하세요. 각 행은 quantity와 unit_price의 곱이며,
기존 Decimal 입력을 유지합니다. 빈 입력은 0이어야 합니다.
expenses.py만 수정하고 테스트 변경이나 의존성 설치는 하지 마세요.
python3 test_expenses.py를 실행하고 실제 결과, 원인, 수정한 줄,
아직 검증하지 않은 가정을 보고하세요. commit, push, 외부 서비스 접근은 금지합니다.
실행하지 않은 테스트를 실행했다고 말하지 마세요.

이 프롬프트는 범위와 독립적으로 계산 가능한 정답을 정하지만 모델의 준수를 보장하지는 않습니다. diff에서 테스트 약화와 무관한 수정을 검사합니다. 범위는 유효한 행과 빈 입력뿐입니다. 음수 수량·누락 키·잘못된 데이터 처리는 별도 제품 요구사항으로 정해야 하며 작은 수정에 임의 규칙을 끼워 넣으면 안 됩니다.

로컬 증거로 변경 승인하기

세션 뒤에 git diff -- expenses.py test_expenses.py를 보고 직접 테스트를 실행합니다. 최종 답변의 “통과”보다 실제 프로세스 종료 코드와 출력이 강한 증거입니다. 두 행의 산술과 테스트 파일 미변경을 확인합니다. assertion을 $5.75로 바꿔 녹색으로 만들었다면 버그가 남아 있으므로 거절해야 합니다.

시작 commit, 클라이언트 버전, 제공자·모델, 요청 effort, 테스트 명령·결과, diff, 검토 결정을 보관합니다. 모델 응답 전에 계정 정책으로 막혔다면 “접근 차단”이지 “코딩 실패”가 아닙니다. 도구 권한 거절과 잘못된 패치도 구분합니다. 올바른 패치를 제안했어도 테스트를 실행하지 않았다면 독립 검증 전까지 “제안됨, 미검증”입니다.

실제 저장소에서는 관련 회귀 테스트와 타입·빌드 검사로 확장합니다. 두 테스트로 일반적인 코딩 성능을 추론하지 마세요. 이 연습은 접근 경로·파일 수정·승인 절차가 함께 작동하는지 확인한 뒤 더 큰 작업으로 가기 위한 것입니다.

이전 설정으로 복귀하기

시작 플래그만 썼다면 세션을 종료하고 다음 세션의 상태를 확인합니다. 저장된 기본값을 바꿨다면 지원 선택기나 설정 경로로 원래 값을 복구하고 검증합니다. 관리 설정은 유지합니다. 자신이 만든 임시 연습 파일만 삭제하고, 시험을 되돌리려고 공유 저장소를 무작정 reset 또는 clean 하지 않습니다.

결과는 접근 차단, 모델 도달 후 승인 가능한 패치 없음, 패치 제안됐지만 미검증, 독립 검증을 통과한 패치의 네 가지로 나눕니다. 그래야 설치·권한 문제를 모델 벤치마크로 잘못 보고하거나 자신감 있는 설명을 작동하는 코드로 오인하지 않습니다.

실제 실패 증상부터 확인하기

404를 전체 장애의 증거로, 429를 구독 취소의 증거로 보지 마세요. 민감한 정보를 지운 오류 본문, 시각, 클라이언트 버전을 저장합니다. 지원 요청에 토큰, 전체 환경 변수 덤프, 비공개 저장소 문맥을 게시하지 마세요.

네이티브 요청 변경은 Sonnet 5.5 API 마이그레이션 체크리스트, 이전 모델에서 바꿀지에 대한 판단은 Sonnet 5와 5.5 비교를 참고하세요.