Quick Reference

effort는 Claude API 요청 하나가 응답, 도구 호출, thinking에 얼마나 많은 token을 쓸지 조절하는 신호입니다. 기본값은 high이며, 이 값은 effort를 생략한 것과 같습니다. 낮은 비용이 우선이면 low 또는 medium부터 평가하고, 장기 코딩·도구 탐색은 지원 모델에서 xhigh나 max를 실제 평가 결과가 있을 때만 올립니다.

response = client.messages.create(
    model="지원 모델 ID",
    max_tokens=8_192,
    messages=[{"role": "user", "content": "변경 범위와 테스트 위험을 분석해 줘."}],
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
)

적용 범위와 동작

effort는 Claude 앱의 대화 길이나 Claude Code의 권한 모드를 설정하는 값이 아닙니다. Messages API와 지원 플랫폼에서 요청별로 전달하는 output_config.effort입니다. 낮은 effort는 설명뿐 아니라 tool call과 함수 인자에 쓰는 token도 줄이는 경향이 있으므로, 단순한 답변은 빨라질 수 있지만 여러 단계 탐색·재시도·검증이 필요한 작업의 완결성은 낮아질 수 있습니다.

adaptive thinking에서는 Claude가 요청 난이도에 따라 thinking block을 쓰는 빈도와 깊이를 조절합니다. effort는 그 전체 작업량을 조절하고, thinking은 thinking 사용 방식 자체를 조절합니다. 둘을 같은 비용 상한으로 보면 안 됩니다. max_tokens는 한 요청의 출력 한도이고, timeout·요청 수·재시도 제한은 호출자가 별도로 둡니다.

낮은 effort
  -> 적은 응답·thinking·tool token을 목표로 한다.

높은 effort
  -> 더 많은 탐색과 설명을 허용한다.

어느 경우에도
  -> 정답, 비용, 호출 횟수를 고정 보장하지 않는다.

고르는 법

같은 입력, 같은 도구, 같은 성공 기준으로 최소 low·medium·기본값을 비교합니다. 작업이 성공했는지만 보지 말고 정확도, 누락된 단계, tool call 수, 총 token, 지연 시간, 사람 검토 시간을 함께 기록합니다. 특히 작은 subagent나 분류 단계는 low가 맞을 수 있지만, 최종 결정을 내리는 agent까지 낮추면 앞 단계의 비용 절감이 재시도 비용으로 돌아올 수 있습니다.

Prompt caching을 쓰는 대화에서는 effort를 시작 시점에 정하고 유지합니다. effort 값도 렌더링된 프롬프트에 영향을 주므로, 다음 요청에서 값을 바꾸면 같은 지시문이라도 이전 cache prefix를 재사용하지 못할 수 있습니다.

자주 틀리는 부분

피해야 할 선택
- 최신 모델과 이전 모델의 지원 effort level을 같다고 가정한다.
- high effort를 긴 최종 답변 보장으로 해석한다.
- cache hit가 중요한 대화에서 요청마다 effort를 바꾼다.

권장 선택
1. 모델별 지원 level과 기본값을 공식 문서에서 확인한다.
2. 대표 입력으로 품질·비용·지연을 함께 평가한다.
3. 호출 한도와 오류 처리는 API 클라이언트에서 별도로 강제한다.