Настройка 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 или OpenTelemetry в Claude Code.

Что именно меняет maxEffortLevel

У effortLevel и maxEffortLevel разные задачи. Первый задаёт желаемый уровень усилий для сессии или модели, второй — границу, которую запрос не может превысить.

Если предел установлен на medium, разработчик по-прежнему может выбрать low или medium. Запросы на high, xhigh или max будут выполняться на уровне medium. Ограничение также действует на уровень, выбранный через /effort, меню /model, флаг --effort, переменную CLAUDE_CODE_EFFORT_LEVEL и настройки модели по умолчанию. Claude Code применяет его на стороне клиента перед каждым запросом, поэтому одна и та же политика работает при маршрутизации трафика модели через Anthropic, Amazon Bedrock, Agent Platform от Google Cloud или Microsoft Foundry.

Главное правило легко упустить: побеждает самый низкий предел среди всех загруженных областей настроек. Обычно в Claude Code действует иерархия, где управляемые настройки имеют приоритет над параметрами командной строки, файлами проекта и пользовательскими настройками. Но maxEffortLevel — ограничительное исключение. Более низкий предел проекта останется в силе, даже если управляемый или пользовательский источник разрешает больше.

Настройка Claude Code: глобальный предел, исключение для модели и более строгое правило проекта

Сначала проверьте 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"
}

Итог намеренно получается строгим:

Исключение для модели не отменяет правило проекта. Оно лишь снимает пользовательский предел medium для Sonnet. Именно эта деталь чаще всего создаёт ложное впечатление, будто исключение действует безусловно.

Корпоративную политику можно развернуть тем же верхнеуровневым ключом через управляемые настройки. Тогда предел будет действовать для всех пользователей, охваченных этим управляемым источником, независимо от поддерживаемого провайдера. Если для роли Enterprise также задан лимит усилий, Claude Code применит более низкое из двух ограничений.

Как проверить предел уровня усилий

Корректный JSON ещё не доказывает, что сработал нужный предел. Следует проверить и загруженные источники, и фактически применённый уровень.

1. Выполните /status в Claude Code. Строка Setting sources подтвердит загрузку User settings, Project settings и Managed settings, если они есть. Однако она не показывает, из какого источника пришёл каждый отдельный ключ.
2. Если источник не отображается или новый ключ словно игнорируется, запустите claude doctor. Команда перечислит отклонённые элементы настроек. Опубликованная JSON-схема может отставать от новой версии CLI, поэтому одно лишь предупреждение редактора ещё ничего не доказывает.
3. Посмотрите заголовок сессии рядом с названием модели. Claude Code показывает там текущий уровень усилий, а при его изменении ненадолго выводит значение и в нижней строке.
4. В репозитории из примера запросите /effort max. Проектный предел low всё равно останется в силе: запрос более высокого уровня не сможет его повысить.
5. В неинтерактивной инфраструктуре проверяйте атрибут effort у метрик claude_code.cost.usage и claude_code.token.usage. Он фиксирует применённый к каждому запросу уровень вместе с моделью и источником запроса.

Последняя проверка особенно важна для Bedrock, Google Cloud и Foundry. Политику применяет Claude Code ещё до передачи запроса провайдеру, а телеметрия показывает, какой уровень Claude Code использовал фактически.

Качество и расходы нужно тестировать отдельно

Не стоит внедрять предел medium или low только потому, что его название звучит экономно. Возьмите типовую задачу, которую команда хорошо знает, и проведите сопоставимые прогоны.

Подойдёт небольшой репозиторий с одним падающим тестом парсера. Во всех прогонах оставьте одинаковыми модель, коммит, промпт, разрешения и доступ к инструментам. Задание тоже должно быть одним и тем же: исправить граничный случай, добавить регрессионный тест, запустить набор тестов и перечислить изменённые файлы. Сначала выполните прогон без ограничения, затем восстановите чистое исходное состояние и повторите задачу с заданным пределом.

Сначала оцените результат и только потом смотрите на стоимость:

Главный показатель для решения — стоимость принятой задачи, а не число токенов в одном ответе. Прогон с меньшим усилием, после которого требуется повторное ревью или исправление, может обойтись дороже чистого результата на более высоком уровне. Тот же принцип применим к более широкому сравнению уровней усилий Claude, но новый параметр позволяет принудительно закрепить выбранную верхнюю границу в Claude Code.

Семь сценариев, где предел усилий окупается

Сценарии расположены по тому, кто получит наиболее очевидную практическую пользу.

1. Платформенные команды, управляющие типовыми задачами

Платформенная команда, которая поддерживает 20 или 200 разработчиков, может задать medium в управляемых настройках, сохранить доступ к более низким уровням и менять политику для исключений только по результатам измерений. Выгода не сводится к сокращению токенов. Единая граница действует на ноутбуках, в IDE-сессиях и при работе через облачных провайдеров, поэтому сравнения стоимости и качества становятся сопоставимыми.

2. Специалисты FinOps в Claude Code с оплатой через API

Ответственный за FinOps может объединить управляемый предел с OpenTelemetry и группировать данные по effort, модели, команде и центру затрат. Порядок прост: зафиксировать исходный уровень без ограничения, подключить предел для пилотной группы и сравнить стоимость принятой задачи. Вместо споров о том, какой уровень усилий кажется дорогим, появляется отчёт, привязанный к выполненной работе.

3. Компании, использующие Bedrock, Google Cloud или Foundry

Компания из регулируемой отрасли может направлять запросы к моделям через выбранное облако ради закупочных процедур или контроля данных. Клиент Claude Code применяет maxEffortLevel перед каждым запросом, поэтому единая политика усилий работает у всех этих провайдеров. Организация получает одинаковое правило и не ждёт, пока в каждой панели провайдера появится аналогичная настройка.

4. Команды CI, автоматизирующие повторяющиеся исправления

Команда, которая запускает Claude Code для обновления зависимостей, исправления форматирования, поддержки тестов или правок документации, может ограничить такие репозитории уровнем low или medium. Конкретный уровень следует выбирать на тестовых задачах. Если качество сохраняется, предел не позволит флагу, навыку или настройке модели по умолчанию перевести рутинную автоматизацию в режим более глубоких рассуждений.

5. Владельцы монорепозиториев с разными типами задач

Владелец монорепозитория может сохранить личный предел medium, зафиксировать более низкое общее ограничение в репозитории документации или сгенерированного кода, а для сложного системного репозитория оставить более широкую границу. Каждый репозиторий несёт собственную политику. Так правила расходов следуют за характером работы, а разработчикам не приходится каждый раз вспоминать нужную команду.

6. Консультанты, работающие с репозиториями разных клиентов

Консультант может использовать личный предел medium как базовый, а каждому клиентскому репозиторию позволить задавать более строгое общее правило. Это уменьшает расхождения в конфигурации, когда один ноутбук используется для небольшого контентного сайта, зрелого приложения и контракта на поддержку с жёсткими требованиями к расходам. Кроме того, файл проекта документирует рабочий режим для следующего специалиста.

7. Staff-инженеры, которым нужно точечное исключение для модели

Staff-инженер может через modelSettings освободить одну модель от глобального предела конкретного источника, а в критичном для безопасности репозитории сохранить другое, более строгое ограничение. Модель получает дополнительную свободу там, где источник это разрешает, но исключение не превращается в универсальный обход. В результате точечное послабление по-прежнему подчиняется более строгой политике проекта или организации.

Что имеет смысл построить вокруг этой функции

1. Регрессионный контроль уровней усилий — самая сильная возможность

Можно создать CLI и CI-проверку, которая запускает набор эталонных задач репозитория на разрешённых уровнях усилий, а затем показывает долю успешных результатов, дефекты ревью, длительность, токены и стоимость. Платформенные команды готовы платить за ответ на вопрос, который сразу возникает вместе с новым пределом: насколько можно снизить уровень для рутинной работы, прежде чем исправления сведут экономию на нет?

Коммерческий сигнал здесь особенно заметен. У запроса ai code review оценивается в 1,300 поисков в месяц в США, а CPC составляет $62.38. Минимальный коммерческий продукт — локальный исполнитель и GitHub-проверка, которые сравнивают два профиля усилий на одной и той же чистой тестовой задаче и блокируют изменение политики, если обязательные тесты или правила ревью показывают регрессию.

Слабое место — сам бенчмарк. Универсальную оценку качества программирования легко скопировать, и она слабо связана с репозиторием покупателя. Настоящую защиту создают закрытый набор задач команды, критерии ревью и история по мере обновления моделей. Без этих данных получится всего лишь ещё одна панель мониторинга.

2. Линтер политик уровня усилий Claude Code

Можно создать инспектор политик в режиме только для чтения: он сведёт пользовательские, общие проектные, локальные проектные, параметры командной строки и управляемые настройки в единую таблицу пределов для каждой модели. Платформенные команды и специалисты по безопасности смогут обнаружить исключение max, которое ошибочно считали глобальным, неожиданно победивший нижний предел проекта или машины, где всё ещё установлена версия до 2.1.267.

У запроса claude code оценивается в 550,000 поисков в месяц в США, а среди реальных вопросов встречается «What effort level should I use for a Claude code?». Аудитория у такого запроса широкая и не обязательно готова покупать, но путаница в конфигурации очевидна. Для MVP достаточно обнаруживать источники, определять версию, проверять JSON и объяснять, какой из пределов победил.

Главный риск связан с платформой: Anthropic может добавить штатный инспектор итоговых настроек. Чтобы продукт оставался полезным, ему понадобятся оповещения об отклонениях от политики, инвентаризация парка и подтверждения для аудита, а не просто более красивая страница настроек.

3. Мониторинг расходов Claude Code с учётом уровня усилий

Можно создать специализированную панель OpenTelemetry, которая объединяет применённый атрибут effort с токенами, стоимостью, моделью, источником запроса, репозиторием и проверками качества в развёртываниях Anthropic и облачных провайдеров. Команды FinOps и Developer Experience будут платить за связь между политикой и результатом, а не за очередной общий счётчик токенов.

У запроса llm observability оценивается в 590 поисков в месяц в США, а CPC составляет $37.45. Наличие бюджета подтверждают цены существующих решений: Datadog Agent Observability предлагает бесплатный тариф до 40,000 LLM-спанов, а Pro начинается с $160 в месяц за 100,000 спанов. Специализированный MVP может включать готовую конфигурацию коллектора OpenTelemetry, инвентаризацию пределов и три представления: применённые усилия, стоимость принятой задачи и регрессии после смены модели или политики.

Проблемы здесь — конкуренция и причинно-следственная связь. Платформы наблюдаемости уже собирают данные о токенах и стоимости, а снижение счёта после ввода предела ещё не доказывает, что причиной был именно он. Чтобы заслужить доверие, продукту нужны сопоставимые оценки или анализ точек изменения.

Из трёх вариантов лучше всего выглядит регрессионный контроль уровней усилий. Спрос здесь ближе всего к оплачиваемому инженерному решению, а закрытая история оценок становится ценнее с каждым изменением модели или калибровки усилий со стороны Anthropic.

Чего предел не решает

Предел усилий не гарантирует уменьшения счёта. Уровень влияет на выходные токены, работу инструментов и рассуждения, но выбор модели, размер кодовой базы, поведение кэша и параллельная автоматизация тоже имеют значение. У подписчиков Claude Max и Pro использование включено в тариф, поэтому стоимость сессии в /usage не равна их счёту.

Он не делает low безопасным для любой задачи программирования. Anthropic прямо рекомендует тестировать конкретную нагрузку, а одинаковые названия уровней по-разному откалиброваны в разных моделях. medium у одной модели нельзя механически сравнивать с medium у другой как фиксированный объём рассуждений.

Он не создаёт абсолютного обхода ограничений для модели. Запись max для отдельной модели снимает только верхнеуровневый предел того же источника. Другой источник всё ещё может задать более низкую границу, а организационный лимит усилий может оказаться ещё ниже.

Наконец, /status подтверждает загрузку файлов, но не показывает файл-победитель для каждого ключа. В автоматизации атрибут телеметрии effort надёжнее отражает реально применённый уровень.

Что сделать в понедельник

На следующей неделе выберите одну типовую задачу в репозитории. Зафиксируйте исходный прогон без ограничения, добавьте пользовательский предел medium и описанное исключение для Sonnet, а затем задайте low в общем файле проекта. Проверьте загруженные источники и уровень усилий в заголовке сессии, повторите задачу на том же чистом исходном состоянии и сравните качество приёмки до того, как смотреть на стоимость в /usage. Если качество сохранилось, перенесите проверенный предел в подходящую общую или управляемую область. Если нет — повысьте либо снимите самое строгое ограничение для этой нагрузки и сохраните результаты измерений.

Если вам нужны политика усилий, контур оценки и телеметрия расходов для инженерного процесса, изучите промышленные ИИ-системы.