effort 파라미터를 잘못 쓰고 있는 이유 - max~low 5단계 실전 선택 기준

토큰을 10배 쓰는데 답변이 나빠진다 — Anthropic 공식 가이드로 정리한 max~low 5단계 실전 선택 기준

---

문제 제기: effort를 높이면 항상 좋아질 것이라는 착각

Claude API를 쓰는 개발자들이 자주 하는 실수가 있다.
"성능을 최대화하려면 effort를 max로 설정하면 된다"는 생각이다.

Anthropic 공식 문서는 이것을 명확하게 경고한다.

• **max 설정은 일부 use case에서 성능을 높이지만
• token 사용량이 증가해도 수익이 감소하는 지점이 있으며,
• 과도한 thinking에 빠질 수 있다.

단순한 질문에 max effort를 설정하면

• 모델이 불필요하게 길게 생각하고,
• 토큰을 10배 쓰면서 오히려 답변이 이상해지는 경우가 생긴다.

 

effort는 지능 vs 토큰 비용의 트레이드오프를 조절하는 파라미터다.

 

모든 작업에 max를 쓰는 것은 모든 이동에 택시를 타는 것과 같다.

---

공감: "어느 effort를 써야 하는지 기준이 없다"

API를 사용하기 시작한 개발자들이 겪는 현실적인 어려움이다.
문서를 읽으면 5단계가 있다는 것은 알겠는데,
내 use case에 어느 것을 쓰면 되는지 기준이 없다.

 

챗봇인데 고객 문의 분류 작업은?
코딩 에이전트인데 단순 자동완성은?
복잡한 리서치 파이프라인은?

각 상황마다 다른 설정이 필요하고, 잘못 선택하면 비용이 수십 배 차이 난다.

 

Anthropic 공식 가이드가 제시하는 5단계 선택 기준을 정리한다.

---

해결: 5단계 선택 기준과 실전 설정

단계별 공식 권장 사항

effort	월 추천 상황	주의사항
max	가장 어려운 intelligence 작업, 테스트 단계	수익 체감, 과도한 thinking 가능
xhigh	코딩·에이전트 use case (1순위 권장)	가장 많은 도구 사용
high	대부분 intelligence-sensitive 작업 (최소 기준)	토큰-지능 균형
medium	비용 민감, 토큰 절약이 중요한 경우	지능 일부 희생
low	짧고 범위 한정된 작업, 지연시간 민감	복잡한 작업에서 under-thinking 위험

핵심 원칙: 먼저 xhigh나 high로 시작하고 내려가라

Anthropic의 권고는 명확하다.

"effort는 이 모델에서 중요하므로 업그레이드할 때 적극적으로 실험하라."

# 코딩·에이전트: xhigh 시작
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=64000,  # xhigh·high에서 64k부터 시작 권장
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "..."}],
)

# 비용 민감 챗봇: medium
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=8192,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "..."}],
)

low effort의 함정: 요청한 것만 한다

Anthropic 공식 문서에서 중요하게 강조하는 내용이다.

"Opus 4.8은 특히 low effort에서 요청을 엄격하게 해석한다.
하나의 항목에서 다른 항목으로 지시를 일반화하지 않으며,
요청하지 않은 것을 추론하지 않는다."

 

low와 medium에서 Claude는 요청된 것 안에서 작업 범위를 잡는다.
비용과 지연시간에는 좋지만 복잡한 작업에서는 under-thinking 위험이 있다.

 

복잡한 작업에서 low를 유지해야 한다면 프롬프트로 보완하면 된다:

이 작업은 다단계 추론을 포함합니다.
응답하기 전에 문제를 신중하게 생각해 주십시오.

---

도구 사용과 effort의 관계

Anthropic 공식 문서에서 다음과 같이 말한다.

"high 또는 xhigh effort 설정은
에이전트 검색과 코딩에서 도구 사용량을 상당히 증가시킨다."

 

웹 검색 도구를 쓰는데 모델이 도구를 안 쓰고 추론만 한다면?
effort를 높이는 것이 첫 번째 해결책이다.

# 모델이 웹 검색 도구를 쓰지 않는다면
# 프롬프트 수정 전에 effort 먼저 올려보라
output_config={"effort": "high"}  # medium → high

---

실전 use case별 권장 설정

Use Case	effort	thinking	max_tokens
코딩 에이전트 (자율 실행)	xhigh	adaptive	64k
복잡한 리서치 파이프라인	high	adaptive	64k
일반 챗봇·고객 지원	medium	disabled	8k
분류·요약·단순 추출	low	disabled	4k
지연시간 최우선 서비스	low	disabled	2k

사례
코딩 에이전트에 medium effort를 쓰다가 복잡한 리팩터링 작업에서 실패율이 높았다면
xhigh로 변경하면 도구 호출이 상당히 늘어나고 완료율이 올라간다.
비용은 증가하지만 재실행 비용을 포함하면 오히려 절감되는 효과를 얻는다.

---

max output token과 effort의 관계

Anthropic 공식 가이드가 명시한다.

"max 또는 xhigh effort로 Opus 4.8을 실행할 때
모델이 서브에이전트와 도구 호출에서 생각하고 행동할 충분한 공간을 가질 수 있도록
큰 max output token 예산을 설정하라.
64k 토큰에서 시작하고 거기서 조정하라."

 

64k를 설정하지 않으면
모델이 thinking 도중 max_tokens에 걸려 잘리는 경우가 생긴다.

---

마치며

effort 파라미터는 "높을수록 좋다"가 아니다.
작업 복잡도와 비용 제약에 맞는 수준을 찾는 것이 핵심이다.

 

Anthropic의 권고는 명확하다.

• 코딩·에이전트는 xhigh,
• intelligence-sensitive는 최소 high,
• 나머지는 작업에 맞게 내려가라.
• 그리고 업그레이드할 때마다 이 파라미터를 적극적으로 실험하라.

---

📎 참고 출처

• Anthropic 공식 Prompting Best Practices: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
• Anthropic effort 가이드: https://platform.claude.com/docs/en/build-with-claude/effort