본문으로 건너뛰기

effort 튜닝: 5단계, 모델별 기본값, 그리고 캐시의 함정

중급

2026년 7월 22일, Anthropic은 effort를 Claude Managed Agents의 모델 설정에 통합해, Messages API가 조용히 다섯 단계로 늘려 온 제어를 한 바퀴 돌려 마무리했습니다. 2026년 초의 블로그 글에서 messages.create 최상위에 effort="high"를 복사해 쓰고 있다면, 요청은 유효해 보이지만 Claude가 여러분이 생각하는 필드를 따르지 않을 수 있습니다. 이 파라미터는 이제 output_config 안에 있고, API는 모델 카드에 문서화된 단계만 적용합니다.

이 글은 실전 튜닝 가이드입니다. 요청에서 effort가 실제로 어디에 들어가는지, 다섯 단계가 정말 무엇을 하는지(사고 깊이만이 아니라 도구 호출 횟수를 바꿉니다), 놀라운 모델별 기본값, 그리고 지출을 조용히 부풀리는 한 가지 함정, 즉 대화 도중에 effort를 바꾸면 프롬프트 캐시가 무효화된다는 점을 다룹니다.

What you'll learn
  • effort 필드를 올바르게 배치하기 — Messages API에서는 output_config 안에, Managed Agents에서는 model 객체 안에, Claude Code에서는 /effort 또는 CLAUDE_CODE_EFFORT_LEVEL로
  • 모델별 시작 단계 고르기 — high는 대부분의 모델에서 API 기본값이지만 Opus 5.5와 Haiku 5.5는 medium이 기본값이며, 권장 시작 effort도 또 다르다 (에이전트형 코딩은 Sonnet 5.5 medium, Sonnet 4.6 medium, Opus 4.7/4.8 xhigh, Fable 5.1 high)
  • effort가 텍스트, 도구 호출, (활성 시) 사고를 포함한 모든 토큰에 영향을 준다는 점 이해하기 — effort를 낮추면 장황함뿐 아니라 도구 호출 횟수도 줄어든다
  • 캐시의 함정 피하기 — 한 대화 안에서 effort를 바꾸면 프롬프트 캐싱이 무효화되어 청구액이 조용히 두 배가 될 수 있다
  • Claude Code의 effort 기능 알기 — /effort, ultrathink(한 턴), ultracode(xhigh + 상시 멀티에이전트 허용), 환경 변수 CLAUDE_CODE_EFFORT_LEVEL 덮어쓰기

다섯 단계 (그리고 "ultracode"의 위치)​

2026년 7월 22일 기준 effort 척도에서 API가 받는 값은 다섯 가지입니다.

단계하는 일언제 쓰나
low가장 효율적. 성능은 다소 줄지만 토큰을 크게 절약. 도구 호출이 적고, 확인은 간결하며, 서두가 없음.단순 분류, 대용량 워크로드, 채팅, 지연에 민감한 UX, 범위가 좁은 작업을 맡는 서브에이전트
medium균형형. high 대비 토큰을 적당히 절약.속도·비용·품질의 균형이 필요한 에이전트형 작업, high에서 비용을 의식해 한 단계 내릴 때
high높은 성능. 파라미터를 생략한 것과 같음 — 단, 기본값이 medium인 Opus 5.5와 Haiku 5.5를 제외한 모든 모델에서.복잡한 추론, 어려운 코딩, 속도보다 품질이 중요한 에이전트형 작업
xhigh장기 작업을 위한 확장된 성능. high보다 토큰 사용량이 눈에 띄게 많을 것으로 예상.장시간(30분 이상) 에이전트형·코딩 작업, 수백만 토큰 규모의 예산, 여러 파일에 걸친 깊은 리팩터링
max절대적 최대 성능, 토큰 지출 제약 없음.진짜 최전선의 문제에만. 구조화된 출력 작업에서는 과하게 생각할 수 있음.

max도 xhigh도 모든 모델에서 쓸 수 있는 것은 아닙니다. 출시 전에 모델에 맞는 단계인지 확인하세요. xhigh는 Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Opus 5.5, Opus 5, Opus 4.8, Opus 4.7, Sonnet 5.5, Sonnet 5, Haiku 5.5에서 지원됩니다. max는 이들 전부에 Mythos Preview, Opus 4.6, Sonnet 4.6을 더한 범위입니다. Opus 4.5는 effort를 지원하지만 상위 두 단계는 지원하지 않습니다. Anthropic의 표현으로는 "Not every model that supports max supports xhigh."

Pro tip
  • effort를 모델 자체의 기본값으로 설정하면 파라미터를 생략한 것과 정확히 같은 동작이 됩니다 — 대부분의 모델에서는 'high', Opus 5.5와 Haiku 5.5에서는 'medium'입니다. 캐시된 대화에서 "명시하려고" 설정하지 마세요. 일부 요청에는 필드를 쓰고 다른 요청에는 쓰지 않으면 캐시가 무효화됩니다.
  • 'ultracode'는 여섯 번째 단계가 아닙니다. xhigh에 더해, 대화 도중의 시스템 메시지로 부여되는, Claude Code가 멀티에이전트 워크플로를 시작할 수 있는 상시 허용입니다. API가 받는 값은 다섯 가지입니다.

대부분의 블로그 글이 틀리는 필드 구조​

2026년 초의 effort 파라미터 설명은 최상위 필드를 보여 줍니다.

# WRONG on current models — silently ignored or 400
client.messages.create(
    model="claude-opus-4-8",
    effort="medium",
    ...
)

현재 API는 effort를 output_config 객체 안에 두고, messages/model과 같은 수준으로 전달합니다.

올바른 effort 배치 — Messages API

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
  model="claude-opus-4-8",
  max_tokens=4096,
  output_config={"effort": "medium"},
  messages=[{
      "role": "user",
      "content": "Analyse the trade-offs between microservices and monoliths."
  }],
)

print(response.content[0].text)

Claude Managed Agents(2026년 7월 22일 변경)에서는 에이전트 생성 시 effort를 에이전트의 model 객체 안에 넣습니다. 세션이 설정하는 것이 아니라 에이전트 버전이 설정합니다.

올바른 effort 배치 — Managed Agents (POST /v1/agents)

# Effort travels with the versioned agent config,
# not the per-run session. Every session pinned to
# this agent version runs at xhigh.

POST https://api.anthropic.com/v1/agents
{
"name": "code-reviewer",
"model": {
  "id": "claude-opus-4-8",
  "effort": "xhigh"
},
"system_prompt": "You review pull requests for security issues.",
"tools": [...],
"mcp_servers": [...]
}

effort는 사고 제어가 아니다​

이것이 두 번째 큰 오해입니다. effort는 사고가 활성화되어 있든 아니든 동작하며, 사고가 아닌 응답 부분에서 Claude가 쓰는 토큰을 바꿉니다.

  • 도구 호출. effort가 낮을수록 호출이 줄어듭니다. Claude는 작업을 한 번의 호출로 묶고, 선택적 탐색을 건너뛰며, 서두 없이 바로 행동합니다.
  • 텍스트 길이. effort가 낮을수록 출력이 간결해집니다. 도구 호출 뒤에 상세한 요약 대신 짧은 확인만 하고, 코드 주석도 줄어듭니다.
  • 사고 깊이(사고가 켜져 있을 때). effort가 낮을수록 쉬운 프롬프트에서는 사고를 아예 건너뛰고, 정말 어려운 프롬프트에서는 여전히 사고하되 덜 합니다.

마지막 항목이 중요합니다. low effort에서도 증명 문제에서는 과제가 요구하므로 Claude가 사고합니다. effort는 엄격한 토큰 예산이 아니라 행동 신호입니다. 하드 상한을 기대하지 마세요.

thinking 파라미터와 effort 파라미터는 서로 다른 질문에 답합니다. thinking은 Claude가 사고 블록을 생성하느냐를 정합니다. effort는 적응형 사고가 켜져 있을 때 Claude가 얼마나 자주, 얼마나 깊이 사고하는지를 포함해 응답 전체에 얼마나 많은 노력이 들어가는지를 정합니다. effort="adaptive"를 넘기는 것은 흔한 실수입니다. adaptive는 사고 모드이지 effort 단계가 아닙니다.

Pro tip

Opus 4.5 — effort를 지원하는 유일한 확장 사고 전용 모델 — 에서는 effort 와 budget_tokens를 함께 설정합니다. 작업에 맞는 effort 단계를 고른 다음, 추론 깊이에 맞춰 사고 토큰 예산을 정하세요. effort를 지원하는 다른 모든 모델은 적응형 사고를 쓰며 budget_tokens를 받지 않습니다.

팀을 놀라게 하는 모델별 시작점​

API 기본값은 effort를 지원하는 대부분의 모델에서 high입니다 — 하지만 전부는 아닙니다. Opus 5.5와 Haiku 5.5는 기본값이 medium입니다. 게다가 Anthropic의 권장 시작 effort는 모델마다 다르고, 팀이 과소·과대 지출을 하는 곳이 바로 이 불일치입니다.

Guided walkthrough1 of 9
  1. Opus 5.5는 medium이 기본값인 유일한 Opus이므로, effort를 생략한 요청은 Opus 5에서 같은 코드를 돌릴 때보다 한 단계 낮게 실행됩니다. 마이그레이션 후 품질이 떨어졌다면 가장 먼저 이것을 확인하세요. 적응형 사고는 항상 켜져 있고 끌 수 없으므로(thinking: {type: 'disabled'}는 모든 단계에서 400 반환), effort가 추론량과 요청 비용을 정하는 유일한 수단입니다. 설정을 그대로 가져오지 말고 effort를 새로 스윕하세요 — 같은 단계에서 Opus 5보다 턴당 더 많이 사고합니다.

캐시의 함정 — 청구액을 조용히 두 배로 만드는 것​

프롬프트 캐싱은 캐시 읽기를 표준 입력 가격의 일부(대부분의 모델에서 10분의 1, 최신 모델에서는 그보다 낮음 — Pricing 참조)로 제공합니다. 같은 대화에서 요청 사이에 최상위 output_config.effort를 바꾸면 모델을 바꿀 때와 똑같이 캐시가 무효화됩니다. 최상위 effort는 렌더링된 프롬프트를 형성하므로, 새 값이면 일치하는 캐시된 접두사가 없습니다. 긴 컨텍스트에서는 이후 모든 후속 턴마다 전체 기록을 정가로 다시 읽는 셈입니다.

탈출구: 메시지 단위 effort (베타)​

최신 모델은 캐시를 잃지 않고 effort를 바꿀 수 있게 해 줍니다. output_config.effort에 새 단계를 담은, content가 빈 role: "system" 메시지를 추가하면, 그 앞의 모든 것이 바이트 단위로 동일하게 유지되므로 캐시된 접두사가 계속 일치합니다.

캐시 미스 없이 대화 도중 effort 바꾸기

# Beta header required:
#   anthropic-beta: mid-conversation-output-config-2026-07-01

{
"model": "claude-fable-5-1",
"max_tokens": 4096,
"output_config": {"effort": "high"},
"messages": [
  {"role": "user", "content": "Plan a migration from SQLite to PostgreSQL."},
  {"role": "assistant", "content": "1. Export... 2. Create schema... 3. Import."},
  {"role": "system", "content": [], "output_config": {"effort": "low"}},
  {"role": "user", "content": "Summarize the plan in one sentence."}
]
}

2026년 10월 19일 기준 지원 현황: Claude API와 Google Cloud에서는 Fable 5.1, Mythos 5.1, Opus 5.5, Opus 5, Sonnet 5.5, Haiku 5.5에서 동작하고, Amazon Bedrock에서는 Fable 5.1, Mythos 5.1, Opus 5.5만 해당합니다. 베타 헤더 mid-conversation-output-config-2026-07-01이 필요하며, 없으면 메시지 단위 output_config는 400 messages.N.output_config: Extra inputs are not permitted를 반환합니다. 헤더가 있어도 지원되지 않는 모델(Fable 5 포함)에서는 400 output_config.effort requires a model that supports per-turn effort; this model does not가 나옵니다.

사고가 고정되어 있으면 턴 단위 effort 변경을 거부하는 모델이 둘 있습니다. thinking: {"type": "between_tools"}인 Sonnet 5.5와 thinking: {"type": "disabled"}인 Haiku 5.5는 메시지 단위 단계가 현재 적용 중인 단계와 다르면 400을 반환합니다. 이 경우 effort를 바꾸려면 적응형 사고를 쓰세요.

그 밖의 모든 경우에는 예전 규칙이 여전히 유효합니다 — 단계를 하나 골라 유지하세요.

Pro tip
  • 메시지 단위 effort가 없는 모델에서는 캐시된 대화 '안'이 아니라 워크로드 '사이'에서 effort를 바꾸세요. 대화 시작 때 단계를 정하고 /clear 할 때까지 일정하게 유지하세요.
  • 둘 다 가능하더라도 최상위 변경보다 메시지 단위 effort를 선호하세요. Fable 5.1에서는 최상위 전환이 모델을 덜 안정적으로 이끌기도 합니다. 이전 응답이 옛 단계에서 쓰였고 모델이 그것들과 일관성을 유지하려는 경향이 있기 때문입니다.
  • Claude Code에서 세션 중 /effort는 모델을 바꾸는 것과 같습니다 — 다음 턴에 큰 캐시 미스가 난다고 예상하세요.
  • 한 턴만 깊이를 올리고 싶다면 /effort xhigh 대신 Claude Code의 'ultrathink'(한 턴짜리 더 깊은 추론)를 쓰세요. 세션 설정을 바꾸지 않아도 됩니다.
  • 세션의 나머지 동안 올려야 한다면 일찍 하세요. 3번째 턴의 전환은 싸지만, 30번째 턴의 전환은 30턴 분량의 컨텍스트를 정가로 다시 읽습니다.

따름정리: 캐시된 일부 요청에는 effort="high"를 명시하고 다른 요청에는 생략해도 똑같이 캐시가 무효화됩니다. 둘은 동작으로는 같지만 텍스트로는 다르기 때문입니다. 하나의 규칙(항상 설정 또는 항상 생략)을 정해 유지하세요.

Claude Code — CLI에서의 사용​

Claude Code는 effort를 대화형 명령, 실행 플래그, 환경 변수로 제공합니다 (가장 높은 우선순위가 이기며, 역순으로 적용).

# In-session (interactive slider, or direct)
/effort
/effort xhigh
/effort auto           # reset to model default

# At launch
claude --effort low

# Environment (overrides everything else)
CLAUDE_CODE_EFFORT_LEVEL=high claude

effort 단계는 아니지만 비슷하게 동작해서 알아 둘 만한 명령이 둘 있습니다.

  • ultrathink — 세션 effort를 바꾸지 않는 한 턴짜리 더 깊은 추론 추가분입니다. 이후 모든 턴의 캐시를 무효화하지 않고 다음 턴만 더 열심히 생각하게 하고 싶을 때 쓰세요.
  • ultracode — 세션 전체를 xhigh로 설정하고 동시에 Claude Code에 멀티에이전트 워크플로를 시작할 수 있는 상시 허용을 부여합니다(대화 도중의 시스템 메시지로). API에는 ultracode 값이 없습니다 — xhigh와 오케스트레이션 허용을 합친 CLI 편의 기능입니다.

기억할 지속성 규칙: low, medium, high, xhigh는 한 번 설정하면 Claude Code 세션을 넘어 유지됩니다. max는 현재 세션에만 적용되므로 다음에 다시 적용해야 합니다.

튜닝 실습 — 프롬프트 하나, effort 셋​

감각을 맞추기 위해 같은 프롬프트를 세 단계로 실행하고 출력의 모양을 비교해 보세요.

튜닝 보정용 프롬프트 (low, high, xhigh로 실행)

Task: Review this pull request for security issues.

<pr_diff>
[paste a real diff — 300+ lines, multi-file, at least one auth-touching change]
</pr_diff>

Report: severity-tagged findings + a one-line fix per finding.
Do not restate what the diff does.

대략 이렇게 기대하세요.

  • low — 명백한 고위험 문제(SQL 문자열 연결, 헤더의 검증되지 않은 사용자 입력)는 잡습니다. 미묘한 로직 버그는 놓칩니다. 도구가 있으면 1~2회 호출. 출력이 짧고 빠릅니다.
  • high — 전체 분석. 미묘한 것을 포함해 대부분의 취약점을 잡습니다. 관련 파일을 읽기 위한 여러 번의 표적 도구 호출. 구조화된 결과. 대부분의 팀이 여기서 멈춥니다.
  • xhigh — 철저함. 새로운 공격 벡터와 심층 방어까지 고려합니다. low/high가 건드리지 않은 인접 파일까지 읽습니다. 도구 호출이 훨씬 많고 토큰 사용량도 눈에 띄게 많습니다.

평가에서 high와 xhigh가 여러분의 코드베이스에서 같은 결과를 낸다면 high로 출시하세요. xhigh의 가치는 작업이 반복적인 도구 호출과 상세한 탐색의 덕을 볼 때 나타나며, 바로 그때 Anthropic이 권장하는 경우입니다.

Sonnet 5는 보정을 옮겼다 — 단계를 그대로 옮기지 말 것​

Sonnet 4.6을 high로 쓰다가 Sonnet 5로 마이그레이션했다면, 같은 단계를 유지할 때 Sonnet 5는 Sonnet 4.6이 max에서 쓰던 양에 가깝게 소비합니다. Sonnet 5의 effort 척도는 이동했습니다. Anthropic 자신의 지침은 Sonnet 5 medium ≈ Sonnet 4.6 high입니다. effort를 조정하지 않고 트래픽을 재생했다면 요청당 비용 차이를 확인해 볼 가치가 있습니다. 마이그레이션 전체 이야기는 Sonnet 5 필드 가이드를 보세요.

굳히기​

Enter 또는 스페이스 키를 눌러 카드를 뒤집습니다. 좌우 화살표 키로 카드를 이동할 수 있습니다.용어가 표시되었습니다.
1 / 9

스스로 점검하기

0/7
  1. Messages API에서 유효한 effort 값이 아닌 것은?
  2. 캐시된 20턴 대화에서 21번째 턴에 최상위 effort를 high에서 xhigh로 바꿨습니다. 어떻게 되나?
  3. Opus 5.5를 쓰면서 effort 파라미터를 완전히 생략했습니다. 어떤 단계로 실행되나?
  4. Claude Code에서 세션의 effort 설정은 건드리지 않고 '다음' 턴만 더 열심히 추론하게 하고 싶습니다. 가장 좋은 방법은?
  5. Opus 4.8에서 effort='xhigh'일 때, 긴 사고 뒤에 응답이 계속 stop_reason='max_tokens'로 잘립니다. 가장 가능성 높은 해결책은?
  6. Claude Managed Agents 에이전트를 만들 때(2026년 7월 업데이트) effort는 어디에 들어가나?
  7. Sonnet 5의 'medium'이 'high'의 Sonnet 4.6과 가장 비슷하게 동작하게 만드는 변화는?

출처 및 더 읽을거리​

다음​