"LLM 추론 모드 (4/6) — Claude Code의 effort 실전: low·medium·high·xhigh·max와 ultracode"

- 6월 15, 2026

3편이 API의 effort 파라미터(low~max)를 정면으로 해부했다면, 4편은 그 똑같은 다이얼이 Claude Code CLI 안으로 들어왔을 때를 본다. 값은 같다 — 다른 건 어떻게 켜고, 얼마나 지속되며, ultracode가 무엇이냐다.

Claude Code의 effort는 새 개념이 아니다. 3편에서 본 API의 output_config.effort와 정확히 같은 값들이 CLI 표면에 노출된 것이다. 그래서 4편의 목표는 "또 다른 손잡이"를 소개하는 게 아니라, 그 손잡이를 실전에서 어떻게 돌리는지 — /effort 명령, 환경변수, 세션 지속성, 그리고 메뉴에 보이지만 정작 effort 레벨이 아닌 ultracode — 를 정리하는 것이다.

한 문단 요약

Claude Code는 보수적→강력 순서로 다섯 단계의 effort를 노출한다 — low, medium, high, xhigh, max. 이는 API가 받는 그 effort 값을 UI에 그대로 꺼낸 것이고, 기본값은 API와 동일한 high다. xhigh는 Anthropic이 실제 코딩·에이전트 세션에 권장하는 값, max는 토큰 소비 제약이 없는 가장 깊은 추론이다. 다만 max는 현재 세션에만 적용된다(CLAUDE_CODE_EFFORT_LEVEL 환경변수로 지정한 경우는 예외) — low/medium/high/xhigh는 세션을 넘어 지속된다. ultracode는 메뉴에 보이지만 6번째 effort 레벨이 아니다. xhigh effort에 멀티에이전트 워크플로 실행 권한을 묶어 놓은 Claude Code 측 패키징일 뿐, API의 effort 집합은 여전히 low~max다.

1. 다섯 단계 — API의 값이 그대로 올라온다

Claude Code의 effort는 보수적인 쪽에서 강력한 쪽으로 다섯 단계다.

low → medium → high → xhigh → max

여기서 가장 먼저 짚을 점은, 이 다섯이 새로운 CLI 전용 값이 아니라는 것이다. 3편에서 본 API의 effort 파라미터가 받는 값 집합이 정확히 low / medium / high / xhigh / max이고, Claude Code는 그 값을 UI에 그대로 꺼내 보여줄 뿐이다. API가 받는 집합과 CLI가 보여주는 집합이 동일하다.

그래서 기본값도 같다. Claude Code의 기본 effort는 high — API의 기본값과 정확히 일치한다. 이 high 기본값은 Fable 5, Opus 4.8, Opus 4.6, Sonnet 4.6의 런칭 기본값이다. 즉 별도 설정 없이 Claude Code를 켜면 high로 동작한다.

2. 동작은 어떻게 바뀌나 — API의 거동을 그대로 미러링

effort를 올리고 내릴 때 Claude Code의 행동이 바뀌는 방식은 3편에서 본 API의 거동을 그대로 따라간다. effort는 사고 깊이뿐 아니라 응답 전체의 토큰 사용 방식 — 도구 호출 수, 프리앰블, 완료 보고의 상세도 — 까지 조절하기 때문이다.

낮은 effort일수록: - 도구 호출이 더 적다. - 프리앰블 없이 곧바로 작업을 시작한다. - 간결한 완료 보고로 마친다.

높은 effort일수록: - 시작 전에 계획을 설명한다. - 변경 사항을 상세히 요약한다. - 코드 주석을 더 꼼꼼하게 단다.

즉 같은 작업이라도 낮은 effort에서는 "말없이 빠르게 처리하고 짧게 보고"하는 쪽으로, 높은 effort에서는 "계획을 펼치고, 더 많은 도구를 거쳐, 자세히 정리"하는 쪽으로 거동이 이동한다.

3. 다섯 단계 한눈에 — 지속성·거동·용처

레벨	세션 넘어 지속?	거동	언제 쓰나
`low`	지속	도구 호출 최소, 프리앰블 없이 바로 작업, 간결한 보고	답이 하나로 좁혀지는 작업 — 이름 변경, 한 줄 초안
`medium`	지속	low와 high 사이의 균형	깊게 고민할 것 없는 기본값
`high`	지속	계획 설명·상세 요약·꼼꼼한 주석 (= 기본값)	실질적인 작업 대부분
`xhigh`	지속	high보다 더 깊은 추론과 더 긴 호흡	실제 코딩·에이전트 세션 (Anthropic 권장)
`max`	현재 세션만 (단, 환경변수 지정 시 예외)	토큰 소비 제약 없는 가장 깊은 추론	가장 어렵고 지연에 둔감한 문제만

표에서 한 가지가 유독 다르다 — max의 지속성이다.

low / medium / high / xhigh는 한 번 설정하면 세션을 넘어 지속된다. 다음에 Claude Code를 다시 켜도 그 값이 유지된다.
max는 현재 세션에만 적용된다. 세션을 닫으면 풀린다. 단, CLAUDE_CODE_EFFORT_LEVEL 환경변수로 지정한 경우는 예외 — 환경변수로 박아두면 max도 세션을 넘어 유지된다.

이 비대칭은 의도적인 안전장치로 읽힌다. max는 토큰 소비에 제약이 없으므로, 무심코 세션 전체의 기본값으로 굳어 비용을 계속 태우는 일을 막는 쪽으로 기본 동작이 설계돼 있다.

4. 어떻게 켜나 — 세 가지 설정 표면

Claude Code에서 effort를 지정하는 경로는 세 가지이고, 각자 지속 범위가 다르다.

/effort (대화형, 세션 단위): 대화 중에 /effort를 치면 레벨을 고를 수 있다. 이 경로는 현재 세션에 적용된다.
CLAUDE_CODE_EFFORT_LEVEL 환경변수 (지속): 환경변수로 박아두면 세션을 넘어 지속된다 — 위에서 본 대로, max마저 세션 경계를 넘기게 만드는 유일한 경로다.
레포별 설정 (per-repo): 프로젝트 설정에 effort 레벨을 고정해 둘 수 있다(예: 프로젝트 설정에 effortLevel을 박아두기). 그 레포에서 작업할 때의 기조를 코드 옆에 함께 둘 수 있다.

세 표면을 한 줄로 구분하면 — /effort는 "지금 이 세션만", 환경변수는 "내 환경 전반에 지속", 레포별 설정은 "이 프로젝트에서는 항상"이다.

5. ultracode의 정체 — 6번째 effort 레벨이 아니다

여기서 가장 흔한 오해를 정리한다. Claude Code의 effort 메뉴에는 low / medium / high / xhigh / max 외에 ultracode가 보인다. 그래서 "ultracode가 max 위의 6번째 effort 레벨"이라고 생각하기 쉽다. 아니다.

사실은 이렇다.

API의 effort 집합은 여전히 low ~ max로 완결돼 있다. ultracode라는 추가 effort 레벨은 API에 존재하지 않는다.
ultracode는 xhigh effort에, Claude Code가 멀티에이전트 워크플로를 띄울 수 있는 상시 권한을 묶어 놓은 것이다. 이 권한은 대화 중간에 들어오는 시스템 메시지를 통해 부여된다.
즉 ultracode는 새 레벨이 아니라, xhigh + 권한의 Claude Code 측 패키징이다.

정리하면, effort의 "깊이"라는 축에서 ultracode는 xhigh와 같다. 거기에 더해지는 것은 권한 — Claude Code가 더 큰 작업을 멀티에이전트로 풀어낼 수 있게 하는 — 이지 추론 깊이가 아니다. 메뉴에 나란히 보여서 같은 종류의 다이얼처럼 느껴지지만, 실제로는 "effort 레벨 다섯 개 + 그 위에 얹힌 실행 모드 하나"로 읽는 편이 정확하다.

6. 그래서 어느 레벨을 언제 — 실전 매칭

레벨별 의미를 작업 난이도에 맞추면 다음과 같다. 1편에서 세운 원칙 — "항상 최대로"가 아니라 작업 난이도에 다이얼을 맞춰라 — 가 CLI에서도 그대로 적용된다.

low — 답이 사실상 하나로 좁혀지는 작업. 이름 변경, 한 줄 초안 작성처럼 사고할 여지가 거의 없는 일.
medium — 깊게 고민할 것 없는 기본 작업. 균형이 필요한 일반 흐름의 무난한 선택.
high — 실질적인 작업 대부분. 기본값이자, 품질과 토큰 효율의 균형점.
xhigh — 실제 코딩 세션, 에이전트 실행. Anthropic이 권장하는 값이며, 진짜 일을 시킬 때의 출발점.
max — 가장 어렵고 지연에 둔감한 문제에만. 토큰 제약이 없는 만큼 비용도 가장 크므로, 상시 기본값으로 두지 않는다(그래서 기본적으로 현재 세션에만 적용된다).

실무적으로는 xhigh를 코딩·에이전트 작업의 기본 출발점으로 두고, 가벼운 일에는 내리고(low/medium), 정말 어려운 한 판에만 max로 올리는 운영이 Anthropic 권장에 부합한다.

이어지는 글

지금까지 3·4편이 Claude 쪽 다이얼을 — API의 effort와 Claude Code의 effort 실전을 — 모두 정리했다.

다음 편(5/6)은 진영을 바꿔 OpenAI·Codex의 reasoning_effort를 본다 — minimal / low / medium / high / xhigh가 GPT-5 / 5.5 / 5.2-codex에서 어떻게 갈리는지, config.toml에서 어떻게 설정하는지, 그리고 Claude의 단일 effort와 달리 출력 길이를 따로 떼어낸 verbosity가 무엇인지.

Claude Code의 effort 레벨·기본값·세션 지속성·ultracode의 동작은 Anthropic 공식 문서(effort, Claude Code 모델 설정)와 모델 마이그레이션 가이드를 1차 자료로 정리했다.

시리즈 전체 안내: 시리즈 목차

이 블로그 검색

MaJu's Note