Claude Code 사용법: maxEffortLevel로 추론 강도와 비용 통제하기

Claude Code 사용법 핵심: 상한은 어디에 설정하나

Claude Code를 2.1.267 이상으로 업그레이드한 뒤, 관리할 사용자와 프로젝트 범위에 맞는 설정 파일에 "maxEffortLevel": "medium"을 넣습니다. 개인의 전역 상한은 ~/.claude/settings.json, 특정 저장소에서 일하는 모든 구성원의 상한은 .claude/settings.json, 조직 전체 규칙은 관리형 설정을 사용합니다.

설정값으로는 low, medium, high, xhigh, max를 사용할 수 있습니다. max는 해당 설정 소스에서 추론 강도에 상한을 두지 않는다는 뜻입니다. 키를 아예 지정하지 않아도 상한이 적용되지 않습니다.

이 기능은 예산 한도가 아니라 속도 제한 장치에 가깝습니다. 요청 하나에서 Claude가 어느 정도까지 깊게 추론할 수 있는지는 제한하지만, 토큰 할당량이나 금액 한도, 구독 사용량 제한을 정하지는 않습니다. 이런 수치는 /usage, Claude Console 또는 Claude Code OpenTelemetry로 별도 측정해야 합니다.

maxEffortLevel을 설정하면 무엇이 달라지나

effortLevel과 maxEffortLevel의 역할은 다릅니다. effort level은 세션이나 모델이 요청하는 추론 강도이고, maximum effort level은 그 요청이 넘어설 수 없는 경계입니다.

상한이 medium이면 개발자는 여전히 low나 medium을 선택할 수 있습니다. 반면 high, xhigh, max를 요청해도 실제로는 medium으로 실행됩니다. /effort, /model 선택기, --effort, CLAUDE_CODE_EFFORT_LEVEL, 모델 기본값을 통해 요청된 추론 강도도 모두 이 상한의 적용을 받습니다. Claude Code가 각 요청을 보내기 전에 클라이언트에서 제한하므로, 모델 트래픽이 Anthropic, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 중 어디를 거쳐도 같은 정책을 사용할 수 있습니다.

여기서 놓치기 쉬운 핵심 규칙이 있습니다. 불러온 모든 범위의 상한 중 가장 낮은 값이 최종 적용됩니다. 일반적인 Claude Code 설정은 대개 관리형 설정, 명령줄 설정, 프로젝트 파일, 사용자 설정 순의 계층을 따릅니다. 하지만 maxEffortLevel은 더 엄격한 값을 우선하는 예외입니다. 따라서 관리형 설정이나 사용자 설정이 더 높은 수준을 허용하더라도, 프로젝트 상한이 더 낮으면 프로젝트 값이 적용됩니다.

전역 상한, 모델 예외, 더 엄격한 프로젝트 상한 설정하기

먼저 claude --version을 확인합니다. 2.1.267보다 이전 버전이라면 키를 추가하기 전에 claude update를 실행합니다.

모든 저장소에 적용할 개인 상한은 ~/.claude/settings.json에 다음과 같이 작성합니다.

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

최상위 값은 지원되는 모든 모델을 medium으로 제한합니다. Sonnet 4.6 항목은 이 사용자 파일 안에서만 Sonnet에 적용되는 최상위 값을 대체합니다. 여기서 max는 Sonnet을 최대 추론 강도로 강제한다는 의미가 아닙니다. 이 설정 소스에서는 해당 모델에 상한을 두지 않는다는 뜻입니다.

이제 특정 저장소의 .claude/settings.json에 더 엄격한 규칙을 추가합니다.

{
  "maxEffortLevel": "low"
}

최종 결과는 의도한 대로 엄격하게 적용됩니다.

모델 예외가 프로젝트 규칙을 뚫고 지나가지는 않습니다. Sonnet에 대해 사용자 설정의 medium 상한만 해제할 뿐입니다. 이 차이를 놓치면 예외가 실제보다 넓게 적용된다고 잘못 판단하기 쉽습니다.

회사 정책으로 운영하려면 같은 최상위 키를 관리형 설정으로 배포합니다. 그러면 지원되는 공급자가 어디든 해당 관리형 설정의 대상 구성원에게 상한이 적용됩니다. Enterprise 역할에 별도의 effort 제한도 있다면 Claude Code는 둘 중 더 낮은 상한을 적용합니다.

상한이 실제로 적용됐는지 확인하는 방법

JSON 파일이 유효하다고 해서 의도한 상한이 최종 적용됐다는 뜻은 아닙니다. 어떤 설정 소스를 불러왔는지와 실제 적용 수준을 모두 확인해야 합니다.

1. Claude Code 안에서 /status를 실행합니다. Setting sources 줄을 보면 User settings, Project settings, Managed settings가 제대로 불러와졌는지 확인할 수 있습니다. 다만 개별 키가 어느 소스에서 왔는지는 보여주지 않습니다.
2. 특정 설정 소스가 보이지 않거나 새 키가 무시되는 것 같다면 claude doctor를 실행합니다. 거부된 설정 항목이 여기에 표시됩니다. 공개 JSON 스키마의 반영이 새 CLI 릴리스보다 늦을 수 있으므로, 편집기 경고만으로 오류라고 단정하면 안 됩니다.
3. 세션 헤더에서 모델 이름 옆을 확인합니다. 현재 effort가 표시되며, 값이 바뀔 때는 푸터에도 잠시 나타납니다.
4. 예시 저장소에서 /effort max를 요청합니다. 그래도 프로젝트 수준의 low 상한이 적용됩니다. 더 높은 값을 요청해도 상한을 끌어올릴 수 없습니다.
5. 비대화형 환경에서는 claude_code.cost.usage와 claude_code.token.usage의 effort 속성을 확인합니다. 모델과 쿼리 소스 정보와 함께 각 요청에 실제 적용된 수준이 기록됩니다.

마지막 확인은 Bedrock, Google Cloud, Foundry 환경에서 특히 중요합니다. 공급자가 요청을 받기 전에 Claude Code가 정책을 적용하고, 텔레메트리에는 Claude Code가 실제로 적용한 값이 남기 때문입니다.

품질과 Claude Code 비용은 별도 트랙으로 검증하기

medium이나 low라는 이름이 경제적으로 들린다는 이유만으로 곧바로 배포해서는 안 됩니다. 팀이 이미 잘 아는 일상 작업을 골라 조건을 맞춘 실행끼리 비교해야 합니다.

좋은 테스트 픽스처는 파서 테스트 하나가 실패하는 작은 저장소입니다. 모든 실행에서 모델, 커밋, 프롬프트, 권한, 툴 접근 조건을 동일하게 유지합니다. 엣지 케이스를 수정하고, 회귀 테스트를 추가하고, 전체 테스트를 실행한 뒤 변경 파일을 보고하게 합니다. 상한이 없는 기준 실행을 마친 다음 픽스처를 깨끗한 상태로 되돌리고, 상한을 둔 조건에서 다시 실행합니다.

비용을 보기 전에 결과물부터 평가합니다.

판단 기준은 응답당 토큰이 아니라 검수 통과 작업당 비용입니다. 낮은 추론 강도에서 리뷰나 수정 작업을 한 번 더 해야 한다면, 처음부터 높은 강도로 깔끔하게 끝낸 실행보다 오히려 비용이 커질 수 있습니다. 더 폭넓은 Claude effort level 비교에도 같은 원리가 적용되지만, 새 설정을 사용하면 선택한 상한을 Claude Code에서 강제할 수 있습니다.

추론 강도 상한의 효과가 큰 일곱 가지 활용처

다음 활용 사례는 운영상 효과를 가장 명확하게 얻는 주체 순으로 정리했습니다.

1. 일상 작업을 관리하는 플랫폼 팀

20명 또는 200명의 개발자를 지원하는 플랫폼 팀이라면 관리형 설정에 medium을 지정하고, 더 낮은 수준도 선택할 수 있게 두되 정책 예외는 측정 결과에 따라 승인할 수 있습니다. 효과는 단순한 토큰 감소에 그치지 않습니다. 노트북, IDE 세션, 클라우드 공급자 경로 전반에 일관된 기본 경계를 적용하므로 비용과 품질을 의미 있게 비교할 수 있습니다.

2. API 요금제 Claude Code를 관리하는 FinOps 담당자

FinOps 담당자는 관리형 상한과 OpenTelemetry를 결합해 effort, 모델, 팀, 코스트 센터별로 데이터를 묶을 수 있습니다. 절차는 간단합니다. 상한이 없는 기준선을 관찰하고, 파일럿 그룹에 상한을 도입한 뒤, 검수 통과 작업당 비용을 비교합니다. 어느 effort level이 비싸게 느껴지는지를 두고 논쟁하는 대신 실제 산출물에 연결된 보고서를 얻게 됩니다.

3. Bedrock, Google Cloud 또는 Foundry를 사용하는 기업

규제 산업의 기업은 조달이나 데이터 통제를 위해 선택한 클라우드로 모델 요청을 보낼 수 있습니다. Claude Code 클라이언트가 매 요청 전에 maxEffortLevel을 적용하므로 조직은 공급자가 달라도 하나의 effort 정책을 유지할 수 있습니다. 모든 공급자 콘솔이 동일한 제어 기능을 제공할 때까지 기다리지 않고도 정책을 일관되게 적용할 수 있다는 점이 장점입니다.

4. 반복 수정을 실행하는 CI 관리자

Claude Code로 종속성 업데이트, 포매팅 수정, 테스트 유지보수, 문서 변경을 처리하는 팀이라면 해당 저장소의 상한을 low 또는 medium으로 둘 수 있습니다. 정확한 수준은 작업 픽스처로 결정해야 합니다. 품질이 유지되는 값을 찾고 나면 플래그, 스킬, 모델 기본값 때문에 일상 자동화가 더 깊은 추론 모드로 올라가는 일을 막을 수 있습니다.

5. 작업 난이도별 정책이 필요한 모노레포 관리자

개인 설정에는 medium 상한을 유지하면서, 문서나 생성 코드 저장소에는 더 낮은 공유 상한을 커밋하고, 난도가 높은 시스템 저장소에는 더 넓은 범위를 허용할 수 있습니다. 저장소마다 자체 경계를 갖게 되는 셈입니다. 개발자가 매번 명령을 기억하는 데 의존하지 않고 비용 정책이 작업을 따라가도록 만들 수 있습니다.

6. 여러 고객 저장소를 오가는 컨설팅 팀

컨설턴트는 개인 설정의 medium 상한을 기준으로 삼고, 각 고객 저장소의 공유 설정에서 필요하면 더 엄격한 값을 지정할 수 있습니다. 같은 노트북으로 소규모 콘텐츠 사이트, 성숙한 애플리케이션, 비용에 민감한 유지보수 계약을 오갈 때 발생하는 설정 편차를 줄여줍니다. 프로젝트 파일에는 다음 담당자가 확인할 운영 방식도 함께 남습니다.

7. 제한된 모델 예외가 필요한 Staff Engineer

Staff Engineer는 modelSettings를 이용해 특정 설정 소스의 전역 상한에서 모델 하나만 제외하면서도, 안전이 중요한 저장소에는 별도의 낮은 상한을 유지할 수 있습니다. 해당 설정 소스가 허용하는 곳에서는 모델에 여유를 주되, 예외가 보편적인 우회로로 바뀌지는 않습니다. 더 엄격한 프로젝트 또는 조직 정책 아래에 놓이는 정밀한 예외를 만들 수 있습니다.

이 설정을 바탕으로 만들 만한 제품

1. Effort 회귀 게이트 — 가장 유망한 기회

저장소의 검수 작업 모음을 허용된 effort level별로 실행한 뒤 통과율, 리뷰 결함, 소요 시간, 토큰, 비용을 보여주는 CLI와 CI 검사를 만들 수 있습니다. 플랫폼 엔지니어링 팀이 비용을 지불할 이유도 분명합니다. 상한이 생기는 순간, 일상 작업의 추론 강도를 어디까지 낮춰야 수정 비용이 절감액을 잠식하지 않는지 확인해야 하기 때문입니다.

상업적 수요 신호도 이례적으로 강합니다. ai code review의 미국 월간 검색량 추정치는 1,300회이며 CPC는 $62.38입니다. 가장 작은 판매 가능 버전은 동일한 깨끗한 픽스처에서 두 effort 프로필을 비교하고, 필수 테스트나 리뷰 규칙이 회귀하면 정책 변경을 차단하는 로컬 실행기와 GitHub 검사입니다.

난점은 벤치마크에 있습니다. 범용 코딩 점수는 복제하기 쉽고 구매자의 저장소와 연결성도 약합니다. 팀이 보유한 비공개 작업 모음, 리뷰 기준, 모델 업데이트에 따른 이력이 방어력을 만듭니다. 이 데이터가 없다면 또 하나의 대시보드에 불과합니다.

2. Claude Code effort 정책 린터

사용자, 공유 프로젝트, 프로젝트 로컬, 명령줄, 관리형 설정 소스를 모델별 상한 표 하나로 정리하는 읽기 전용 정책 검사기를 만들 수 있습니다. 플랫폼 팀과 보안 팀은 전역 예외라고 잘못 이해한 max 설정, 예상과 달리 우선 적용된 낮은 프로젝트 상한, 아직 2.1.267 이전 버전을 실행하는 환경을 찾아내는 데 활용할 수 있습니다.

claude code의 미국 월간 검색량 추정치는 550,000회이며, 실제 검색 질문에는 “What effort level should I use for a Claude code?”가 포함됩니다. 검색량은 크지만 구매 의도가 선명한 키워드는 아닙니다. 그래도 설정 혼란이라는 문제는 분명합니다. MVP에는 설정 소스 탐색, 버전 감지, JSON 검증, 가장 낮은 상한이 최종 적용되는 이유 설명만 있으면 됩니다.

난점은 플랫폼 종속 위험입니다. Anthropic이 최종 적용 설정을 보여주는 자체 검사기를 추가할 수 있습니다. 단순히 설정 화면을 보기 좋게 만드는 수준을 넘어, 정책 변경 알림과 전체 환경 인벤토리, 감사 증빙까지 제공해야 오래가는 제품이 됩니다.

3. Effort 인식형 Claude Code 비용 모니터

실제 적용된 effort 속성을 토큰, 비용, 모델, 쿼리 소스, 저장소, 품질 검사와 연결하고 Anthropic 및 클라우드 공급자 배포 환경을 아우르는 전용 OpenTelemetry 대시보드를 만들 수 있습니다. FinOps와 개발자 경험 팀은 또 하나의 토큰 합계가 아니라 정책과 결과물의 연결에 비용을 지불합니다.

llm observability의 미국 월간 검색량 추정치는 590회이며 CPC는 $37.45입니다. 기존 가격도 예산 항목이 존재함을 보여줍니다. Datadog Agent Observability는 LLM span 40,000개까지 무료로 시작하고, Pro는 span 100,000개에 월 $160부터 시작합니다. 전용 MVP는 OpenTelemetry collector 프리셋, 상한 인벤토리와 함께 실제 effort, 검수 통과 작업당 비용, 모델 또는 정책 변경 후 회귀를 보여주는 세 가지 화면으로 구성할 수 있습니다.

난점은 경쟁과 인과관계입니다. 관측성 공급자들은 이미 토큰과 비용을 수집하고 있으며, 상한 적용 후 청구액이 줄었다고 해서 상한이 원인이라고 단정할 수는 없습니다. 신뢰를 얻으려면 조건을 맞춘 평가나 변화 시점에 근거한 증거가 필요합니다.

세 가지 중에서는 effort 회귀 게이트가 가장 유망합니다. 유료 엔지니어링 의사결정과 가장 가까운 수요를 갖고 있으며, Anthropic이 모델이나 effort 보정을 바꿀 때마다 비공개 평가 이력의 가치도 커집니다.

추론 강도 상한으로 해결되지 않는 것

추론 강도 상한이 청구액 감소를 보장하지는 않습니다. Effort는 출력 토큰, 툴 사용 방식, 사고 과정에 영향을 주지만 모델 선택, 코드베이스 규모, 캐시 동작, 병렬 자동화도 여전히 중요합니다. Claude Max와 Pro 구독자는 사용량이 요금제에 포함되므로 /usage에 표시되는 세션 비용이 실제 청구액은 아닙니다.

모든 코딩 작업에서 low가 안전해지는 것도 아닙니다. Anthropic은 워크로드를 직접 테스트하라고 명시하며, 동일한 effort 명칭도 모델마다 다르게 보정됩니다. 한 모델의 medium 실행을 다른 모델의 medium과 고정된 추론량처럼 기계적으로 비교할 수는 없습니다.

특정 모델에 절대적인 우회권을 만들어주지도 않습니다. 모델별 max 항목은 같은 설정 소스의 최상위 상한만 제거합니다. 다른 설정 소스에는 여전히 더 낮은 상한이 있을 수 있고, 조직의 effort 제한이 그보다 더 낮을 수도 있습니다.

마지막으로 /status는 어떤 파일을 불러왔는지는 확인하지만, 각 키에 대해 어느 파일의 값이 최종 적용됐는지는 알려주지 않습니다. 자동화 환경에서는 실제 적용된 effort 텔레메트리 속성이 더 명확한 기록입니다.

다음 주 첫 실행 과제

다음 주에 일상적인 저장소 작업 하나를 고릅니다. 상한이 없는 기준선을 기록하고, 사용자 수준에 medium 상한을 추가한 뒤, 문서에 나온 Sonnet 예외를 넣고, 공유 프로젝트 파일에는 low를 지정합니다. 불러온 설정 소스와 세션 헤더의 effort를 확인하고, 동일하게 초기화한 픽스처에서 작업을 반복한 다음 /usage 비용보다 검수 품질을 먼저 비교합니다. 품질이 유지되면 검증한 상한을 적절한 공유 또는 관리형 범위로 승격합니다. 실패하면 해당 워크로드에 적용된 가장 엄격한 상한을 높이거나 제거하고 증거는 보존합니다.

엔지니어링 워크플로에 맞춘 effort 정책, 평가 게이트, 비용 텔레메트리가 필요하다면 AI 프로덕션 시스템을 확인해 보세요.