optimizar sesiones de Claude Code lentas

Cómo evitar que una sesión larga de Claude Code se vuelva lenta y costosa

Una sesión larga de Claude Code se vuelve lenta y costosa porque cada turno reenvía todo el contexto, y ese contexto solo crece. La solución es mantener la higiene en un orden específico. Ejecute /context para ver qué contenido llena la ventana, elimine los elementos por los que paga en cada solicitud, luego use /clear entre tareas no relacionadas y /compact con una instrucción dentro de una tarea larga. Trabaje en periodos continuos, ya que un prompt cache frío convierte una lectura económica en una reescritura completa de todo lo que ha dicho.

La razón por la que el contador aumenta se explica en el medidor de tokens detrás de una sesión de agente.

Lea /context antes de realizar cualquier cambio

No intente adivinar el contenido de la ventana. Claude Code se lo indicará.

/context [all] muestra el uso actual del contexto como una cuadrícula de colores, con sugerencias de optimización para herramientas con mucho contexto y exceso de memoria; all expande el desglose por elementos en modo pantalla completa. Interprete el resultado como cinco categorías.

• El system prompt. Las instrucciones propias del entorno de Claude Code. Son fijas durante la sesión.
• Tool definitions. El esquema de cada herramienta que el agente puede llamar, incluyendo cada servidor MCP (Model Context Protocol) conectado.
• Memory files. CLAUDE.md y la memoria automática, cargadas al inicio de la sesión.
• Files and tool results. Cada archivo leído y todo lo que sus comandos imprimieron como respuesta.
• Message history. Sus mensajes y las respuestas del modelo.

Los tres primeros son un coste fijo que se aplica en cada solicitud durante toda la sesión. Los dos últimos crecen. Reduzca el coste fijo una vez, al inicio; gestione la parte creciente de forma continua.

Dos cadenas indican que la ventana está llena:

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

La primera es un límite estricto y la solicitud es rechazada; el error de la API (application programming interface) correspondiente es Prompt is too long. La segunda es una ventana de compactación, que puede situarse por debajo de la ventana de contexto real del modelo en un modelo de 1 millón de tokens. Las solicitudes siguen teniendo éxito después de este punto, por lo que esa es una advertencia en lugar de un rechazo.

En un plan de pago, /usage añade la otra mitad, señalando comportamientos como contextos largos o fallos de caché, y atribuyendo el uso reciente a habilidades individuales, subagentes y servidores MCP.

CLAUDE.md es un impuesto permanente, manténgalo ligero

Su CLAUDE.md se carga en el contexto al inicio de la sesión y permanece allí. Si contiene un procedimiento de despliegue detallado, esos tokens consumen recursos mientras corrige un error tipográfico en un archivo de prueba. La recomendación de Anthropic es incluir solo lo esencial y mantener el archivo con menos de 200 líneas.

Mueva los procedimientos a skills. Una skill solo se carga cuando se invoca; por lo tanto, un flujo de trabajo que ejecuta dos veces por semana no tiene coste los demás días. Las skills tienen su propio presupuesto tras una compactación: los cuerpos se reinyectan, con un límite de 5,000 tokens por skill y 25,000 en total, eliminando primero los más antiguos. La truncación conserva el inicio del archivo, así que coloque las instrucciones más importantes cerca de la parte superior de SKILL.md.

Lo que sobreviva a una compactación determina dónde debe ubicarse una instrucción.

• El system prompt y el estilo de salida no cambian, porque no forman parte del historial de mensajes.
• El CLAUDE.md de la raíz del proyecto, las reglas sin scope y la memoria automática se reinyectan desde el disco.
• Una regla con frontmatter paths: se pierde hasta que se vuelva a leer un archivo coincidente.
• Una CLAUDE.md anidada en un subdirectorio se pierde hasta que se vuelva a leer un archivo en ese subdirectorio.
• Los hooks no se ven afectados, porque un hook se ejecuta como código y nunca entra en el contexto.

Por tanto, una regla de la que dependa debe estar en el CLAUDE.md de la raíz del proyecto: Claude Code limpia primero los outputs de herramientas más antiguos y luego resume, por lo que las instrucciones de las primeras partes de la conversación pueden perderse. Edite la memoria con /memory. Claude Code mantiene la copia que cargó al inicio de la sesión, por lo que un recorte a mitad de sesión mantiene el prompt cache y no se aplica hasta el próximo /clear, /compact, o reinicio.

/clear entre tareas, /compact dentro de una misma

Estos dos comandos parecen intercambiables pero tienen costos muy distintos.

/clear [name] inicia una nueva conversación con el contexto vacío. No envía ninguna solicitud, por lo que no tiene costo. Proporcione un nombre para etiquetar la conversación anterior en el selector /resume; /reset y /new son alias. Utilícelo en cuanto cambie a una tarea no relacionada, ya que de lo contrario la tarea anterior se enviaría y se volvería a facturar en cada mensaje de la nueva.

/compact [instructions] libera contexto manteniendo la misma conversación: resume el historial actual y lo reemplaza. Utilícelo dentro de una tarea larga donde aún necesite continuidad.

Siempre proporcione una instrucción a /compact. Un comando /compact sin instrucciones utiliza un prompt por defecto que no sabe qué parte del trabajo aún necesita. Un comando con instrucciones lo mantiene:

/compact focus on the auth bug fix
/compact keep only the plan and the diff

Si realiza la compactación siempre por la misma razón, coloque una instrucción fija en el CLAUDE.md de su proyecto bajo un encabezado # Compact instructions. En una sesión nueva, /compact imprime Not enough messages to compact., lo que significa que aún no hay historial.

Aquí se confunden dos costos. La solicitud de resumen comparte su prefijo, por lo que lee el cache existente en lugar de reprocesar el historial, y la mayor parte del tiempo se dedica a generar el resumen. Compactar un contexto grande sigue siendo una solicitud grande, porque la conversación que se resume es la entrada. El turno después de la compactación no es la parte lenta: reconstruye el cache para un prompt mucho más corto.

Existen dos comandos más económicos. /rewind [description] revierte el código y la conversación a un checkpoint; para una ruta que desea abandonar por completo, es mejor que compactar, porque trunca el historial hasta un prefijo que ya está en cache. /recap añade un resumen como salida del comando en lugar de reemplazar el historial, por lo que el prefijo en cache permanece intacto.

La ejecución automática de la compactación repetida imprime esto:

Autocompact is thrashing: the context refilled to the limit...

La compactación tuvo éxito, pero la salida de un archivo o herramienta llenó la ventana varias veces seguidas, por lo que Claude Code dejó de reintentar. Recupere el control leyendo el archivo de gran tamaño en rangos de líneas, ejecutando /compact con un enfoque que descarte la salida grande, moviendo ese trabajo a un subagent, o /clear si la conversación anterior ha finalizado.

Los servidores MCP tienen un overhead fijo

Cada servidor MCP conectado aumenta el costo de cada solicitud durante toda la sesión. El consumo se aplica independientemente de si se utiliza la herramienta o no.

Claude Code mitiga este efecto. Las definiciones de las herramientas MCP se posponen por defecto; solo los nombres de las herramientas entran en el contexto hasta que Claude utiliza una herramienta específica. Ejecute /context para ver el costo real de sus servidores, y /mcp disable <name> para eliminar uno que no utilizará hoy. Si ejecuta sus propios servidores MCP en un VPS, la misma lógica limita la cantidad de herramientas que un servidor debe exponer.

Realice esto al inicio de una sesión. Aunque las definiciones se mantengan pospuestas, conectar o desconectar un servidor solo añade información a la conversación y el cache se mantiene. En cambio, si las definiciones se cargan en el prefix (porque la búsqueda de herramientas está desactivada o un servidor está exento de la postergación), el mismo cambio hará que la siguiente solicitud vuelva a leer todo el contenido.

Filtre la salida detallada de las herramientas antes de que entre en el contexto

El resultado de una herramienta es una entrada, y la entrada se vuelve a enviar en cada turno posterior. Una ejecución de prueba que genera 20,000 tokens de salida no es un coste de una sola vez: se paga de nuevo en cada turno hasta que sale de la ventana.

Filtre en el origen. Un hook que reduzca una ejecución de prueba solo a sus fallos antes de que Claude lo vea convierte ese bloque de salida en unos pocos cientos de tokens, tanto en este turno como en cada reenvío:

npm test 2>&1 | grep -E "FAIL|Error:" | head -40

Los hooks nunca entran en el contexto porque se ejecutan como código. Haga esto para cualquier herramienta cuya salida exceda el tamaño de la pantalla. La misma lógica se aplica a un archivo de 3,000 líneas: solicite solo el rango de líneas necesario, ya que el archivo completo permanece en la ventana una vez que llega.

Defina el alcance de la lectura del agente y delegue las tareas ruidosas

Un prompt que especifica un archivo leerá ese archivo. Una solicitud abierta para organizar el proyecto leerá lo que el agente considere relevante, y cada una de esas lecturas permanecerá en la ventana de contexto.

Delegue el trabajo verboso a un subagente. La ejecución de pruebas y el procesamiento de logs consumen contexto real; un subagente mantiene esa salida en su propia ventana y solo devuelve un resumen. El compromiso es el siguiente: un subagente genera su propio cache sin aciertos en la primera llamada y utiliza un tiempo de vida de cache de cinco minutos incluso en suscripciones. La delegación protege de forma fiable su contexto principal. No siempre reduce el total de tokens.

El reloj de caché: trabaje en periodos

El almacenamiento en caché de prompts hace que el reenvío sea económico: 0.1x la tasa de entrada base para leer el prefijo, frente a 1.25x para escribirlo, o 2x para escribirlo con una vida útil de una hora. Cada uso refresca la entrada sin coste adicional, por lo que el reloj se reinicia desde el último uso.

El tiempo de vida depende de su método de autenticación; por eso la afirmación general "su caché expira tras cinco minutos" es incorrecta.

• Con una suscripción de Claude, Claude Code solicita automáticamente la vida útil de una hora.
• Una vez superado el límite de su plan y utilizando créditos de uso, se le factura por dicho uso, por lo que el tiempo baja a cinco minutos.
• Con una API key o un proveedor de la nube, el tiempo se mantiene en cinco minutos. ENABLE_PROMPT_CACHING_1H=1 permite la vida útil de una hora, y FORCE_PROMPT_CACHING_5M=1 la reduce de nuevo.

El consejo sobre el ritmo es el mismo en ambos casos: trabaje en periodos continuos, ya que un intervalo de inactividad superior al tiempo de vida obliga a reescribir todo el prefijo acumulado en la siguiente ejecución. Una sesión de Claude Code desvinculada en tmux no tiene coste mientras esté inactiva, pero el tiempo de inactividad consume la caché activa.

Algunas acciones eliminan la caché mientras aún trabaja: cambiar de modelo, cambiar el nivel de esfuerzo, activar el modo rápido, conectar o desconectar un servidor MCP, habilitar o deshabilitar un plugin, denegar una herramienta completa, compactar y actualizar Claude Code. /model es la sorpresa habitual, ya que cada modelo tiene su propia caché; por tanto, la siguiente solicitud leerá todo el historial sin aciertos de caché aunque el contenido sea idéntico.

Editar archivos, editar CLAUDE.md, invocar habilidades y comandos, ejecutar /recap, retroceder y generar un subagente mantienen la caché. Esta se limita a una máquina y un directorio; por tanto, dos sesiones en directorios distintos no comparten caché.

Para verificar si la caché funciona, lea current_usage. cache_creation_input_tokens se escribió a la tasa de escritura de caché; cache_read_input_tokens se sirvió a aproximadamente una décima parte de la tasa de entrada estándar. Una relación alta entre lectura y creación es señal de un funcionamiento correcto. Si la creación se mantiene alta en cada turno, algo en su prefijo cambia constantemente.

¿Un contexto más amplio soluciona esto?

Parcialmente. Varios modelos actuales admiten una ventana de contexto de 1 millón de tokens, y la compactación funciona igual con límites mayores. La economía no cambia, porque el prompt completo se reenvía y se factura en cada turno. Una ventana más grande determina cuándo es obligatorio actuar; la higiene determina el costo. Si el problema es la factura y no el límite, qué plan de Claude se adapta a tu forma de trabajar determina si gastas dólares o el cupo del plan.

La edición de contexto y la compactación en la API son funciones distintas

Si está creando su propio agente con la Messages API, no existen los slash commands y debe implementarlos usted mismo. Dos funciones del lado del servidor cumplen esta tarea, y no son la misma función.

La edición de contexto elimina selectivamente contenido específico del historial de la conversación a medida que este crece. Reemplaza cada resultado eliminado con un texto de marcador de posición para que Claude sepa que algo fue borrado. Es una versión beta: envíe anthropic-beta: context-management-2025-06-27 y configure las estrategias bajo context_management.edits. clear_tool_uses_20250919 elimina los resultados de las herramientas, y clear_thinking_20251015 gestiona los bloques de pensamiento (thinking blocks). Su trigger tiene por defecto 100,000 tokens de entrada, keep los últimos 3 usos de herramientas, y clear_tool_inputs es false, de modo que las entradas se mantienen y solo se eliminan los resultados.

La compactación genera un resumen y reemplaza el historial completo de la conversación con este. También es una versión beta: envíe anthropic-beta: compact-2026-01-12 y use el tipo de edición compact_20260112. El disparador (trigger) tiene por defecto {"type": "input_tokens", "value": 150000} y el valor debe ser al menos 50,000.

La compactación tiene una regla de transferencia que rompe agentes de forma silenciosa. La respuesta comienza con un bloque de contenido compaction que contiene el resumen, seguido del bloque de texto normal. Debe reenviar ese bloque en solicitudes posteriores; la API eliminará entonces todos los bloques de contenido anteriores a este. En la práctica: adjunte el contenido completo de response.content, no solo el texto.

La documentación de Anthropic define la compactación del lado del servidor como la estrategia principal para gestionar el contexto en conversaciones largas, y la edición de contexto como la opción para un control más preciso sobre qué se elimina. Verifique primero la compatibilidad del modelo. Los modelos actuales Opus, Sonnet y Fable admiten la compactación; claude-haiku-4-5 no la admite, y la página de compactación contiene la lista actualizada. Ninguna de las dos betas controla el /compact de Claude Code, el cual su documentación describe como una solicitud de resumen única enviada por el cliente.

FAQ

¿Por qué mi sesión de Claude Code se vuelve más lenta y costosa cuanto más tiempo dura?

La sesión se vuelve lenta y costosa porque se envía toda la conversación en cada turno. Una pregunta de una sola línea en una sesión abierta durante todo el día incluye todo el historial previo. El prompt caching mantiene el costo bajo mientras el cache esté activo, al 0.1x de la tarifa base de entrada por lectura; si un turno no encuentra el cache, el mismo prefijo se reescribe al 1.25x. Ejecute /context para ver qué contenido llena la ventana, y lea qué se le factura en una sesión de Claude Code para entender el mecanismo.

¿Cuál es la diferencia entre /clear y /compact en Claude Code?

/clear inicia una nueva conversación con el contexto vacío. No envía ninguna solicitud, por lo que no tiene costo; es la opción correcta para tareas no relacionadas. /compact mantiene la misma conversación y reemplaza el historial con un resumen; es la opción correcta para una única tarea larga. Proporcione un enfoque, como en /compact keep only the plan and the diff, ya que la instrucción determina qué contenido se conserva.

¿Cómo puedo ver qué está consumiendo mi ventana de contexto de Claude Code?

Ejecute /context, o /context all para obtener un desglose detallado por elemento. Muestra el system prompt, las definiciones de herramientas, los servidores MCP, los archivos de memoria y el historial en una cuadrícula de colores, con sugerencias para herramientas con exceso de contexto y saturación de memoria. En un plan de pago, /usage también atribuye el uso reciente a habilidades individuales, subagentes y servidores MCP.

¿Debería usar una ventana de contexto de 1 millón de tokens en lugar de compactar?

Una ventana más grande solo retrasa el problema en lugar de resolverlo. Varios modelos actuales admiten una ventana de contexto de 1 millón de tokens, incluyendo Opus 4.8 y Sonnet 5, y la compactación funciona de la misma manera en ellos. Cada turno sigue reenviando el prompt completo y sigue generando costos, por lo que una conversación de 400,000 tokens es costosa independientemente de si cabe en la ventana o no.

¿Cuál es la diferencia entre la edición de contexto y la compactación en la API de Claude?

La edición de contexto elimina selectivamente contenido antiguo, principalmente resultados de herramientas, dejando un texto de marcador de posición donde estaba cada uno para que Claude sepa que fue eliminado. La compactación genera un resumen y reemplaza el historial completo con este. La documentación de Anthropic define la compactación como la estrategia principal para conversaciones largas y posiciona la edición de contexto como la opción de ajuste fino. Ambas son versiones beta con sus propios encabezados, y ambas son independientes de /compact de Claude Code.