Claude Code /effort 설정: 작업별 추론 강도와 maxEffortLevel 상한 정하기

파일 이름 변경처럼 범위가 분명한 작업에는 깊은 추론이 필요하지 않습니다. 반면 여러 모듈에 걸친 오류 분석이나 설계 비교는 원인과 제약을 더 오래 검토해야 합니다. 작업에 비해 effort가 너무 높으면 시간과 토큰을 더 쓰고, 너무 낮으면 중요한 조건을 놓칠 수 있습니다.

Claude Code의 /effort는 작업별 추론 강도를 고르는 명령입니다. 2.1.267부터 지원하는 maxEffortLevel을 함께 설정하면 /effort, --effort, Skill, 서브에이전트가 요청할 수 있는 최대 단계를 제한할 수 있습니다.[1][2]

아래 예시는 Linux에서 @anthropic-ai/claude-code@2.1.267을 격리 실행한 결과입니다. 공식 문서의 동작과 실제 시작 경고를 구분하고, 로그인 없이 확인할 수 없는 응답 시간과 토큰 수는 비교 대상에서 제외합니다.

/effort가 조절하는 것

Effort level은 모델에 고정된 생각 토큰 수를 직접 입력하는 기능이 아닙니다. Anthropic 공식 문서는 이를 adaptive reasoning의 깊이를 조절하는 단계로 설명합니다. 모델은 선택한 effort 범위 안에서 현재 작업의 복잡도를 판단하고, 필요한 추론의 양과 깊이를 조절합니다.[2]

이 때문에 effort는 다음 세 가지와 구분해야 합니다.

high를 low로 바꾼다고 이미 찬 컨텍스트가 비워지지는 않습니다. 새 세션을 열어도 계정의 주간 한도가 초기화되지 않는 것과 같습니다. 컨텍스트와 계정 사용량의 차이는 Claude Code·Codex CLI 사용량 확인에서 별도로 정리했습니다.

낮은 단계는 짧고 범위가 분명한 작업에서 시간과 토큰을 줄이고, 높은 단계는 복잡한 문제를 더 깊게 검토하도록 유도합니다.[2] 다만 같은 high라도 모델마다 내부 척도가 같다는 뜻은 아닙니다. effort 단계는 모델별로 보정되며, 지원 단계도 모델에 따라 달라집니다.[2]

작업 복잡도에 맞는 effort 고르기

현재 공식 문서에 표시되는 단계는 low, medium, high, xhigh, max입니다. 활성 모델이 어떤 단계를 지원하는지에 따라 실제 선택지는 줄어들 수 있습니다. 지원하지 않는 높은 단계를 요청하면 Claude Code는 그 모델이 사용할 수 있는 가장 가까운 하위 단계로 낮춥니다.[2]

/effort 메뉴에는 이 다섯 단계와 별도로 ultracode가 표시될 수 있습니다. ultracode는 effort 단계가 아니라 xhigh 추론과 동적 워크플로를 결합한 Claude Code 설정이므로 이 글의 단계·상한 비교에서는 제외합니다.[2]

기본값은 대부분의 작업에 맞춰져 있습니다. 공식 문서도 max에 대해 어려운 과제의 성능을 높일 수 있지만 수익 체감이 있고 과도하게 생각하기 쉽다고 안내합니다.[2] “중요한 작업이니 무조건 max”보다 “이 작업에서 더 깊은 추론이 실제로 필요한가”를 먼저 묻는 편이 낫습니다.

단계는 코드 줄 수보다 불확실성의 범위를 기준으로 고릅니다. 수정할 파일과 성공 조건이 정해져 있다면 변경량이 커도 medium으로 시작할 수 있습니다. 반대로 짧은 오류 하나라도 원인 후보가 설정, 네트워크, 권한, 버전에 걸쳐 있다면 high 이상이 적합합니다. 낮은 단계에서 시작해 원인 후보가 넓어지거나 조건 누락이 확인될 때 한 단계 올리되, 답변 길이만으로 추론 정확도를 판단하지 않습니다.

/effort 적용 범위 선택하기

대화 중 다음 명령을 입력하면 선택 화면이 열립니다.

/effort

단계를 직접 지정할 수도 있습니다.

/effort low
/effort medium
/effort high
/effort xhigh
/effort max

대화형 화면에서 low부터 xhigh까지 고른 뒤 Enter로 확정하면 활성 모델의 기본값으로 저장되고 이후 세션에도 적용됩니다. s 키로 확정하면 현재 세션에만 적용됩니다. 세션 전용 선택은 Claude Code 2.1.257 이상에서 지원합니다.[2]

max는 예외입니다. 공식 문서 기준 /effort max는 현재 세션에만 적용되며 모델별 기본값으로 저장되지 않습니다. 저장된 모델별 값을 지우려면 다음 명령을 사용합니다.

/effort auto

/effort auto는 활성 모델의 modelSettings.<모델>.effortLevel을 지우며, 최상위 effortLevel은 그대로 둡니다. 이후 값은 남아 있는 최상위 설정, 일부 모델의 기본 effort 유지 동작, 모델 기본값을 포함한 정상 우선순위에 따라 다시 결정됩니다.[2][3]

새 세션을 시작할 때 한 번만 지정하려면 --effort가 더 명확합니다.

claude --effort low
claude --effort high
claude --effort max

현재 적용값은 세션 헤더의 모델명 옆 with low effort 같은 문구로 확인할 수 있습니다. 시작할 때와 값이 바뀔 때는 푸터에도 잠시 표시됩니다.[2] 선택 화면에서 커서만 옮긴 상태를 적용 완료로 보지 말고, 확정 메시지와 세션 헤더를 함께 봅니다.

maxEffortLevel은 기본값이 아닌 상한

maxEffortLevel은 Claude Code 2.1.267에 추가됐습니다. 최상위에 두면 모든 모델에 공통 상한을 걸고, modelSettings 안에 두면 특정 모델의 상한을 정합니다.[1][3]

{
  "maxEffortLevel": "medium"
}

이 설정은 세션을 medium으로 시작하게 만드는 기본값이 아닙니다. 사용자는 여전히 low와 medium을 고를 수 있지만, high, xhigh, max를 요청하면 실제 실행은 medium으로 낮아집니다.

상한이 적용되는 경로도 넓습니다.

• 대화형 /effort와 /model 선택 화면

• 시작 옵션 --effort

• CLAUDE_CODE_EFFORT_LEVEL 환경 변수

• Skill과 서브에이전트 frontmatter의 effort

• 모델 자체의 기본 effort

클라이언트가 요청을 보내기 전에 상한을 적용하므로 Anthropic API뿐 아니라 Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry 같은 provider에도 적용됩니다. 여러 설정 범위에서 상한을 정하면 가장 낮은 상한이 남습니다. 프로젝트 로컬에서 xhigh로 바꿔도 조직 관리형 설정이 medium이면 올릴 수 없습니다.[1][3]

상한 값에는 max도 쓸 수 있습니다.

{
  "maxEffortLevel": "max"
}

여기서 max는 “모든 작업을 max로 실행”이 아니라 이 설정 소스에서는 제한하지 않음에 가깝습니다. effortLevel: "max"와 혼동하면 안 됩니다.

기본값과 세션값 저장 위치

effort 값은 모델별 기본값, 공통 기본값, 세션 시작값, 환경 변수로 지정할 수 있습니다. 적용 범위가 서로 다르므로 먼저 역할을 구분합니다.

• modelSettings.<모델>.effortLevel: 대화형 /effort에서 저장한 모델별 기본값

• 최상위 effortLevel: 해당 설정 소스에 모델별 저장값이 없는 모델에 적용할 공통 기본값. 단, Fable 5·Opus 4.8·Opus 4.7의 기본 effort 유지 상태가 끝나지 않았다면 이 값보다 유지된 모델 기본값이 먼저 적용될 수 있음

• --effort: 실행한 세션에만 적용하는 시작값

• CLAUDE_CODE_EFFORT_LEVEL: 해당 실행 환경에서 가장 우선하는 명시값

같은 설정 파일 안에서는 modelSettings.<모델>.effortLevel이 최상위 effortLevel보다 우선합니다. 여러 파일 사이에서는 각 모델에 대해 모델별 값이나 최상위 effortLevel 중 하나를 지정한 가장 높은 우선순위 파일이 최종 값을 결정합니다. 예를 들어 관리형 설정의 최상위 effortLevel은 사용자 설정에 저장된 모델별 값보다 우선합니다. 여러 범위의 값 가운데 가장 낮은 값을 합성하는 maxEffortLevel 상한 규칙과는 다릅니다.[3]

최상위 기본값을 직접 넣는 예시는 다음과 같습니다.

{
  "effortLevel": "medium"
}

모델별로 다르게 저장하면 다음 모양이 됩니다.

{
  "modelSettings": {
    "claude-opus-5": {
      "effortLevel": "high"
    },
    "claude-sonnet-5": {
      "effortLevel": "medium"
    }
  }
}

effortLevel과 모델별 effortLevel에 저장할 수 있는 값은 low, medium, high, xhigh입니다. max는 이 두 키의 지속값으로 받지 않습니다.[2][3]

설정 파일은 적용 범위에 맞게 고릅니다.

처음 시험할 때는 개인 전역 파일을 바로 고치기보다 별도 JSON을 --settings로 연결하면 되돌리기 쉽습니다.

claude --settings /tmp/claude-effort-test.json --effort high

설정을 바꿨는데 결과가 예상과 다르면 현재 로드된 범위를 /status로 확인하고, 파일 오류는 claude doctor로 점검합니다.

공통 상한에 모델별 예외 두기

모든 모델을 medium까지 제한하되 특정 모델만 제한하지 않으려면 같은 설정 소스에서 모델별 값을 덮어쓸 수 있습니다.

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-opus-5": {
      "maxEffortLevel": "max"
    }
  }
}

같은 파일 안에서는 claude-opus-5의 모델별 상한이 최상위 medium을 대신합니다. 그러나 다른 범위의 더 낮은 상한까지 없애지는 않습니다. 예를 들어 조직 관리형 설정이 Opus를 high로 제한했다면 프로젝트 파일의 max 예외보다 낮은 high가 적용됩니다.[3]

반대로 특정 모델만 더 낮추는 구성도 가능합니다.

{
  "maxEffortLevel": "xhigh",
  "modelSettings": {
    "claude-opus-5": {
      "maxEffortLevel": "low"
    }
  }
}

modelSettings에는 Claude Code가 인식하는 정식 모델명을 사용합니다. 공식 문서는 modelSettings의 정식 이름이 날짜 접미사, [1m], 인식된 provider별 ID에도 대응한다고 설명합니다.[3]

상한 적용값 확인하기

기존 설치를 바꾸지 않고 2.1.267 동작을 확인하려면 npm 패키지를 버전까지 지정해 실행합니다.[4]

npx -y @anthropic-ai/claude-code@2.1.267 --version

버전이 다음과 같이 표시되는지 확인합니다.

2.1.267 (Claude Code)

최상위 medium 상한

/tmp/claude-effort-cap-medium.json에 다음 설정을 저장합니다.

{
  "maxEffortLevel": "medium"
}

이 설정 파일을 연결한 뒤 max를 요청합니다.

npx -y @anthropic-ai/claude-code@2.1.267 \
  --settings /tmp/claude-effort-cap-medium.json \
  --effort max

2.1.267에서는 환영 화면을 열기 전에 다음 경고가 나타납니다.

Effort 'max' exceeds the cap for claude-opus-5[1m] set by your settings or organization; using 'medium'.
Welcome to Claude Code v2.1.267

Effort 'max'는 요청값이고 using 'medium'은 상한을 적용한 결과입니다. 프로세스가 시작됐는지만 보지 말고 이 두 값을 함께 확인합니다.

모델별 low 상한

이번에는 최상위 상한을 xhigh로 두고 claude-opus-5만 low로 제한합니다.

{
  "maxEffortLevel": "xhigh",
  "modelSettings": {
    "claude-opus-5": {
      "maxEffortLevel": "low"
    }
  }
}

같은 방식으로 max를 요청하면 다음 경고가 나타납니다.

Effort 'max' exceeds the cap for claude-opus-5[1m] set by your settings or organization; using 'low'.
Welcome to Claude Code v2.1.267

같은 설정 파일에서는 모델별 low가 최상위 xhigh를 대신하므로 실제 적용값은 low입니다.

모델별 예외

최상위 상한은 medium으로 유지하면서 claude-opus-5만 max로 예외 처리할 수도 있습니다.

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-opus-5": {
      "maxEffortLevel": "max"
    }
  }
}

이 설정으로 --effort max를 요청하면 앞선 두 예시와 달리 상한 초과 경고가 나타나지 않습니다. 같은 설정 파일의 모델별 max가 해당 모델에 최상위 medium 상한을 적용하지 않기 때문입니다.[3] 다만 경고가 없다는 사실만으로 조직 관리형 상한도 없다고 단정할 수는 없습니다. 로그인한 세션에서 헤더의 실제 effort를 다시 확인합니다.

같은 과제로 단계 비교하기

응답 품질과 시간을 비교하려면 단계마다 질문을 바꾸지 말아야 합니다. 다음처럼 작은 테스트 저장소와 성공 조건을 고정합니다.

이 프로젝트에서 실패하는 단위 테스트의 원인을 찾고 최소 수정으로 고쳐줘.
조건:
1. 테스트 코드는 바꾸지 말 것
2. 수정 전 원인을 설명할 것
3. 수정 후 같은 테스트를 실행할 것
4. 변경 파일과 남은 위험을 요약할 것

low, medium, high를 각각 새 세션에서 실행하고 아래 항목만 기록합니다.

한 번의 결과로 “high가 몇 배 좋다”는 결론을 내리면 안 됩니다. 모델 응답에는 변동이 있고, 캐시·네트워크·저장소 상태도 시간에 영향을 줍니다. 같은 커밋에서 새 세션을 열고 여러 번 반복해야 비교 의미가 생깁니다.

상한 실습에서는 모델 답변보다 요청값과 적용값의 차이가 핵심입니다. 다음 세 줄을 남기면 됩니다.

requested: max
cap: medium
applied: medium

선택한 effort가 적용되지 않을 때

Claude Code 버전 확인하기

maxEffortLevel은 2.1.267부터 지원합니다. 먼저 버전을 확인하고 세션을 완전히 종료한 뒤 업데이트합니다.

claude --version
claude update
claude --version

모델이 지원하는 단계 확인하기

모든 모델이 xhigh나 max를 지원하는 것은 아닙니다. 지원하지 않는 단계를 요청하면 사용할 수 있는 하위 단계로 내려갈 수 있습니다. 모델명과 헤더의 실제 적용값을 함께 기록합니다.[2]

로드된 설정 범위 확인하기

사용자 파일, 프로젝트 공유 파일, 프로젝트 로컬 파일, 관리형 설정이 함께 로드될 수 있습니다. 상한은 높은 우선순위 파일 하나만 보고 끝나지 않고 여러 범위의 가장 낮은 값이 적용됩니다. /status에서 설정 출처를 확인합니다.

기본값과 상한 구분하기

effortLevel은 기본값이고 maxEffortLevel은 제한입니다. 일반적인 effort 해석에서는 아래 설정이 기본 요청값을 low로 두고 상한을 high로 제한합니다. 다만 Fable 5·Opus 4.8·Opus 4.7의 기본 effort 유지 상태가 아직 끝나지 않았다면 시작값은 이 설명과 다를 수 있으므로 세션 헤더에서 실제 값을 확인해야 합니다.

{
  "effortLevel": "low",
  "maxEffortLevel": "high"
}

항상 high로 실행한다는 뜻이 아닙니다.

Skill과 서브에이전트의 요청값 확인하기

Skill이나 서브에이전트 frontmatter도 별도 effort를 요청할 수 있습니다. 세션이 medium이어도 특정 작업이 더 높은 단계를 요구할 수 있지만, maxEffortLevel 상한은 이 요청에도 적용됩니다.[2][3] 설치된 Skill의 노출 비용과 사용 기록을 정리하려면 Claude Code 스킬 관리를 함께 볼 수 있습니다.

개인과 팀의 권장 설정

개인은 모델 기본값이나 medium에서 시작하고, 범위가 분명한 반복 수정만 low로 낮추는 방식이 무난합니다. 원인 후보가 넓은 디버깅과 설계 비교에는 high나 xhigh를 쓰고, max는 성공 조건과 검증 방법이 분명한 작업에서 세션 단위로 선택합니다.

팀은 .claude/settings.json이나 관리형 설정에 상한을 둘 수 있습니다. 다만 상한만 정하지 말고 높은 단계를 허용할 작업과 예외 검토 기준도 함께 문서화해야 합니다. 실행 후에는 답변 길이가 아니라 세션 헤더, 상한 경고, 테스트 결과, 종료 코드, diff로 결과를 확인합니다.

Effort를 높여도 잘못된 명령이나 코드가 자동으로 안전해지지는 않습니다. 삭제·덮어쓰기·배포처럼 영향이 큰 변경은 실행 범위와 되돌릴 방법을 먼저 확인합니다. 자세한 검토 기준은 AI가 만든 코드를 그대로 믿지 않는 습관에서 볼 수 있습니다.

/effort의 목적은 모든 작업을 최대 강도로 돌리는 데 있지 않습니다. 작업의 불확실성에 맞춰 필요한 만큼 생각하게 하고, 상한으로 과도한 선택을 막은 뒤 실제 적용값을 확인하는 것이 핵심입니다.

참고 자료

[1] https://github.com/anthropics/claude-code/releases/tag/v2.1.267 — Claude Code v2.1.267 release
[2] https://code.claude.com/docs/en/model-config — Claude Code model configuration, Adjust effort level
[3] https://code.claude.com/docs/en/settings-reference — effortLevel, modelSettings, maxEffortLevel settings reference
[4] https://www.npmjs.com/package/@anthropic-ai/claude-code/v/2.1.267 — npm package 2.1.267