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

중급

2026년 7월 22일 Anthropic은 effort를 Claude Managed Agents의 모델 설정에 통합하면서, Messages API가 조용히 5단계까지 확장해 온 이 제어 장치의 마지막 매듭을 지었습니다. 초반 2026년 블로그 글을 따라 messages.create 최상위에 effort="high"를 계속 붙이고 있다면, 요청은 유효해 보이지만 Claude는 여러분이 생각하는 필드를 존중하지 않을 수 있습니다 — 파라미터는 이제 output_config 안에 있고, API는 모델 카드에 문서화된 단계만 인정합니다.

이 글은 실전 튜닝 가이드입니다. effort가 요청 안 어디에 들어가는지, 5단계가 실제로 무엇을 바꾸는지(thinking 깊이만이 아니라 tool call 횟수도), 놀랄 만한 모델별 기본값, 그리고 예산을 조용히 폭발시키는 단 하나의 함정 — 대화 중간에 effort를 바꾸면 프롬프트 캐시가 무효화된다는 사실을 다룹니다.

What you'll learn

effort 필드를 올바른 위치에 두기 — Messages API에서는 output_config 안에, Managed Agents에서는 model 오브젝트 안에, Claude Code에서는 /effort 또는 CLAUDE_CODE_EFFORT_LEVEL로
모델별 시작 단계 고르기 — API 기본값은 high지만 권장 시작 effort는 모델에 따라 다름(Sonnet 5는 high, Sonnet 4.6은 medium, Opus 4.7/4.8은 xhigh, Fable 5는 high)
effort는 모든 토큰에 영향을 미친다는 점 이해하기 — 텍스트, tool call, (활성 시) thinking까지 — 즉 effort를 낮추면 장황함뿐 아니라 tool call 횟수도 줄어듦
캐시 함정 피하기 — 캐시된 대화 안에서 effort를 바꾸면 프롬프트 캐싱이 무효화되어 청구액이 조용히 두 배가 될 수 있음
Claude Code의 effort 표면 알기 — /effort, ultrathink(한 턴), ultracode(xhigh + 상시 멀티에이전트 권한), CLAUDE_CODE_EFFORT_LEVEL 환경 변수 우선순위

다섯 단계 (그리고 "ultracode"의 자리)

2026년 7월 22일 기준 API가 받아들이는 effort 값은 다섯 개입니다:

단계	하는 일	언제 쓰나
`low`	가장 효율적. 약간의 능력 감소와 함께 상당한 토큰 절감. tool call 감소, 짧은 확인 응답, 서론 없음.	간단한 분류, 대용량 워크로드, 채팅, 지연에 민감한 UX, 좁은 범위의 서브에이전트
`medium`	균형형. high 대비 적당한 토큰 절감.	속도·비용·품질 균형이 필요한 에이전트 작업, 비용 절감을 위한 high에서의 단계 하향
`high`	고성능. 파라미터를 생략한 것과 동일.	복잡한 추론, 어려운 코딩, 속도보다 품질이 중요한 에이전트 작업
`xhigh`	장기 작업을 위한 확장 능력. high보다 의미 있게 많은 토큰 사용을 예상.	장시간(30분 이상) 에이전트·코딩 작업, 수백만 토큰 예산, 여러 파일에 걸친 깊은 리팩터
`max`	절대 최고 능력, 토큰 소비 제한 없음.	진짜 프런티어 문제 전용. 구조화된 출력 작업에서는 과다 사고할 수 있음.

max는 effort를 지원하는 모든 모델에서 공통입니다. xhigh는 더 최근에 도입되었고 Fable 5, Mythos 5, Opus 4.8, Opus 4.7, Sonnet 5에서만 지원됩니다. 그보다 오래된 effort 지원 모델(Sonnet 4.6, Opus 4.6, Opus 4.5)은 max는 이해하지만 xhigh는 이해하지 못합니다.

Pro tip

effort='high'는 파라미터를 생략한 것과 정확히 같은 동작을 만듭니다 — 캐시된 대화에서 '명시성을 위해' 굳이 설정하지 마세요. 어떤 요청에는 넣고 어떤 요청에는 빼면 캐시가 무효화됩니다.
'ultracode'는 여섯 번째 단계가 아닙니다. xhigh + 대화 중 시스템 메시지로 부여되는 Claude Code의 멀티에이전트 워크플로 상시 실행 권한의 조합입니다. API는 다섯 값만 받습니다.

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

2026년 초의 effort 파라미터 소개 글은 최상위 필드로 보여줍니다:

# 현재 모델에서는 WRONG — 조용히 무시되거나 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는 thinking 제어가 아니다

두 번째로 큰 오해입니다. Effort는 thinking이 켜져 있든 아니든 작동하며, thinking이 아닌 응답 부분에 Claude가 쓰는 토큰을 바꿉니다:

Tool call. effort가 낮을수록 → tool call이 줄어듭니다. Claude는 작업을 단일 호출로 합치고, 선택적 탐색을 건너뛰고, 서론 없이 실행으로 갑니다.
텍스트 길이. effort가 낮을수록 → 출력이 압축됩니다. tool call 이후 상세 요약 대신 짧은 확인. 코드 주석 감소.
Thinking 깊이(thinking이 켜져 있을 때). effort가 낮을수록 → 쉬운 프롬프트에서는 thinking을 아예 건너뜁니다. 진짜 어려운 문제에서는 여전히 사고하지만 덜 합니다.

이 마지막 지점이 중요합니다: low effort에서도 Claude는 증명 문제에는 사고합니다. 과제가 그것을 요구하기 때문입니다. Effort는 행동 신호이지 엄격한 토큰 예산이 아닙니다. 하드 상한을 기대하지 마세요.

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

Pro tip

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

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

이 파라미터를 지원하는 모든 모델에서 API 기본값은 high입니다. 하지만 Anthropic이 권장하는 시작 effort는 모델마다 다르며, 이 불일치가 팀이 과지출 또는 과소지출하는 지점입니다.

Guided walkthrough1 of 6

Sonnet 5는 API와 Claude Code 모두에서 기본이 high이고, 권장 사항도 일치합니다. 가장 어려운 코딩·에이전트 작업에서만 xhigh로 올리세요. 비용 절감으로 medium으로 낮추세요 — Sonnet 5 medium은 Sonnet 4.6 high와 비슷합니다. 채팅이나 코딩이 아닌 지연 민감 워크로드에는 low를 쓰세요.

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

프롬프트 캐싱은 캐시 읽기를 표준 입력 가격의 약 10%에 제공합니다. 같은 대화 안에서 요청 간에 effort를 바꾸면 캐시가 무효화됩니다 — 모델을 바꿀 때와 정확히 같은 방식으로요. 긴 컨텍스트에서 이것은 $0.03 캐시 읽기와 전체 히스토리에 대한 $0.30 정가 재읽기의 차이 — 이후 모든 후속 턴마다입니다.

Pro tip

effort는 워크로드 사이에서 다양화하되, 캐시된 대화 안에서는 하지 마세요. 대화 시작 시 단계를 정하고 /clear까지 일정하게 유지하세요.
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

직관을 보정하려면 같은 프롬프트를 세 단계로 실행하고 출력 형태를 비교하세요:

Tuning-calibration prompt (run at 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 문자열 연결, 헤더의 미검증 사용자 입력). 미묘한 로직 버그는 놓침. 도구가 있으면 tool call 1-2회. 짧은 출력. 빠름.
high — 전체 분석. 미묘한 것을 포함해 대부분의 취약점을 잡음. 관련 파일을 읽기 위한 여러 표적 tool call. 구조화된 발견. 대부분 팀이 여기서 멈춤.
xhigh — 철저함. 새로운 공격 벡터와 심층 방어를 고려. low/high가 건드리지 않은 인접 파일을 읽음. 훨씬 많은 tool call. 의미 있게 많은 토큰 사용.

여러분 코드베이스에서 high와 xhigh가 같은 발견을 내놓는다는 평가 결과가 있다면 high로 배포하세요. xhigh의 가치는 작업이 반복적 tool call과 상세한 탐색으로부터 이득을 볼 때 구체적으로 드러납니다 — 바로 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 field guide를 참고하세요.

확실히 붙잡기

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

1 / 8

Check yourself

0/6

다음 중 Messages API에서 유효한 effort 값이 아닌 것은?
20턴의 캐시된 대화를 실행 중입니다. 21번째 턴에서 effort를 high에서 xhigh로 바꾸면 어떻게 되나요?
Claude Code에서 세션의 effort 설정을 건드리지 않고 바로 다음 턴만 더 깊이 추론하게 하고 싶습니다. 가장 좋은 방법은?
Opus 4.8을 effort='xhigh'로 돌리는데, 긴 thinking 후 응답이 stop_reason='max_tokens'로 계속 잘립니다. 가장 유력한 해결책?
Claude Managed Agents 에이전트를 만들 때(2026년 7월 업데이트) effort는 어디에 들어가나요?
어떤 변화가 Sonnet 5 'medium'을 Sonnet 4.6 'high'와 가장 비슷하게 동작하게 만드나요?

Sources & further reading

Anthropic — Effort (build-with-claude/effort) — 다섯 단계, output_config.effort, 모델별 권장에 대한 권위 있는 참조
Anthropic — Thinking (build-with-claude/thinking) — effort가 적응형 thinking과 어떻게 상호작용하는지, 어떤 제어에 언제 손을 뻗을지
Anthropic Platform release notes — 22 July 2026 entry — Managed Agents effort 출시 및 같은 날 배포된 웹훅/세션 시딩 변경
Prompting Claude Sonnet 5 — calibrating effort and thinking depth — Sonnet 5 effort 스케일 이동과 xhigh를 언제 쓸지
Anthropic — Task budgets — 전체 에이전트 루프를 위한 권고 토큰 예산, 장시간 실행에서 effort의 보완재
AILmanac — Extended Thinking & Effort — 이 페이지가 전제로 하는 도입 프레이밍
AILmanac — Claude Sonnet 5: The Field Guide — 마이그레이션과 재보정 이야기
AILmanac — Prompt caching — 대화 중 effort 변경을 그토록 비싸게 만드는 캐시 경제학

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

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

올바른 effort 배치 — Messages API

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

Effort는 thinking 제어가 아니다​

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

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

Claude Code — CLI 표면​

튜닝 워크스루 — 하나의 프롬프트, 세 개의 effort​

Tuning-calibration prompt (run at low, high, xhigh)

Sonnet 5는 보정을 이동시켰다 — 단계를 맹목적으로 이식하지 말라​

확실히 붙잡기​

Check yourself

Sources & further reading​

다섯 단계 (그리고 "ultracode"의 자리)

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

Effort는 thinking 제어가 아니다

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

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

Claude Code — CLI 표면

튜닝 워크스루 — 하나의 프롬프트, 세 개의 effort

Sonnet 5는 보정을 이동시켰다 — 단계를 맹목적으로 이식하지 말라

확실히 붙잡기

Sources & further reading