# Claude Code effort 설정과 차이: Opus 5.5 기본값 medium, 안 먹힐 때 해결

> Claude Code effort는 한 요청의 작업량입니다. 5.5 계열 기본값은 medium이며, 사용자 설정 최상위 effortLevel은 Opus 5.5가 무시하니 /effort로 저장하세요.

- URL: https://blog.laozhang.ai/ko/posts/claude-code-effort-level
- Published: 2026-11-02
- Updated: 2026-11-02
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ko/about)
- Topic: Claude Code
- Tags: Claude Code, effort, effort 설정, Opus 5.5, Sonnet 5.5, ultrathink, ultracode, settings.json

---
Claude Code의 effort는 어떤 모델이 답하는지가 아니라, 같은 모델이 한 요청에 얼마나 공을 들이는지를 정하는 값입니다. 생각하는 양뿐 아니라 읽는 파일 수, 도구 호출, 사용자에게 다시 묻기 전에 어디까지 진행하는지가 함께 달라집니다. 2026년 11월 2일 기준 Claude Code에서 Opus 5.5, Sonnet 5.5, Haiku 5.5의 기본값은 `medium`이고 Fable 5.1과 Opus 5는 `high`, Opus 4.7은 `xhigh`이므로, 하단에 medium이 떠 있다고 해서 성능이 떨어진 상태는 아닙니다.

지금 세션이 실제로 어느 수준으로 도는지는 Claude Code 프롬프트에서 `/effort status`로 확인합니다. 바꾸고 싶다면 `/effort high`처럼 수준을 입력하면 현재 모델의 기본값으로 `~/.claude/settings.json`의 `modelSettings`에 저장되고, 슬라이더에서 `s`를 누르면 이번 세션에만 적용됩니다. `max`는 환경 변수 `CLAUDE_CODE_EFFORT_LEVEL`로 지정하지 않는 한 저장되지 않고 그 세션에서 끝납니다.

설정했는데 다음 세션에서 medium으로 돌아온다면 원인은 대개 두 가지입니다. 예전 방식대로 사용자 설정 파일 최상위에 `"effortLevel": "high"`를 넣었다면 Opus 5.5는 이 키를 무시하고, 셸에 `CLAUDE_CODE_EFFORT_LEVEL`이 남아 있다면 `/effort`나 `--effort`로 무엇을 고르든 그 값이 이깁니다.

## Claude Code effort란: 모델이 아니라 한 요청의 작업량

effort는 Claude가 요청 하나를 처리하면서 쓰는 작업량의 크기입니다. Anthropic의 [Claude Code 모델과 effort 수준 선택 안내 글](https://claude.com/blog/claude-model-and-effort-level-in-claude-code)은 effort가 "생각하는 시간"만이 아니라 읽는 파일 수, 사용하는 도구, 다시 묻기 전까지 밟는 단계 수를 함께 정한다고 설명합니다. 그래서 수준을 올리면 더 많이 확인하고 더 멀리 혼자 진행하며, 내리면 더 일찍 결과를 돌려주거나 맥락을 되묻습니다.

모델 선택은 이와 다른 축입니다. 모델은 지식과 능력의 범위 자체를 정하고, effort는 그 범위 안에서 얼마나 일할지를 정합니다. 같은 안내 글은 필요한 맥락을 다 갖고도 틀렸다면 더 강한 모델로 바꾸고, 파일을 건너뛰거나 테스트를 돌리지 않거나 리팩터링을 중간에 멈춰서 틀렸다면 effort를 올리라고 구분합니다. 또 작업마다 바꾸기보다 하는 일의 종류에 맞춰 평소 수준을 정해 두라고 권합니다.

effort를 "사고 예산"이나 토큰 한도로 이해하면 헷갈립니다. Opus 5.5, Sonnet 5.5, Haiku 5.5와 Fable 계열은 사고 기능을 끌 수 없고, 각 단계에서 얼마나 생각할지를 모델이 effort 수준에 맞춰 스스로 정합니다. 그래서 이 모델들에서는 `MAX_THINKING_TOKENS=0`이나 `"alwaysThinkingEnabled": false`를 저장해도 효과가 없고, 조절 수단은 effort뿐입니다.

## 모델별 effort 기본값: Opus·Sonnet·Haiku 5.5는 medium

Claude Code에서 아무 설정도 하지 않았을 때의 effort는 모델마다 다릅니다. 2026년 11월 2일 기준 [Claude Code 모델 구성 문서의 effort 수준 조정 항목](https://code.claude.com/docs/ko/model-config#adjust-effort-level)은 Opus 5.5, Sonnet 5.5, Haiku 5.5를 `medium`, Opus 4.7을 `xhigh`, effort를 지원하는 나머지 모델을 `high`로 적고 있고, 같은 날 직접 돌려 본 테스트에서도 Claude Code가 실제로 보낸 값이 문서와 일치했습니다.

| 모델 | 고를 수 있는 수준 | 문서상 Claude Code 기본값 | 2026-11-02 실제 전송값 |
| --- | --- | --- | --- |
| Opus 5.5 | `low`~`max` 5단계 | `medium` | `medium` |
| Sonnet 5.5 | `low`~`max` 5단계 | `medium` | `medium` |
| Haiku 5.5 | `low`~`max` 5단계 | `medium` | `medium` |
| Fable 5.1 | `low`~`max` 5단계 | `high` | `high` |
| Opus 5 | `low`~`max` 5단계 | `high` | `high` |
| Opus 4.7 | `low`~`max` 5단계 | `xhigh` | `xhigh` |
| Opus 4.6 | `low`, `medium`, `high`, `max` (`xhigh` 없음) | `high` | `high` |

테스트는 2026년 11월 2일 macOS에서 Claude Code 2.1.316을 별도 설정 폴더(`CLAUDE_CONFIG_DIR`)로 실행하고, `ANTHROPIC_BASE_URL`을 요청 내용만 기록하는 로컬 mock 엔드포인트로 돌려 진행했습니다. 실제 모델은 호출되지 않으며, `claude -p "Reply with OK" --model claude-opus-5-5`처럼 모델 ID만 바꿔 요청 본문의 `output_config.effort` 값을 읽었고 일곱 모델 모두 `thinking`은 `adaptive`로 전송됐습니다. 이 테스트는 Claude Code가 무엇을 보내는지를 보여 줄 뿐, 모델이 어떻게 답하는지나 토큰 사용량은 보여 주지 않습니다. 아래에 나오는 다른 실측도 모두 같은 환경에서 진행했습니다.

5.5 계열 기본값이 한 단계 낮아진 것은 성능을 깎은 결과가 아닙니다. 공식 문서는 effort 척도가 모델마다 따로 보정되어 같은 이름의 수준이라도 모델끼리 같은 값이 아니라고 밝히고, Anthropic 자체 테스트에서 `medium`의 Opus 5.5가 코딩과 지식 작업 평가에서 `high`의 Opus 5와 같거나 앞섰다고 적고 있습니다. 같은 수준에서 Opus 5.5가 Opus 5보다 턴마다 더 많이 생각하는 경향도 있으므로, Opus 5에서 옮겨 왔다면 예전 수준을 그대로 가져오지 말고 `medium`부터 시작하라는 것이 문서의 권고입니다.

표에 없는 모델 가운데 Fable 5, Sonnet 5, Opus 4.8은 문서상 5단계를 모두 지원하고 기본값이 `high`이며, Sonnet 4.6은 Opus 4.6처럼 `xhigh`가 없습니다. 목록에 없는 모델은 effort 자체를 지원하지 않습니다. Claude API를 직접 호출할 때는 기본값이 다를 수 있다는 점도 기억해 두세요. [Claude API의 effort 문서](https://platform.claude.com/docs/en/build-with-claude/effort)에서 Sonnet 5.5의 기본값은 `high`이고 Claude Code만 이를 `medium`으로 보내며, Sonnet 5.5로 옮길 때 effort별 비용이 어떻게 달라지는지는 [Claude Sonnet 5.5 가격과 성능: Sonnet 5 대비 effort별 비용, 전환 방법](https://blog.laozhang.ai/ko/posts/claude-sonnet-5-5)에서 다룹니다.

## effort 수준별 차이: low부터 max까지 언제 쓰나

기본값은 대부분의 코딩 작업에 맞춰져 있으므로 먼저 기본값으로 쓰고, 특정 종류의 작업에서 부족함이 반복될 때 한 단계씩 조정하는 편이 낫습니다. 수준을 올리면 엣지 케이스를 더 많이 시험하고 답하기 전에 더 많이 검증하는 대신 토큰과 시간이 더 들고, 내리면 출발점을 더 빨리 받는 대신 검토와 다음 지시를 사용자가 더 자주 맡게 됩니다. 아래 표는 Claude Code 공식 문서의 수준별 안내를 정리한 것입니다.

| 수준 | 잘 맞는 작업 | 대가 |
| --- | --- | --- |
| `low` | 결과를 바로 검토하는 짧은 대화, 브레인스토밍, 첫 스케치, 이름 바꾸기 같은 작은 변경 | 검증과 엣지 케이스 확인이 줄어 사용자가 더 자주 확인해야 함 |
| `medium` | 범위가 분명한 일상 개발 작업, 예를 들어 새 기능 구현. 5.5 계열 기본값 | 기본값이 `high`인 모델에서 내리면 토큰은 줄지만 일부 성능을 양보 |
| `high` | 검증이 중요하거나 엣지 케이스가 많을 작업, 예를 들어 기존 코드베이스의 버그 수정 | 5.5 계열에서는 기본보다 토큰과 시간이 더 듦 |
| `xhigh` | 더 깊은 추론이 필요한 작업. Opus 4.7 기본값 | 토큰 지출이 더 크고, Opus 4.6·Sonnet 4.6에서는 `high`로 내려가 실행됨 |
| `max` | 사용자 개입 없이 끝까지 풀게 할 어려운 문제, 예를 들어 보안 취약점 찾기 | 들인 만큼 효과가 늘지 않을 수 있고 과도하게 생각하기 쉬움. 세션 한정 |

"그냥 max로 두라"는 조언이 그대로 통하지 않는 이유는 두 가지입니다. 먼저 `max`는 설정 파일에 저장할 수 없어 `/effort max`로 고르면 그 세션에서만 유지되고, 계속 쓰려면 `CLAUDE_CODE_EFFORT_LEVEL=max`를 셸에 넣는 수밖에 없습니다. 또 공식 문서는 `max`가 효과 대비 비용이 커지고 과도한 사고에 빠지기 쉬우니 넓게 쓰기 전에 직접 시험해 보라고 경고합니다. 평소 기본값을 올리고 싶다면 저장이 되는 `high`나 `xhigh`를 고르고, `max`는 정말 어려운 작업이 있을 때 그 세션에만 쓰는 쪽이 현실적입니다.

수준을 올려도 같은 실수가 반복된다면 effort가 아니라 모델 문제일 가능성이 큽니다. Sonnet 5.5를 `high`로 쓸지 Opus 5.5를 `medium`으로 쓸지처럼 모델과 수준을 함께 고르는 문제는 [Sonnet 5.5 vs Opus 5.5 차이: 작업당 비용과 선택 기준](https://blog.laozhang.ai/ko/posts/claude-sonnet-5-5-vs-opus-5-5)에서 작업당 비용으로 비교하고, Opus에서 Fable로 올릴지는 [Claude Fable 5.1 vs Opus 5 가격 비교: 실제 작업 비용](https://blog.laozhang.ai/ko/posts/claude-fable-5-1-migration-pricing-cache-effort)이 다룹니다. 높은 수준이 5시간·주간 사용량을 얼마나 더 쓰는지 직접 따져 보려면 [Claude Code 토큰 사용량 확인·감사: /usage와 5시간·주간 한도 계획](https://blog.laozhang.ai/ko/posts/claude-code-usage-limit-issues)의 방법으로 확인하는 것이 정확합니다.

## 지금 세션의 effort 수준 확인하는 순서

설정 출처가 여러 곳이라 화면 표시만 보고 판단하면 틀리기 쉽습니다. `/effort status` 출력과 환경 변수, 설정 파일을 차례로 보면 어떤 값이 이기고 있는지 알 수 있습니다.

1. Claude Code 프롬프트에서 `/effort status`를 실행합니다. 2026년 11월 2일 새 설정 폴더의 Opus 5.5 세션에서는 `Effort level: auto (currently medium)`이 나왔는데, 직접 고른 수준 없이 모델 기본값 `medium`이 전송되고 있다는 뜻입니다. 괄호 없이 `Effort level: auto`만 나오면 Claude Code가 수준을 아예 보내지 않고 API 기본값에 맡기는 상태입니다.
2. 화면 하단 바닥글을 봅니다. 같은 테스트에서 시작 시 `◐ medium · /effort`, `high`를 저장한 뒤 `● high`, `max`를 고른 뒤 `◈ max`로 바뀌었습니다. 바닥글과 세션 헤더는 설정된 값을 보여 주므로, 이미 진행 중이던 턴은 이전 수준으로 끝날 수 있습니다.
3. 터미널에서 `echo $CLAUDE_CODE_EFFORT_LEVEL`을 실행합니다. 값이 나오면 그 값이 `/effort`, `--effort`, 설정 파일보다 우선합니다.
4. `~/.claude/settings.json`과 프로젝트의 `.claude/settings.json`, `.claude/settings.local.json`에서 `modelSettings`, 최상위 `effortLevel`, `maxEffortLevel`을 찾습니다. 상한이 있으면 그보다 높은 수준은 어떤 방법으로 골라도 상한에서 실행됩니다.

## Claude Code effort 설정 방법: 이번 턴·세션·모델 기본값·상한

effort를 바꾸는 방법은 여러 가지이고, 방법마다 유지되는 기간과 우선순위가 다릅니다. Claude Code는 환경 변수 `CLAUDE_CODE_EFFORT_LEVEL`, 세션에서 고른 수준, 실행 플래그 `--effort`, 설정 파일, 모델 기본값 순서로 확인해 처음 걸리는 값을 쓰므로, 원하는 범위에 맞는 방법 하나만 쓰고 나머지는 비워 두는 것이 안전합니다.

![Claude Code가 환경 변수, 세션에서 고른 수준, --effort, 설정 파일, 모델 기본값 순서로 effort를 고르고 maxEffortLevel이 모두를 상한으로 누르는 구조](https://blog.laozhang.ai/posts/ko/claude-code-effort-level/img/effort-priority-order.webp)

| 방법 | 적용 범위와 유지 기간 | 우선순위 |
| --- | --- | --- |
| `CLAUDE_CODE_EFFORT_LEVEL=high`를 export한 셸에서 `claude` 실행 | 그 셸에서 시작한 모든 세션. `max`도 유지되는 유일한 방법 | 1순위, 다른 출처를 모두 덮음 |
| `/effort high` 입력, 또는 `/effort` 슬라이더·`/model` 선택기에서 `Enter` | 현재 모델의 기본값으로 `modelSettings`에 저장, 다음 세션에도 유지. `low`~`xhigh`만 저장됨 | 2순위 |
| 슬라이더·`/model` 선택기에서 `s`, 또는 `/effort max` | 이번 세션만 | 2순위 |
| `claude --effort high`로 실행 | 그 실행 한 번 | 3순위 |
| 설정 파일의 `modelSettings` | 모델별 저장 기본값 | 4순위, 같은 파일의 최상위 `effortLevel`보다 우선 |
| 설정 파일 최상위 `effortLevel` | 사용자 설정에서는 Opus 5.5 이후 모델에 무시됨. 프로젝트·로컬·관리형 설정과 `--settings`에서는 모든 모델에 적용 | 4순위 |
| 프롬프트에 `ultrathink` 포함 | 그 한 턴 | 세션 설정은 바꾸지 않음 |
| 스킬·서브에이전트 frontmatter의 `effort` | 스킬이 실행된 턴, 서브에이전트가 도는 동안 | 세션 수준보다 우선, 환경 변수에는 짐 |
| `maxEffortLevel` | 상한. 위 모든 출처와 모델 기본값에 적용 | 순서와 별개로 항상 적용 |

우선순위는 2026년 11월 2일 mock 테스트에서도 문서대로 확인됐습니다. `CLAUDE_CODE_EFFORT_LEVEL=low`를 둔 채 `claude --effort high`로 실행하자 실제 전송값은 `low`였고, Opus 5.5에서 `--effort max`는 `max`, `--effort low`는 `low`, 환경 변수 `max`는 `max`로 그대로 전송됐습니다. Opus 4.6에서 `--effort xhigh`는 아무 메시지 없이 `high`로 바뀌었고, 오타를 낸 `--effort banana`는 아래 경고를 출력한 뒤 기본값 `medium`으로 실행됐습니다.

```text
Warning: Unknown --effort value 'banana' — ignoring it and using the default effort. Valid values: low, medium, high, xhigh, max.
```

설정 파일 쪽은 결과가 더 갈렸습니다. 같은 날 사용자 설정 최상위에 `"effortLevel": "high"`를 넣자 Fable 5.1은 `high`로 보냈지만 Opus 5.5는 여전히 `medium`을 보냈고, `"effortLevel": "max"`를 넣은 Opus 5는 아무 메시지 없이 기본값 `high`로 실행됐습니다. 반면 아래처럼 `modelSettings`에 Opus 5.5 항목을 넣으면 Opus 5.5는 `high`, 같은 파일로 실행한 Sonnet 5.5는 `medium`이었고, 여기에 `--effort low`를 더하면 `low`가 전송됐습니다. 저장값은 모델 이름별로 따로 관리되므로, Sonnet 5.5도 올리려면 Sonnet 5.5로 바꾼 뒤 한 번 더 저장해야 합니다.

```json
{
  "modelSettings": {
    "claude-opus-5-5": {
      "effortLevel": "high"
    }
  }
}
```

`modelSettings`는 Claude Code v2.1.251 이상에서 쓰는 키이고, `claude-opus-5-5` 같은 정식 이름 아래 저장되며 별칭, 날짜가 붙은 ID, `[1m]` 표기도 같은 항목으로 묶입니다. 직접 편집할 일은 드물고, 대화형 세션에서 `/effort`로 저장하면 Claude Code가 이 형태로 기록합니다.

대화형 화면에서의 동작은 2026년 11월 2일 터미널(tmux)에서 같은 mock에 연결한 Opus 5.5 세션으로 확인했습니다. `/effort high`를 입력하자 아래 메시지가 나오고 `settings.json`에 위의 `modelSettings` 항목이 생겼습니다. 이어서 `/effort max`를 입력하면 "this session only"라는 표시와 함께 과도한 토큰 사용을 경고하는 설명이 붙었고, 설정 파일은 `high` 그대로였지만 다음 메시지는 `max`로 전송됐습니다.

```text
Set effort level to high (saved as your default for new sessions): Comprehensive implementation with extensive testing and documentation

Set effort level to max (this session only): Maximum capability with deepest reasoning. May use excessive tokens resulting in long response times or overthinking. Use sparingly for the hardest tasks.
```

인수 없이 `/effort`만 입력하면 왼쪽 `Faster`에서 오른쪽 `Smarter`까지 `low medium high xhigh max`가 놓인 슬라이더가 열리고, 하단에 `←/→ to adjust · Enter to confirm · s for this session only · Esc to cancel`이 표시됩니다. 단축키는 슬라이더와 `/model` 선택기 모두 좌우 화살표로 한 단계씩 움직이는 방식이며, 슬라이더에서는 `Tab`이 Ultracode를 켜고 끕니다.

### 팀·모델별 effort 상한: maxEffortLevel

팀원이 일정 수준 이상을 쓰지 못하게 하려면 `effortLevel`이 아니라 `maxEffortLevel`을 씁니다. 관리형 설정의 `effortLevel`은 우선순위 4단계의 기본값일 뿐이라 사용자가 `/effort`나 `--effort`로 바꿀 수 있지만, `maxEffortLevel`은 `/effort`, `/model`, `--effort`, 환경 변수, 스킬·서브에이전트의 `effort`, 모델 기본값까지 모두 상한으로 눌러 둡니다. v2.1.267 이상의 Claude Code가 요청을 보내기 전에 직접 적용하므로 Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry에서도 통하고, 여러 설정 파일에 상한이 있으면 가장 낮은 값이 적용됩니다.

```json
{
  "maxEffortLevel": "high",
  "modelSettings": {
    "claude-sonnet-5-5": {
      "maxEffortLevel": "max"
    }
  }
}
```

위 예시는 모든 모델을 `high`로 제한하면서 Sonnet 5.5만 같은 설정 파일의 상한에서 빼 줍니다. 상한보다 높은 수준은 `/effort` 슬라이더에 아예 나오지 않고, Claude Enterprise 관리자가 역할별·모델별 effort 제한을 따로 걸었다면 둘 중 낮은 쪽이 적용됩니다. 2026년 11월 2일 mock 테스트에서 `"maxEffortLevel": "high"`를 둔 채 `--effort max`로 실행하자 `high`가 전송되며 아래 경고가 나왔고, 같은 상한에서 `CLAUDE_CODE_EFFORT_LEVEL=xhigh`는 아무 메시지 없이 `high`로 전송됐습니다.

```text
Effort 'max' exceeds the cap for claude-opus-5-5 set by your settings or organization; using 'high'.
```

### 스킬·서브에이전트에 다른 effort 지정

특정 스킬이나 서브에이전트만 다른 수준으로 돌리고 싶다면 그 markdown 파일의 frontmatter에 `effort: high`처럼 적습니다. 스킬의 `effort`는 그 스킬이 실행된 턴이 끝날 때까지, 서브에이전트의 `effort`는 호출할 때 따로 덮어쓰지 않는 한 서브에이전트가 도는 동안 세션 수준 대신 적용됩니다. 다만 `CLAUDE_CODE_EFFORT_LEVEL`이 설정돼 있으면 그 값이 이기고, `maxEffortLevel`과 조직 제한도 그대로 적용됩니다.

## effort 설정이 안 먹힐 때: 증상별 원인과 해결

설정한 effort가 적용되지 않는 경우는 대부분 더 높은 우선순위의 출처가 값을 덮어쓰거나, 설정 파일이 그 값을 받지 않거나, 모델이 그 수준을 지원하지 않는 세 가지 중 하나입니다. 아래 표에서 증상을 찾아 원인과 해결 방법을 확인하세요.

| 증상 | 원인 | 해결 |
| --- | --- | --- |
| 하단에 `medium`이 떠 있다 | Opus 5.5·Sonnet 5.5·Haiku 5.5의 정상 기본값 | 그대로 써도 되며, 올리려면 `/effort high` |
| `settings.json`에 `"effortLevel": "high"`를 넣었는데 Opus 5.5가 `medium` | 사용자 설정 최상위 `effortLevel`은 모델별 저장 이전의 옛 형식이라 Opus 5.5 이후 모델은 무시 | Opus 5.5에서 `/effort high`로 저장하거나 `modelSettings`에 직접 기록 |
| 설정 파일의 `"effortLevel": "max"`가 무시되거나 `/effort max`가 다음 세션에서 사라짐 | 설정 파일은 `max`를 받지 않고(메시지 없음), `/effort max`는 세션 한정 | 계속 쓰려면 `CLAUDE_CODE_EFFORT_LEVEL=max`, 아니면 저장 가능한 `xhigh`나 `high`를 기본값으로 |
| `/effort`·`--effort`로 무엇을 골라도 같은 수준 | 셸에 `CLAUDE_CODE_EFFORT_LEVEL`이 설정됨 | `unset CLAUDE_CODE_EFFORT_LEVEL` 후 `claude` 재시작, 셸 설정 파일에서도 삭제 |
| 어떤 값을 넣어도 `high` 이상 안 올라감 | `maxEffortLevel` 또는 조직 effort 제한 | 상한을 올리거나 관리자에게 요청 |
| Opus 4.6에서 `xhigh`가 `high`로 실행됨 | 모델이 `xhigh`를 지원하지 않아 그 이하의 최고 수준으로 대체 | 정상 동작. `xhigh`가 필요하면 지원 모델로 전환 |
| Opus 5.5에서 올렸는데 Sonnet 5.5로 바꾸니 `medium` | 저장값은 모델별로 따로 관리됨 | Sonnet 5.5에서도 `/effort`로 한 번 더 저장 |
| 모델이 자동 폴백된 뒤에도 이전 수준 유지 | 폴백 후에는 원래 요청의 수준을 이어감 | `/effort status`로 확인 후 `/effort`로 다시 지정 |
| 바꿨는데 진행 중인 작업에 반영 안 됨 | 새 수준은 다음 메시지부터 시작 | Claude 작업 중에 `keep going` 같은 메시지를 대기열에 추가 |
| Amazon Bedrock·Google Cloud Agent Platform·Microsoft Foundry에서 ARN이나 사용자 지정 배포 이름으로 쓰는데 `/effort`가 동작하지 않음 | 모델 ID가 알려진 패턴과 맞지 않아 effort 기능이 꺼진 상태 | `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES`에 `effort,xhigh_effort,max_effort` 등을 선언. 이 세 제공자에서만 효과가 있음 |

마지막 행은 [Claude Code 모델 구성 문서](https://code.claude.com/docs/ko/model-config)의 설명을 따른 것으로, Sonnet·Haiku·Fable 계열도 `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES`처럼 같은 접미사를 붙여 선언합니다. 이 변수를 설정하면 나열한 기능만 켜지고 나머지는 꺼지므로, `thinking`, `adaptive_thinking`처럼 모델이 실제로 지원하는 기능도 함께 적어야 합니다. 다만 2026년 11월 2일 기준 문서상 `_SUPPORTED_CAPABILITIES`는 Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry 같은 서드파티 제공자에서만 적용됩니다. `ANTHROPIC_BASE_URL`로 LLM 게이트웨이를 거치는 경우에는 표시용 `_NAME`과 `_DESCRIPTION`만 반영되고, api.anthropic.com에 직접 연결하면 이 변수들이 하나도 적용되지 않으므로 게이트웨이 사용자에게는 해결책이 되지 않습니다.

## ultracode·ultrathink·auto와 effort의 차이

ultracode, ultrathink, auto는 effort 설정 화면이나 명령에 함께 등장하지만 다섯 수준 중 하나가 아닙니다. 셋 다 effort와 맞물려 동작하므로 각각이 실제로 무엇을 바꾸는지 알아 두면 의도하지 않은 수준으로 도는 일을 막을 수 있습니다.

### ultracode는 effort 수준이 아니라 동적 워크플로 스위치

ultracode는 모델의 effort 수준이 아니라 Claude Code 설정으로, 켜면 Claude가 실질적인 작업에서 동적 워크플로(dynamic workflows)를 조율합니다. `/effort ultracode`와 `/effort ultracode off`, 또는 슬라이더에서 `Tab` 후 `Enter`로 켜고 끄며, 계속 켜 두려면 설정 파일에 `"ultracode": true`를 넣습니다. 이렇게 켜고 끌 때 effort 수준은 바뀌지 않고, 세션이 돌던 수준 그대로 워크플로가 실행됩니다. 예외는 실행 플래그 `--effort ultracode`로, ultracode를 켜면서 수준을 `xhigh`로 맞춥니다. 2026년 11월 2일 mock 테스트에서 이 플래그는 Opus 5.5에서 `xhigh`를, `xhigh`가 없는 Opus 4.6에서는 `high`를 보냈습니다. `effortLevel` 설정과 `CLAUDE_CODE_EFFORT_LEVEL`은 `ultracode`라는 값을 받지 않으며, v2.1.284 이전 버전에서는 ultracode를 켜면 세션이 `xhigh`로 바뀌고 다른 수준을 고르면 꺼졌기 때문에 그 시기의 설명과 지금 동작이 다릅니다.

### ultrathink는 그 한 턴만 xhigh, think hard는 키워드가 아님

프롬프트 어디에든 `ultrathink`를 넣으면 세션 설정은 그대로 둔 채 그 턴에서만 더 깊이 추론하도록 요청합니다. 2026년 11월 2일 `medium` 세션의 터미널에서 `ultrathink about this and reply with OK`를 보내자 그 턴만 `xhigh`로 전송됐고, 다음 일반 메시지는 다시 `medium`이었으며 바닥글도 `medium`에서 바뀌지 않았습니다. 반면 `claude -p "ultrathink: reply with OK"`처럼 비대화형으로 실행하면 수준은 `medium` 그대로였고, 아래 한 줄이 시스템 맥락에 추가됐을 뿐입니다.

```text
The user included the keyword "ultrathink", requesting deeper reasoning on this turn. Reason as thoroughly as the task warrants.
```

`think hard`를 넣은 `-p` 실행은 문장 자체 외에는 일반 프롬프트와 똑같이 전송됐습니다. 공식 문서도 "think", "think hard", "think more"는 키워드가 아니라 일반 텍스트로 전달된다고 밝힙니다. 터미널에서 턴을 `xhigh`로 올릴 수 있을 때는 단어가 무지개색으로 표시되는데(v2.1.311 이상), 무지개색이 아니라면 `xhigh`보다 낮은 `CLAUDE_CODE_EFFORT_LEVEL`이나 상한이 걸려 있거나 5.5 계열·Fable 5.1이 아닌 모델일 수 있습니다. Amazon Bedrock처럼 이 단어로 턴을 올릴 수 없는 환경에서는 effort 수준 자체를 바꿔야 합니다.

### /effort auto와 CLAUDE_CODE_EFFORT_LEVEL=auto의 차이

같은 auto라도 명령과 환경 변수는 다르게 동작합니다. `/effort auto`는 현재 모델에 저장한 수준만 지우는 명령이라 모델 기본값은 계속 전송되고, `CLAUDE_CODE_EFFORT_LEVEL=auto`(또는 `unset`)를 export한 셸에서 실행하면 Claude Code가 effort 값을 아예 보내지 않아 API 쪽 기본값이 적용됩니다. 2026년 11월 2일 테스트에서 `/effort auto`는 `Effort level set to auto`를 출력하고 `settings.json`의 `claude-opus-5-5` 항목을 빈 `{}`로 만들었지만 다음 메시지는 `medium`으로 전송됐고, 환경 변수 `auto`로 실행한 요청에는 effort 필드 자체가 없었습니다. Opus 5.5는 API 기본값도 `medium`이라 차이가 드러나지 않지만, Sonnet 5.5는 API 문서상 기본값이 `high`이므로 환경 변수 `auto`를 쓰면 Claude Code 기본값인 `medium`과 다른 수준이 적용됩니다. `/effort auto`는 다른 모델의 저장값이나 최상위 `effortLevel`은 건드리지 않습니다.

![/effort auto는 모델 기본값 medium을 계속 보내고 CLAUDE_CODE_EFFORT_LEVEL=auto는 effort 필드를 빼서 Sonnet 5.5에서는 high가 적용되는 차이](https://blog.laozhang.ai/posts/ko/claude-code-effort-level/img/effort-auto-vs-env-auto.webp)

## Claude Code effort 설정에 관한 다른 질문

### Effort 'xhigh' isn't available 오류는 어떻게 해결하나요?

`Effort 'xhigh' isn't available with thinking turned off` 오류는 사고 기능을 끈 상태로 `high`보다 높은 effort를 보낼 때 Opus 5처럼 이 조합을 받지 않는 모델에서 납니다. `/effort high` 이하로 내리거나, `MAX_THINKING_TOKENS=0`을 해제하거나 설정의 `"alwaysThinkingEnabled": false`를 지워 사고를 다시 켜면 해결됩니다. 2026년 11월 2일 기준 공식 오류 문서에 따르면 v2.1.251부터는 이 조합을 거부하는 것으로 알려진 모델에 Claude Code가 `high`를 대신 보내므로, 이 오류가 계속 보이면 Claude Code 버전부터 확인하세요. v2.1.242 이전에는 `API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model.`로 시작하는 문구였고, 지금 버전의 전체 문구는 아래와 같습니다.

```text
API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)
```

### -p 실행, Remote Control, VS Code에서 바꾼 effort도 저장되나요?

환경에 따라 다릅니다. 2026년 11월 2일 기준 공식 설정 문서에 따르면 `-p` 실행, 원격 작업자 세션, Agent SDK에서 `/effort`로 바꾼 수준은 그 세션에만 적용되고, Remote Control로 연결한 휴대폰이나 브라우저에서 고른 수준도 그 세션에서 끝납니다(v2.1.234 이상). 반대로 VS Code 확장의 모델 선택기에서 `low`~`xhigh`를 고르면 터미널의 `/effort`와 똑같이 `modelSettings`에 저장됩니다.

## 참고 자료

이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026-11-02.

- [Claude Code 모델과 effort 수준 선택 안내 글](https://claude.com/blog/claude-model-and-effort-level-in-claude-code) (claude.com)
- [Claude Code 모델 구성 문서의 effort 수준 조정 항목](https://code.claude.com/docs/ko/model-config) (code.claude.com)
- [Claude API의 effort 문서](https://platform.claude.com/docs/en/build-with-claude/effort) (platform.claude.com)