effort 가 알아서 max 로 안 뛰게 막는다

무엇이 바뀌었나

확인 Claude Code 공식 저장소 변경 로그(CHANGELOG.md) 기준, 2.1.267 (2026-09-09 공개)에 maxEffortLevel 설정이 추가됐다. 원문은 이렇다 — "Added maxEffortLevel setting (top-level or per model under modelSettings): caps the effort level on every provider, in organization managed settings, and on self-hosted runners." 쉽게 말하면, 이 값보다 위로는 못 가게 묶는 천장이다.

확인 효과(effort) 수준은 모델마다 다르지만 보통 low · medium · high · xhigh · max 다섯 단계다(문서 기준, 일부 구형 모델은 xhigh 없이 네 단계). 기본값은 대부분 high이고, /effort·/model· 환경변수·설정 파일 어디서 더 높은 값을 골라도 maxEffortLevel보다 위면 자동으로 그 천장 값으로 눌린다 — 공식 설정 문서 표현으로 "Anything above it … is clamped to it."

확인 "설정 파일 어디든"이라는 건 조직이 배포하는 관리 설정만이 아니라 ~/.claude/settings.json — 즉 내 계정 개인 설정에도 그대로 적을 수 있다는 뜻이다. 공식 설정 우선순위 문서에도 이 파일이 "You, every project" 등급으로 따로 올라 있다.

왜 중요한가

9월 1일 글(페이블 5.1이 나온 날)에서 Claude Code 는 High로, claude.ai·Cowork 는 Medium으로 시작한다고 적었다. 그런데 세션 중에 /effort max 를 실수로 누르거나, 스킬·서브에이전트가 프런트매터에서 effort를 올려 버리는 경우도 있다. maxEffortLevel은 그런 경우에도 천장을 넘지 못하게 막아 주는 안전장치다. 이 사이트 교육 과정 L0·04 토큰·컨텍스트·환각에서 다뤘듯, effort가 높을수록 생각하는 토큰이 늘어 값이 더 든다 — 상한을 걸어 두는 것은 결국 토큰 쓰는 습관에 스스로 울타리를 치는 일이다.

직접 해 보기 — 5분

1. 지금 쓰는 effort를 먼저 본다.

   /effort

   슬라이더가 뜨면서 현재 모델에 저장된 값이 나온다. 손대지 말고 Esc로 닫는다.
2. 개인 설정 파일을 연다. ~/.claude/settings.json을 텍스트 편집기로 연다. 없으면 새로 만들어도 된다.
3. 상한 값을 하나 적어 넣는다. 비용이 신경 쓰이면 medium 정도로 낮게, 속도보다 품질이 중요하면 xhigh 정도로 넉넉하게 잡는다.

   {
     "maxEffortLevel": "medium"
   }

4. 파일을 저장하고 새 세션을 연다. 그리고 일부러 더 높은 값을 시켜 본다.

   /effort max

   상한을 걸어 뒀다면 max로 올라가지 않고 설정한 값(여기서는 medium)에서 멈춰야 한다. 느낌이 아니라 슬라이더에 실제로 뜬 값으로 확인한다 (L0·04).
5. 모델 하나만 따로 묶고 싶으면 modelSettings를 쓴다.

   {
     "modelSettings": {
       "claude-opus-5": { "maxEffortLevel": "high" }
     }
   }

   다른 모델은 그대로 두고 Opus만 상한을 걸 때 쓰는 자리다.

한 줄 정리

1. 9월 9일(2.1.267) maxEffortLevel 설정이 생겼다. effort 천장을 거는 값이다.
2. ~/.claude/settings.json 처럼 개인 설정 파일에도 바로 적을 수 있다.
3. 걸어 뒀으면 /effort max 처럼 일부러 넘겨 시켜서 확인한다. 슬라이더 값으로.