Optimización de costos de Claude Code: checklist de 25 puntos

Activa cache_control en tu prompt de sistema

Si usas la API directamente, envuelve tu prompt de sistema (o cualquier bloque de contexto grande que se repita en varias solicitudes) en un bloque cache_control: {"type": "ephemeral"}. Los tokens en caché cuestan el 10% de los tokens de entrada sin caché. En un prompt de sistema de 10.000 tokens repetido 50 veces al día, eso son 4,5 millones de tokens ahorrados por día.

system=[{
  "type": "text",
  "text": your_large_system_prompt,
  "cache_control": {"type": "ephemeral"}
}]

Cachea documentos antes de consultarlos varias veces

Si vas a correr varios prompts contra el mismo documento (un trozo de código base, una especificación, un PDF), cachea el documento en la primera solicitud. Cada solicitud posterior que pegue en la caché paga el 10% por el documento. El punto de equilibrio está en 2 solicitudes; rinde a partir de 3.

Vigila la tasa de aciertos de caché en las cabeceras de respuesta

Lee usage.cache_read_input_tokens en cada respuesta de la API. Si tu tasa de aciertos está por debajo del 60% en una aplicación con prompt de sistema pesado, la caché está expirando antes de que la puedas aprovechar. La caché efímera dura 5 minutos; asegúrate de que tus solicitudes lleguen dentro de esa ventana.

Mantén el contenido cacheado al inicio del prompt

La caché se indexa por contenido y por posición. Si pones contenido dinámico (mensaje del usuario, fecha actual) antes de tu prompt de sistema cacheado, la caché no va a acertar. Pon primero el bloque estático y grande. Pon el contenido dinámico al final.

Usa caché extendida (TTL de 1 hora) para contextos grandes y estables

La caché efímera estándar dura 5 minutos. Si tu contexto es grande (un índice completo del código base) y cambia poco, Anthropic ofrece caché extendida con TTL de 1 hora a un costo de escritura de caché un poco mayor pero costo de lectura de caché más bajo por hora. Vale la pena para contextos por encima de los 100K tokens.

Cachea el contenido del CLAUDE.md en sesiones largas de Claude Code

En sesiones de Claude Code, el contenido del CLAUDE.md se antepone a cada mensaje. Si tu CLAUDE.md tiene 5.000 tokens, son 5.000 tokens facturados por turno. Mantén el CLAUDE.md ligero y considera dividir el contexto específico de cada proyecto en un archivo aparte que se referencia solo cuando hace falta, en vez de inyectarse en cada turno.

Usa Haiku para tareas de clasificación y enrutamiento

Haiku 3.5 cuesta $0,25 por millón de tokens de entrada frente a $3 de Sonnet 4.5. Para tareas que en el fondo son emparejamiento de patrones (clasifica este error, categoriza este ticket, ¿este texto cumple estos criterios?), Haiku da una calidad equivalente a una doceava parte del precio. Audita tus subagentes—cualquiera con un máximo de 3 turnos y salida tipo clasificación debería correr en Haiku.

Usa Sonnet solo cuando el razonamiento sea lo que importa

Sonnet vale el precio para: revisión de código, auditoría de seguridad, razonamiento multipaso, cualquier cosa que exija sintetizar información en conflicto. No vale el precio para: generación de documentación, escritura de changelogs, extracción estructurada de datos o cualquier cosa con formato determinista.

Define max_tokens conservador por agente

La API factura por tokens generados, no por tokens solicitados. Pero fijar un max_tokens alto cuando no lo necesitas hace que Claude pueda generar más de lo necesario. Para salidas estructuradas (JSON, YAML, tablas), un max_tokens más bajo además fuerza a Claude a ser más conciso. Audita la longitud real de salida de cada agente y fija max_tokens al 120% del p95 observado.

Usa streaming para salidas largas; cancela pronto si hace falta

Si usas streaming, puedes cancelar a media salida cuando ya tengas suficiente. En la API, las respuestas parciales por streaming se facturan por los tokens generados hasta ese punto, no por todo el max_tokens. En aplicaciones donde a menudo solo necesitas la primera parte de una salida larga, streaming + cancelación temprana puede reducir los costos de tokens de salida en un 40–70%.

Evita Opus para tareas que Sonnet maneja igual de bien

Opus cuesta $15 por millón de tokens de entrada—5 veces Sonnet. La diferencia de calidad entre Opus y Sonnet es notable en trabajo creativo abierto y razonamiento multipaso complejo. Para tareas de código, salida estructurada y la mayoría de flujos de desarrollo, Sonnet iguala la calidad de Opus a una quinta parte del precio. Haz benchmark antes de poner a Opus por defecto.

Ejecuta /compact antes de que las sesiones largas pasen los 50K tokens

El comando /compact de Claude Code resume el contexto de la sesión y lo reemplaza por una versión comprimida. Una sesión de 100K tokens se vuelve un resumen de 5K tokens. La pérdida de calidad para la continuidad de la tarea es mínima; el ahorro de costo es notable. Córrelo cada 2 horas en sesiones activas.

Usa Grep y Read en lugar de dejar que Claude explore el código base

Cuando Claude explora un código base sin dirección, lee muchos archivos para entender el contexto. Dirigirlo primero a los archivos relevantes («lee app/api/users.ts y el modelo User») reduce el contexto en un orden de magnitud. Usa Grep para encontrar los archivos relevantes antes de pedirle a Claude que los lea.

Mantén el CLAUDE.md por debajo de las 300 líneas

Cada línea del CLAUDE.md es un token que se antepone a cada mensaje en una sesión de Claude Code. Un CLAUDE.md de 3.000 líneas suma ~4.500 tokens a cada turno. Uno de 300 líneas suma ~450. El artículo sobre el CLAUDE.md de 3000 líneas cubre cómo estructurarlo para gastar el mínimo de tokens sin perder cobertura.

Acota el acceso a herramientas de cada subagente a lo justo y necesario

Un subagente con acceso a todas las herramientas las va a usar. Un subagente con acceso solo a [Read, Grep] no puede levantar un proceso Bash y cargar un log de 10MB en contexto. La restricción de herramientas es a la vez una guarda de costo y un control de seguridad.

Pasa diffs, no archivos completos, a los agentes de revisión

Cuando corres un agente de revisión de código, pásale la salida de git diff HEAD~1 en lugar del contenido completo del archivo. Un archivo de 2.000 líneas con 40 líneas modificadas cuesta 2.000 tokens si pasas el archivo y 200 tokens si pasas el diff. En flujos de revisión, el diff casi siempre alcanza.

Usa la Batch API para cualquier carga que no sea sensible al tiempo

La Batch API de Anthropic cuesta un 50% menos por token que la API en tiempo real. Acepta hasta 10.000 solicitudes por lote y procesa en menos de 24 horas. Si tu caso de uso no necesita respuesta en menos de 60 segundos, la Batch API es la opción correcta. Análisis de documentos, generación de pruebas, escritura de changelogs—todos elegibles para batch.

Deduplica solicitudes antes de enviarlas a la API

Si tu aplicación puede llegar a enviar el mismo prompt dos veces (consulta idéntica de un usuario, mismo análisis de documento), contrasta tu solicitud con un hash local antes de llamar a la API. Un hash SHA-256 de (modelo + prompt_sistema + mensaje_usuario) identifica los duplicados. Cachea la respuesta indexada por ese hash. Una tasa de duplicados del 5% en una aplicación de alto volumen es un ahorro significativo a fin de mes.

Agrupa solicitudes similares en un único prompt multiparte

Si necesitas hacer la misma operación sobre 20 documentos (resumir, clasificar, extraer), una sola solicitud multidocumento suele costar menos que 20 solicitudes individuales, porque el prompt de sistema se paga una vez. Pruébalo contra tu matemática real de tokens—los lotes muy grandes pueden superar los límites de contexto y obligarte a partirlos igualmente.

Implementa coalescing de solicitudes para consultas concurrentes idénticas

En aplicaciones con mucho tráfico, varios usuarios pueden disparar simultáneamente la misma llamada subyacente a la API (mismo informe, mismo análisis). El coalescing: cuando una solicitud está en curso, las solicitudes idénticas posteriores esperan la primera respuesta y la comparten. Ahorra llamadas a la API en proporción a tus picos de tráfico.

Programa los lotes en horas de baja demanda para acelerar Batch API

El tiempo de procesamiento de la Batch API varía con la carga de Anthropic. Enviar lotes en horas de tráfico bajo (UTC 02:00–08:00) suele dar tiempos de respuesta más rápidos sin costo adicional. Para lotes con ventana de 24 horas, enviar a medianoche y recibir resultados por la mañana es un patrón fiable.

Define límites de presupuesto por sesión y por día con hooks PreToolUse

Un hook PreToolUse se ejecuta antes de cada llamada a herramienta. Un hook de 30 líneas que lee el costo acumulado de tu sesión desde ~/.claude/projects/ y la detiene si supera los $10 evita escenarios de Tokenocalipsis. El hook se dispara antes de que la llamada a la API salga de tu máquina; no hay punto de aplicación más temprano que ese.

Pon límites max_turns en todos los subagentes

Un subagente sin límite max_turns puede correr indefinidamente. Pon max_turns: 10 en la mayoría de agentes y max_turns: 5 en agentes con tareas simples y acotadas. Un subagente desbocado a 50 turnos cuesta entre 5 y 10 veces más que uno bien acotado en la misma tarea.

Loguea y alerta sobre anomalías de costo, no solo sobre totales mensuales

Las alertas de facturación mensual cazan eventos de Tokenocalipsis cuando el daño ya está hecho. Las alertas diarias de costo (correo o webhook de Slack cuando el gasto del día supera 2x el baseline) los cazan a tiempo de intervenir. La consola de Anthropic admite alertas de umbral de gasto diario. Configúralas.

Cierra las sesiones zombi antes de que se acumulen

Una sesión de Claude Code dejada abierta pero desatendida sigue facturando cuando un subagente hace una llamada a herramienta. Revisa las sesiones activas con claude sessions list y cierra las que no estés usando. En una máquina compartida entre desarrolladores, las sesiones zombi son una fuente de costo significativa e invisible.