Contexto y costos

Los cuatro controles de contexto

El skill context-optimization de Pierre formaliza cuatro técnicas para ampliar la capacidad efectiva del contexto sin agrandar la ventana ni cambiar de modelo. Aplícalas en este orden:

1. Optimización del cache KV: mantené un prefijo de prompt estable al inicio (prompt de sistema, reglas, contexto fijo) para que el modelo reutilice el cache en lugar de recalcularlo todo. No reordenes lo que no cambia. Efecto: más rápido y más económico.
2. Enmascaramiento de observaciones: compacta las salidas voluminosas de herramientas. Después de leer un archivo de 2000 líneas, ya no necesitas las 2000 líneas en bruto en el contexto: queda el resultado útil, enmascara el resto.
3. Compactación: cuando el uso supera el 70 % aproximadamente, resume el contexto antiguo (eso es lo que hace /compact). Conserva la sustancia, elimina el verbatim.
4. Particionamiento del contexto: delega el trabajo voluminoso a sub-agentes con contexto aislado (módulo 5). El agente principal solo ve las conclusiones.

Resultado combinado: puedes sostener sesiones mucho más largas y complejas sin degradar la calidad ni disparar los costos. "Más capacidad" no proviene de una ventana más grande, sino de una mejor higiene del contexto.

Cuota, rendimiento y alternancia de modelos

El costo en dinero no es el único límite. También existe el rendimiento: la organización de Pierre tiene un tope de 4000 tokens de salida por minuto en Opus. Las llamadas a Claude son gratuitas en su entorno, pero este límite frena los flujos de trabajo masivamente paralelos o con mucha carga de razonamiento, que generan errores 429 (rate limit).

Las contramedidas concretas que él ha codificado:

• Reducir el paralelismo de lectura (un parámetro como PLAN_READS=1 en sus herramientas) para no saturar el rendimiento.
• Reducir max_tokens y el esfuerzo de razonamiento al lanzar muchos agentes.
• Planificar reintentos con backoff ante los 429.
• Alternar modelos: Opus para lo que exige potencia (arquitectura, debug), Sonnet/Haiku para tareas repetitivas delegadas. Esto distribuye la carga y respeta el rendimiento.

La regla económica de Pierre, contraintuitiva pero estructurante: las llamadas a Claude son el recurso barato; solo los servicios externos de pago cuentan de verdad. Por eso no se duda en multiplicar las lecturas y los agentes de Claude para ganar calidad; lo que se vigila principalmente es el rendimiento y los costos externos.

Auditar su presupuesto de contexto

Cada conversación con Claude se ejecuta dentro de una ventana de contexto (el número total de tokens, aproximadamente fragmentos de palabras, que caben en una sesión). Claude Code muestra el uso en tiempo real en su barra de estado. Cuando la ventana se llena, el contenido más antiguo se descarta o el modelo comienza a degradarse. Saber qué consume su presupuesto le permite recortar las cosas correctas.

Los mayores consumidores suelen ser: lecturas de archivos grandes, historiales de conversación largos, system prompts detallados y salidas de herramientas que vuelcan respuestas JSON completas. Use /status dentro de una sesión de Claude Code para ver el uso actual de tokens. La opción --verbose en cualquier comando claude imprime los recuentos de tokens por turno.

Las principales palancas para reducir el consumo son:

• Compactar la conversación: ejecute /compact en Claude Code para resumir el historial en su lugar y recuperar tokens.
• Limitar las lecturas de archivos: pase solo las líneas relevantes en lugar de archivos completos. Use los parámetros offset y limit al leer.
• Reducir la salida de herramientas: si una búsqueda devuelve cientos de coincidencias, filtre antes de enviar los resultados al modelo.
• Borrar y reiniciar: ejecute /clear para borrar la conversación por completo cuando comience una nueva tarea desde cero.

En el lado de la API (cuando llama a Claude de forma programática), el prompt caching le permite marcar un bloque estable de contexto con un punto de ruptura de caché. Anthropic almacena ese bloque en el servidor para que pague solo el 10 por ciento del costo de entrada normal en los accesos al caché. Esto es más importante para los system prompts grandes o los documentos de referencia que envía en cada llamada.

/compact y /clear

Cada mensaje que envías y cada respuesta de Claude consumen parte de la ventana de contexto (la cantidad máxima de texto que Claude puede retener en memoria a la vez). En una sesión de código larga, esa ventana se llena rápidamente. Claude Code te ofrece dos comandos para gestionarla: /compact y /clear.

/compact resume la conversación actual en un breve extracto y reemplaza el historial completo con ese resumen. Claude conserva una memoria de trabajo con lo que se decidió, qué archivos se modificaron y cuál es el objetivo, pero el intercambio bruto desaparece. Usa /compact cuando quieras continuar la misma tarea sin perder el hilo.

/clear borra toda la conversación sin ningún resumen. Claude empieza completamente de cero, como si acabaras de abrir una nueva sesión. Usa /clear cuando estés cambiando a una tarea sin relación, cuando el contexto actual se haya desviado y esté confundiendo a Claude, o cuando simplemente quieras empezar desde cero.

• /compact: conserva el objetivo, descarta la verbosidad. Ideal para sesiones largas de refactorización.
• /clear: reinicio completo. Ideal entre funcionalidades o proyectos separados.
• Ninguno de los dos comandos elimina tus archivos. Solo afectan a lo que Claude recuerda en esta sesión.
• Después de /compact, Claude puede pedirte que confirmes que el resumen es correcto antes de continuar.

El cache de prompt y el KV cache

Cada vez que envías un mensaje a Claude, el modelo procesa toda tu entrada desde cero, token por token. Eso es rápido para prompts cortos, pero costoso y lento cuando repites el mismo contexto grande (un prompt de sistema, un documento extenso, una gran base de código) en muchas llamadas. El cache de prompt resuelve esto almacenando la representación procesada del contenido repetido para que no tenga que ser recalculada.

El mecanismo subyacente es el KV cache (cache de clave-valor). Durante la inferencia (el acto de generar una respuesta), el modelo construye una tabla de valores intermedios para cada token de entrada. Normalmente esa tabla se descarta después de cada llamada. Con el cache de prompt activado, Anthropic mantiene la tabla activa en sus servidores durante una ventana corta, de modo que la siguiente llamada que envíe el mismo prefijo puede omitir el recálculo por completo.

Datos clave sobre el comportamiento del cache:

• La ventana de cache es de 5 minutos. Si tu próxima llamada a la API llega dentro de 5 minutos y comienza con el mismo prefijo, pagas el precio de lectura del cache, más bajo (aproximadamente el 10 por ciento del precio de entrada normal para Opus claude-opus-4-8 y Sonnet claude-sonnet-4-6).
• La primera llamada que llena el cache paga el precio de entrada normal más un pequeño recargo por escritura del cache (aproximadamente un 25 por ciento extra), porque el servidor debe almacenar el resultado.
• El prefijo en cache debe ser idéntico byte a byte. Incluso un carácter cambiado invalida el cache para esa posición y todo lo que sigue.
• Marcas los bloques almacenables explícitamente en la API usando un campo cache_control con "type": "ephemeral". Claude Code y los SDK de Claude gestionan esto automáticamente para los prompts de sistema cuando usas la opción --cache o el comportamiento por defecto del SDK.

El efecto práctico: la latencia disminuye porque el modelo omite procesar miles de tokens, y el costo baja porque los tokens en cache se facturan a la tarifa de lectura. Para un flujo de trabajo que envía el mismo documento de 20,000 tokens a Claude 50 veces en una sesión, el cache puede reducir el costo de entrada en más del 80 por ciento.

La Batch API para trabajo en volumen

La Batch API es el sistema de Anthropic para enviar cientos (o miles) de solicitudes a la vez en lugar de hacerlo una por una. Cada grupo de solicitudes se denomina batch. Los resultados se devuelven de forma asíncrona: usted envía el trabajo, se ocupa de otras cosas y recupera los resultados cuando están listos (generalmente en unos pocos minutos para un centenar de solicitudes).

Las dos razones principales para usar la Batch API son el costo y el rendimiento. Obtiene un descuento del 50 por ciento en todos los costos de tokens en comparación con la API estándar (síncrona). También dispone de un límite de velocidad independiente, por lo que el trabajo en batch no compite con sus llamadas en tiempo real por el cupo disponible.

Casos de uso típicos donde la Batch API resulta ventajosa:

• Generar un gran conjunto de datos sintético (por ejemplo, miles de pares pregunta-respuesta para ajustar un modelo)
• Aplicar el mismo prompt a cada fila de una hoja de cálculo o base de datos
• Traducción, clasificación o resumen masivo de un archivo de documentos
• Evaluaciones nocturnas que califican las salidas del modelo frente a un conjunto de pruebas

Dado que las solicitudes se procesan en segundo plano, la Batch API no es adecuada para tareas que requieren una respuesta inmediata. Para el chat interactivo o la asistencia de código en tiempo real, utilice la API estándar o Claude Code directamente. Pero para el trabajo que de todas formas programaría para la noche, el ahorro es automático.

Enrutar el trabajo hacia el modelo más económico

Cada llamada a la API de Claude tiene un costo y consume tiempo. Los tres modelos disponibles tienen precios muy distintos: Haiku (claude-haiku-4-5) es el más rápido y económico, Sonnet (claude-sonnet-4-6) ocupa un lugar intermedio, y Opus (claude-opus-4-8) es el más capaz y el más costoso. Elegir el modelo adecuado para cada tarea, lo que se conoce como enrutamiento de modelos, es uno de los controles de costo más eficaces que tienes.

La regla general es sencilla: adapta el modelo a la carga cognitiva de la tarea. Reserva Opus para trabajos que realmente requieran razonamiento profundo, como decisiones de arquitectura, depuración compleja o evaluación de compromisos sutiles. Todo lo demás debería ir primero a Sonnet o Haiku.

Tareas que son buenas candidatas para Sonnet o Haiku:

• Traducir texto o reformatear datos en volumen
• Resumir documentos extensos cuando la precisión no es crítica
• Clasificar o etiquetar elementos en un conjunto de datos
• Generar código repetitivo a partir de una plantilla clara
• Responder preguntas de tipo FAQ con un conjunto fijo de respuestas
• Funcionar como sub-agente dentro de un pipeline más grande (enrutamiento, extracción, filtrado)

En Claude Code, puedes cambiar el modelo activo en cualquier momento con /model. En las llamadas a la API, define el parámetro model por solicitud, de modo que distintos pasos de tu flujo de trabajo puedan llamar a modelos diferentes sin infraestructura adicional.

Contar tokens antes de gastar

Cada llamada a la API tiene un costo determinado por la cantidad de tokens (aproximadamente cuatro caracteres por token en inglés) que se procesan. Antes de ejecutar un batch costoso o un largo bucle agentivo, la API de Anthropic expone un endpoint dedicado al conteo de tokens que le indica exactamente cuántos tokens de entrada consumiría su solicitud, sin generar una respuesta y sin cobrarle.

El endpoint es POST /v1/messages/count_tokens. Usted le envía la misma carga que enviaría a /v1/messages (id del modelo, prompt del sistema, arreglo de mensajes, herramientas), pero la API devuelve un único objeto JSON que contiene input_tokens. Los tokens de salida no se pueden contar de antemano porque dependen de lo que el modelo genere, pero puede limitarlos con el parámetro max_tokens para fijar un techo absoluto de costo.

Para estimar el costo total, combine las dos cifras:

• Costo de entrada: tokens contados multiplicados por el precio de entrada del modelo por millón de tokens.
• Costo de salida: sus tokens de salida esperados (o máximos) multiplicados por el precio de salida por millón de tokens.
• Ahorro por caché: si activa el prompt caching (el campo cache_control), los tokens del prompt del sistema que se repiten se almacenan y se leen de nuevo a aproximadamente el 10 % del precio de entrada normal, reduciendo los costos en flujos de trabajo de larga duración.
• Descuento batch: el Batch API (/v1/messages/batches) ofrece un descuento del 50 % en entrada y salida para cargas de trabajo asíncronas.

En Claude Code (el agente CLI de codificación) puede ver cifras de tokens y costo en tiempo real en la línea de estado después de cada turno. El flag --max-turns limita los bucles agentivos y actúa como regulador de costo. Para verificaciones puntuales fuera de un bucle, pase su prompt por el método client.messages.countTokens() del SDK antes de comprometerse con la llamada completa.

Límites de velocidad y cómo sobrevivir un error 429

Un límite de velocidad es un techo que la API impone sobre cuánto puede enviar o recibir en una ventana de tiempo determinada. Cuando lo alcanza, el servidor devuelve el estado HTTP 429 Too Many Requests. En Claude Code esto se manifiesta como un mensaje de error que pausa la tarea actual hasta que la ventana se reinicia.

Anthropic aplica varios límites independientes a la vez: tokens de salida por minuto, solicitudes por minuto y, en ocasiones, una ventana deslizante más larga (5 horas o 7 días). Superar cualquiera de ellos activa un error 429. Las dos causas más frecuentes son: enviar muchas solicitudes rápidas en un bucle automatizado, y utilizar un valor alto de max_tokens o un esfuerzo de razonamiento extendido que obliga al modelo a generar respuestas muy largas.

La estrategia de recuperación estándar es el backoff exponencial con reintentos: esperar un intervalo breve (por ejemplo, 2 segundos), reintentar una vez, esperar el doble si vuelve a fallar, y así sucesivamente. La mayoría de los SDK oficiales de Anthropic hacen esto automáticamente con valores predeterminados razonables. En Claude Code, la interfaz de línea de comandos gestiona los reintentos internamente; no es necesario codificarlos usted mismo.

Cuando el backoff por sí solo no es suficiente, reduzca directamente la presión sobre el límite:

• Reducir max_tokens: cuanto menor sea el techo que establezca, menos tokens podrá emitir el modelo por llamada, lo que reduce el consumo por minuto.
• Reducir el esfuerzo de razonamiento (el parámetro budget_tokens para el razonamiento extendido): un presupuesto menor implica menos tokens de razonamiento interno contabilizados contra su límite.
• Distribuir el trabajo en el Batch API: las solicitudes por lotes se ejecutan en una cuota separada y más alta, y cuestan un 50 por ciento menos.
• Cambiar a un modelo más ligero: claude-haiku-4-5 es más rápido y más económico por token que claude-opus-4-8, por lo que el mismo rendimiento consume muchas menos unidades de límite de velocidad.

Enmascaramiento de observaciones

Cada llamada a una herramienta que realiza Claude (leer un archivo, ejecutar un comando de shell, obtener una URL) vuelca su salida completa en la ventana de contexto (el buffer deslizante de texto que el modelo puede ver en un momento dado). Si esa salida es grande o está desactualizada, desperdicia tokens y puede confundir al modelo al presentar datos obsoletos junto a información reciente. El enmascaramiento de observaciones es la práctica de ocultar o recortar esa salida de herramienta para que ya no ocupe espacio en la ventana.

Claude Code expone esto mediante el flag --hide-tool-output y mediante la configuración a nivel de proyecto. Cuando el resultado de una herramienta está enmascarado, el modelo sigue sabiendo que la herramienta fue llamada y si tuvo éxito, pero el texto bruto se elimina de la ventana activa. Esto mantiene la ventana liviana en sesiones largas.

Situaciones comunes en las que el enmascaramiento ayuda:

• Un grep o find que devolvió cientos de líneas sobre las que ya actuaste.
• Una ejecución de pruebas cuyo stack trace completo ya no es relevante tras aplicar la corrección.
• Lecturas repetidas del mismo archivo grande a lo largo de muchas iteraciones.
• Registros de instalación de dependencias que son ruido una vez que la instalación terminó con éxito.

La contrapartida es una reducción del anclaje (el hecho de que el modelo disponga de evidencia concreta para razonar). Enmascara solo las salidas de las que estás seguro de que ya no se necesitan. Si enmascaras de forma demasiado agresiva, el modelo puede repetir trabajo o hacer suposiciones que no debería.