Cómo limitar el esfuerzo en Claude Code con maxEffortLevel

Respuesta breve

Actualiza a Claude Code 2.1.267 o una versión posterior y añade "maxEffortLevel": "medium" al archivo de configuración que corresponda a las personas y los proyectos que quieras controlar. Usa ~/.claude/settings.json como tope global personal, .claude/settings.json para quienes trabajen en un repositorio concreto o la configuración administrada para establecer una regla en toda la organización.

La opción acepta low, medium, high, xhigh o max. El valor max indica que esa fuente no impone ningún tope al esfuerzo. Si la clave no está definida, tampoco hay límite.

Se trata de un limitador de velocidad, no de un presupuesto. Restringe cuánto puede razonar Claude en una solicitud, pero no fija una asignación de tokens, una cuota en dólares ni un límite de uso de la suscripción. Mide esos aspectos por separado con /usage, Claude Console o la telemetría OpenTelemetry de Claude Code.

Qué cambia realmente con maxEffortLevel

effortLevel y maxEffortLevel cumplen funciones distintas. El nivel de esfuerzo es el valor solicitado para una sesión o un modelo; el nivel máximo de esfuerzo es la frontera que esa solicitud no puede superar.

Con el tope en medium, un desarrollador todavía puede elegir low o medium. Si solicita high, xhigh o max, la ejecución se queda en medium. El límite también intercepta el esfuerzo pedido mediante /effort, el selector /model, --effort, CLAUDE_CODE_EFFORT_LEVEL y el valor predeterminado del modelo. Claude Code lo aplica en el cliente antes de cada solicitud, por lo que la misma política funciona tanto si el tráfico del modelo pasa por Anthropic como por Amazon Bedrock, Agent Platform de Google Cloud o Microsoft Foundry.

Hay una regla decisiva que resulta fácil pasar por alto: siempre gana el tope más bajo entre todos los ámbitos cargados. La configuración habitual de Claude Code suele respetar una jerarquía en la que la configuración administrada prevalece sobre la línea de comandos, los archivos del proyecto y la configuración del usuario. maxEffortLevel es una excepción restrictiva. Un tope inferior definido en el proyecto sigue ganando aunque una fuente administrada o de usuario permita más esfuerzo.

Cómo limitar el esfuerzo en Claude Code por usuario, modelo y proyecto

Primero ejecuta claude --version. Si la versión es anterior a 2.1.267, usa claude update antes de añadir la clave.

Para establecer un límite personal en todos los repositorios, incluye lo siguiente en ~/.claude/settings.json:

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

El valor de nivel superior limita todos los modelos compatibles a medium. La entrada de Sonnet 4.6 sustituye ese valor para Sonnet únicamente dentro de este archivo de usuario. Su valor max no obliga a Sonnet a funcionar con el esfuerzo máximo; significa que esta fuente concreta no limita ese modelo.

Ahora añade una regla más estricta para un repositorio en .claude/settings.json:

{
  "maxEffortLevel": "low"
}

El resultado efectivo es deliberadamente restrictivo:

La exención del modelo no atraviesa la regla del proyecto. Solo anula el tope medium de la fuente de usuario para Sonnet. Este es el error con más probabilidades de generar una falsa sensación de exención.

Para aplicar una política empresarial, distribuye la misma clave de nivel superior mediante la configuración administrada. Así, el tope se aplica a las personas cubiertas por esa fuente administrada con cualquier proveedor compatible. Si un rol Enterprise también tiene un límite de esfuerzo, Claude Code aplica el menor de los dos.

Cómo comprobar el tope antes de confiar en él

Que un archivo JSON sea válido no demuestra que se haya impuesto el tope previsto. Comprueba tanto las fuentes cargadas como el nivel aplicado.

1. Ejecuta /status dentro de Claude Code. La línea Setting sources confirma que se cargaron User settings, Project settings y cualquier Managed settings existente. No indica qué fuente aportó cada clave.
2. Ejecuta claude doctor si falta una fuente o si parece que una clave nueva se ignora. El comando enumera las entradas de configuración rechazadas. El esquema JSON publicado puede tardar en reflejar una versión nueva de la CLI, así que una advertencia del editor no basta para determinar el resultado.
3. Revisa el encabezado de la sesión, junto al nombre del modelo. Claude Code muestra allí el esfuerzo actual y lo presenta brevemente en el pie cuando cambia.
4. En el repositorio del ejemplo, solicita /effort max. El tope low del proyecto sigue aplicándose; una petición superior no puede elevarlo.
5. En flotas no interactivas, inspecciona el atributo effort de claude_code.cost.usage y claude_code.token.usage. Registra el nivel aplicado a cada solicitud junto con el modelo y el origen de la consulta.

Esta última comprobación es especialmente importante en Bedrock, Google Cloud y Foundry. Claude Code aplica la política antes de que el proveedor reciba la solicitud, mientras que la telemetría revela el valor que realmente utilizó.

Cómo probar la calidad y el gasto por separado

No implantes un tope medium o low solo porque la etiqueta parezca económica. Toma una tarea rutinaria que el equipo ya conozca y compara ejecuciones equivalentes.

Un buen caso de prueba es un repositorio pequeño con una prueba fallida del analizador. Mantén iguales el modelo, el commit, el prompt, los permisos y el acceso a herramientas en cada ejecución: corrige el caso límite, añade una prueba de regresión, ejecuta la suite e informa qué archivos cambiaron. Ejecuta primero la referencia sin tope, restaura el caso de prueba limpio y después ejecuta la condición con límite.

Evalúa el resultado antes de mirar el costo:

La métrica que debe guiar la decisión es el costo por tarea aceptada, no los tokens por respuesta. Una ejecución con menos esfuerzo que exige otra revisión o una reparación puede costar más que una ejecución limpia con un nivel superior. La misma lógica se aplica al análisis más amplio de niveles de esfuerzo de Claude, pero la nueva opción permite hacer cumplir en Claude Code el límite superior elegido.

Siete escenarios en los que compensa un tope de esfuerzo

Estos casos de uso están ordenados según quién obtiene el beneficio operativo más claro.

1. Equipos de plataforma que controlan el trabajo rutinario

Un equipo de plataforma que atiende a 20 o 200 desarrolladores podría fijar medium en la configuración administrada, mantener disponibles los niveles inferiores y reservar los cambios de política para excepciones medidas. El beneficio no se limita a consumir menos tokens. También ofrece una frontera predeterminada y coherente entre portátiles, sesiones del IDE y rutas de proveedores de nube, lo que permite comparar el costo y la calidad con datos útiles.

2. Responsables de FinOps con Claude Code facturado por API

Un responsable de FinOps podría combinar un tope administrado con OpenTelemetry, agrupando los datos por effort, modelo, equipo y centro de costos. El flujo es sencillo: observar la referencia sin límite, introducir el tope en un grupo piloto y comparar el costo por tarea aceptada. Así, las discusiones sobre qué nivel parece caro se sustituyen por un informe vinculado al trabajo entregado.

3. Empresas que usan Bedrock, Google Cloud o Foundry

Una empresa regulada puede encaminar los modelos a través de la nube elegida por motivos de compras o controles de datos. El cliente de Claude Code aplica maxEffortLevel antes de cada solicitud, de modo que la organización puede usar una sola política de esfuerzo con esos proveedores. El resultado es una política uniforme sin tener que esperar a que cada consola ofrezca el mismo control.

4. Responsables de CI que ejecutan correcciones repetitivas

Un equipo que usa Claude Code para actualizar dependencias, corregir formato, mantener pruebas o modificar documentación podría limitar esos repositorios a low o medium. El nivel exacto debe decidirse con casos de prueba, pero, una vez validada la calidad, el tope impide que una opción de línea de comandos, una skill o el valor predeterminado del modelo lleve una automatización rutinaria a un modo de razonamiento más profundo.

5. Responsables de monorepos que separan el trabajo rutinario del complejo

Quien administra un monorepo podría conservar un tope personal medium, incorporar un límite compartido inferior a un repositorio de documentación o código generado y dejar un repositorio de sistemas más exigente con el margen general. Cada repositorio lleva su propia frontera. Así, la política de costos acompaña al trabajo y no depende de que cada desarrollador recuerde un comando.

6. Consultoras que alternan entre repositorios de clientes

Quien trabaja como consultor podría usar como base un tope personal medium y permitir que el repositorio de cada cliente imponga una configuración compartida más estricta. Esto reduce las diferencias de configuración cuando el mismo portátil pasa de un sitio de contenidos pequeño a una aplicación madura o un contrato de mantenimiento sensible al costo. El archivo del proyecto también documenta el modo operativo previsto para la siguiente persona.

7. Staff engineers que conservan una excepción limitada por modelo

Un staff engineer podría eximir un modelo del tope global de una fuente mediante modelSettings y mantener otro límite inferior en un repositorio crítico para la seguridad. Así, el modelo dispone de margen donde la fuente lo permite sin convertir la exención en una vía de escape universal. El beneficio es una excepción precisa que sigue supeditada a políticas más estrictas del proyecto o de la organización.

Qué productos vale la pena construir alrededor de este cambio

1. Puerta de regresión de esfuerzo: la mejor oportunidad

Se puede crear una herramienta de CLI y CI que ejecute la suite de tareas aceptadas de un repositorio con los niveles de esfuerzo permitidos y presente la tasa de éxito, los defectos de revisión, la duración, los tokens y el costo. Los equipos de plataforma de ingeniería pagarían por ella porque el tope plantea una pregunta inmediata sobre la calidad: ¿hasta dónde puede reducirse el esfuerzo del trabajo rutinario antes de que las reparaciones anulen el ahorro?

La señal de demanda tiene un carácter comercial poco habitual. ai code review registra una estimación de 1,300 búsquedas mensuales en Estados Unidos y un CPC de $62.38. La versión mínima vendible sería un ejecutor local acompañado de una comprobación de GitHub que compare dos perfiles de esfuerzo sobre el mismo caso limpio y bloquee el cambio de política cuando fallen las pruebas o las reglas de revisión obligatorias.

El obstáculo está en el benchmark. Una puntuación genérica de programación es fácil de copiar y guarda poca relación con el repositorio del comprador. La parte defendible es el conjunto privado de tareas del equipo, su rúbrica de revisión y su historial entre actualizaciones de modelos. Sin esos datos, no pasa de ser otro panel.

2. Linter de políticas de esfuerzo para Claude Code

Se puede crear un inspector de políticas de solo lectura que convierta las fuentes de usuario, proyecto compartido, proyecto local, línea de comandos y configuración administrada en una tabla de topes por modelo. Los equipos de plataforma y seguridad lo usarían para detectar una exención max que se daba por global, un límite inferior de proyecto que gana de forma inesperada o una flota que todavía ejecuta una versión anterior a 2.1.267.

claude code registra una estimación de 550,000 búsquedas mensuales en Estados Unidos, y entre las preguntas actuales aparece “What effort level should I use for a Claude code?”. Ese volumen es amplio y no implica una compra inmediata, pero la confusión de configuración es directa. Un MVP solo necesita descubrir fuentes, detectar versiones, validar JSON y explicar cuál es el tope inferior que prevalece.

El riesgo es la dependencia de la plataforma. Anthropic podría añadir un inspector nativo de configuración efectiva. Para perdurar, el producto tendría que incorporar alertas de desviación de políticas, inventario de flota y evidencia para auditorías, no limitarse a ofrecer una pantalla de configuración más atractiva.

3. Monitor de gasto de Claude Code con datos de esfuerzo

Se puede crear un panel especializado de OpenTelemetry que relacione el atributo effort aplicado con tokens, costo, modelo, origen de la consulta, repositorio y controles de calidad en implementaciones de Anthropic y de proveedores de nube. Los equipos de FinOps y experiencia de desarrollo pagarían por conectar la política con el resultado, no por otro total de tokens.

llm observability registra una estimación de 590 búsquedas mensuales en Estados Unidos y un CPC de $37.45. Los precios existentes confirman que hay presupuesto: Datadog Agent Observability comienza con un plan gratuito para 40,000 spans de LLM, mientras que Pro parte de $160 al mes para 100,000 spans. Un MVP especializado podría ofrecer un ajuste predefinido del colector de OpenTelemetry, un inventario de topes y tres vistas: esfuerzo aplicado, costo por tarea aceptada y regresiones tras cambiar un modelo o una política.

El obstáculo es doble: competencia y causalidad. Los proveedores de observabilidad ya recopilan tokens y costos, y que la factura baje después de introducir un tope no demuestra que este haya sido la causa. Para ganarse la confianza, el producto necesita evaluaciones equivalentes o evidencia de cambios de tendencia.

La puerta de regresión de esfuerzo es la mejor de las tres opciones. Su demanda está más cerca de una decisión de ingeniería con presupuesto, y su historial privado de evaluaciones gana valor cada vez que Anthropic cambia un modelo o la calibración del esfuerzo.

Lo que un tope de esfuerzo no resuelve

Un tope de esfuerzo no garantiza una factura menor. El esfuerzo influye en los tokens de salida, el uso de herramientas y el razonamiento, pero también importan el modelo elegido, el tamaño del código base, el comportamiento de la caché y la automatización en paralelo. Los suscriptores de Claude Max y Pro tienen el uso incluido en su plan, por lo que el costo de sesión que muestra /usage no es su factura.

Tampoco convierte low en una opción segura para cualquier tarea de programación. Anthropic recomienda expresamente probar la carga de trabajo, y un mismo nombre de esfuerzo se calibra de forma distinta según el modelo. Una ejecución medium en un modelo no representa una cantidad fija de razonamiento que pueda compararse mecánicamente con medium en otro.

No crea una exención absoluta para un modelo. Una entrada max específica solo elimina el tope superior de esa misma fuente. Otra fuente todavía puede imponer un límite inferior, y el límite de esfuerzo de una organización puede ser aún menor.

Por último, /status confirma qué archivos se cargaron, no cuál ganó para cada clave. En automatizaciones, el atributo de telemetría effort aplicado ofrece un registro más claro.

La acción para el lunes

Elige para la próxima semana una tarea rutinaria de un repositorio. Registra una referencia sin tope, añade un límite medium en el ámbito del usuario, incorpora la exención documentada para Sonnet y después define low en el archivo compartido del proyecto. Confirma las fuentes cargadas y el esfuerzo del encabezado de sesión, repite la tarea desde el mismo caso limpio y compara la calidad de aceptación antes de consultar el costo en /usage. Si la calidad se mantiene, lleva el tope probado al ámbito compartido o administrado adecuado. Si no, sube o elimina el límite más estricto para esa carga de trabajo y conserva la evidencia.

Si quieres incorporar a tu flujo de ingeniería una política de esfuerzo, una puerta de evaluación y telemetría de costos, consulta sistemas de IA en producción.