Claude 모델 교체 전에 effort 기본값을 확인한 이유

이 저장소의 자동화는 모델을 부를 때 추론 강도를 코드에 적어 둡니다. scripts/proofread.py와 rewrite_narration.py는 low, rewrite_titles.py는 medium입니다. 앞선 검수 비용 기록에서 추론 토큰이 상한에 함께 잡히는 일을 겪은 뒤부터, GPT 호출은 값을 생략하지 않는 쪽으로 굳었습니다.

그런데 Claude 쪽은 달랐습니다. Claude API로 effort를 넘기는 코드는 아직 없었고, 모델 교체 후보를 살피다가 기본값 칸을 확인하지 않았다는 사실이 남았습니다. 2026-10-16에 공식 모델 개요와 Effort 문서를 열어 보니, 같은 요청이라도 모델 이름만 바꾸면 사고 강도가 달라질 수 있는 구조였습니다.

먼저 결론부터

• Claude의 effort는 low, medium, high, xhigh, max의 5단계입니다.
• 대부분 모델의 기본값은 high지만, Opus 5.5와 Haiku 5.5는 medium이 기본값입니다.
• Opus 5에서 effort를 생략하던 요청을 Opus 5.5로 옮기면, 문서 기준으로 한 단계 낮은 강도로 실행됩니다.
• 기본값과 같은 effort를 명시해도 생략한 요청과 동작은 같습니다.

scripts/proofread.py        low
rewrite_narration.py        low
rewrite_titles.py           medium

• Sonnet 5.5는 이전 Sonnet과 같은 effort 이름이라도 사고량이 같지 않아, 기존 설정을 그대로 옮기지 말고 다시 측정해야 합니다.
• Opus 5.5는 적응형 사고가 항상 켜져 있습니다. thinking을 disabled로 보내면 effort 값과 관계없이 400 오류가 납니다.
• 공식 문서의 모범 사례도 effort를 명시적으로 설정하는 쪽입니다.

기본값 표에서 멈춘 자리

처음에는 가격과 모델 이름만 비교하려 했습니다. 같은 프롬프트를 보내고 단가가 낮은 모델을 고르면 된다고 생각했던 흐름입니다. 하지만 모델 개요 표에는 가격뿐 아니라 effort 항목에도 다른 변수가 있었습니다.

Fable 5.1은 기본이 high이고 Sonnet 5.5도 high인데, Opus 5.5와 Haiku 5.5는 medium으로 시작합니다. 이름만 보면 새 모델이니 이전 모델보다 더 세게 돌 것처럼 생각하기 쉬웠는데, 기본 동작은 그렇게 단순하지 않았습니다.

여기서 멈췄습니다.

문서는 Opus 5와 그 이전 Opus의 기본값이 high였다고 적으므로, Opus 5에서 effort 없이 호출하던 코드를 Opus 5.5로 바꾸면 요청은 medium으로 들어갑니다. 프롬프트도 호출 코드도 그대로입니다. 모델이 받는 행동 신호만 달라지는 경우입니다.

비용표만으로 설명되지 않았습니다

effort는 텍스트 응답에만 적용되지 않습니다. 도구 호출 인자와 사고 토큰을 포함해 응답의 모든 토큰에 영향을 줍니다. 그래서 모델 단가뿐 아니라 같은 모델을 어떤 effort로 실행했는지도 따로 봐야 합니다.

이번에는 Claude API에서 실제 비용을 측정하지 않았습니다. 기본값 차이가 비용에 얼마나 나타나는지도 확인하지 못했습니다. 다만 기본 effort를 보지 않은 모델 교체라면, 나중에 비용이나 응답 품질이 달라졌을 때 단가만 원인으로 잡을 수 없다는 점은 분명했습니다.

GPT 호출 코드에는 이미 low와 medium이 박혀 있습니다. 반면 Claude 호출은 아직 비어 있습니다. 같은 저장소 안에서 모델마다 기준이 달랐던 셈입니다.

같은 effort 이름도 그대로 옮길 수 없었습니다

기본값만 고정하면 끝날 줄 알았습니다. 그런데 Sonnet 5.5 문서에서 또 멈췄습니다. Sonnet 5.5는 Sonnet 5와 effort 단계를 다르게 재조정했으므로, 같은 medium이나 high가 같은 사고량을 뜻하지 않는다고 안내합니다.

즉 이전 Sonnet에서 잘 맞던 값을 이름만 보고 옮기는 방식은 근거가 없습니다. 문서도 기존 설정을 이전하지 말고 새로 측정하라고 적습니다. effort는 엄격한 토큰 예산이 아니라 모델에 보내는 행동 신호이므로, 낮은 단계에서도 어려운 문제는 생각합니다.

지원 범위도 모델별로 같지 않았습니다. max를 지원하는 모델이라도 xhigh를 지원하지 않을 수 있으니, 최상위 값을 넓게 열어 두고 모델만 바꾸는 설정도 안전하지 않았습니다.

캐시와 thinking 조건도 함께 남겼습니다

요청 사이에서 상위 effort 값을 바꾸면 프롬프트 캐시가 새로 시작됩니다. 비용 기록을 읽을 때 입력이 같아 보이는데도 결과가 달라지는 이유가 될 수 있는 조건입니다.

Fable 5.1, Opus 5.5, Opus 5, Sonnet 5.5, Haiku 5.5에는 메시지 단위 effort 변경 베타가 있으며, 베타 헤더를 쓰면 캐시를 유지할 수 있습니다. 다만 이 기능을 쓸지 여부와 별개로, 기본값에 맡긴 호출과 명시한 호출을 같은 범주로 기록하면 안 되겠다고 남겼습니다.

Opus 5.5는 더 좁은 조건이 있습니다. 적응형 사고를 끌 수 없습니다. thinking: disabled 요청은 400 오류로 끝납니다. effort만 추가하면 되는 모델이라고 보고 기존 요청 옵션을 그대로 붙였다면, 호출 자체가 실패할 수 있는 자리였습니다.

이 저장소의 다음 Claude 호출에는 모델명과 effort를 함께 적을 생각입니다. 기본값과 같은 값을 적어도 동작은 달라지지 않으므로, 생략하지 않고 명시해 두는 편이 기록에 유리합니다. 모델을 바꾼 뒤 응답이 달라졌을 때 무엇이 달라졌는지 되짚을 수 있는 기준도 마련됩니다.