Claude Code Avanzado: Optimización de Tokens y Dominio del Contexto en Bases de Código Grandes (2026)

- Los comandos y las cifras de este artículo vienen de la documentación oficial de Anthropic (consultada el 2026-08-20). Claude Code se actualiza con mucha frecuencia, así que revisa claude --version y vuelve a ejecutar /usage en tu propia máquina para comparar.

¿Por qué Claude Code quema tokens en una base de código grande?

A muchos devs les frustra que "una preguntita y mi consumo sube todo el día". La causa no es esa pregunta, sino cómo funcionan los modelos de lenguaje: cada petición reenvía la conversación entera (system prompt, CLAUDE.md, historial, archivos leídos, resultados de herramientas) como entrada. Cuanto más larga es la sesión, más cuesta cada intercambio, porque ese contexto que se arrastra detrás no para de crecer.

Tres mecanismos se combinan para disparar el costo:

• Acumulación de contexto largo: cuantos más archivos metes al contexto, más pesado se vuelve cada turno posterior, aunque nunca vuelvas a tocar esos archivos.
• Deterioro del contexto (context rot): según el artículo de Anthropic Effective context engineering for AI agents (2025-09-29), a medida que crece el número de tokens en la ventana, la capacidad del modelo para recordar información importante en realidad baja. Es decir, un contexto inflado no solo es más caro, también hace a Claude menos preciso.
• Fallos de caché (cache misses): Claude Code cachea el inicio del prompt para que no te cobren por él de nuevo. Pero la caché caduca; si te alejas demasiado tiempo y vuelves, todo el bloque de contexto se cobra a precio completo otra vez.

Sobre el costo base, la documentación "Manage costs effectively" de Anthropic (docs, consultada 08/2026) reporta un promedio de aproximadamente ~US$ 13/dev por día activo, con la mayoría del uso rondando US$ 150-250/mes, y el 90% de los usuarios por debajo de ~US$ 30/día. Si vas muy por encima de eso en una base grande, casi seguro hay gasto de tokens desperdiciado en unos pocos puntos predecibles. Para entender los planes y cómo funciona la facturación, mira nuestra guía de precios y planes de Claude Code. Y si apenas estás empezando, lee primero qué es Claude Code para tener los fundamentos.

Mide primero, optimiza después - /context, /usage, statusline

No optimices a ciegas. Antes de tocar cualquier técnica, toma una foto del estado actual para saber a dónde se van tus tokens. Estos dos comandos son el punto de partida:

/usage # token & cost overview: input, output, cache read/write, cost
/context # breaks down what is taking up your CURRENT context right now

/usage te da el retrato del dinero: cuántos tokens de entrada, de salida, cuánto se leyó de la caché (barato) frente a lo que se escribió en una caché nueva (caro). Una proporción alta de lectura de caché es buena señal. /context es el más valioso de los dos cuando estás optimizando: separa el system prompt, el CLAUDE.md, las herramientas de MCP que declaraste y los archivos que metiste, mostrándote exactamente qué está acaparando espacio.

/usage tiene un formato de salida específico que vale la pena conocer, por ejemplo el bloque Session:

Total cost:            $0.55
Usage by model:
   claude-sonnet-4-6:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)

En los planes Pro/Max/Team/Enterprise, /usage también muestra un Plan usage breakdown: la Attribution asigna el uso reciente a skills, subagents, plugins y servidores MCP individuales, cada uno como un porcentaje del total; los Behavior flags avisan cuando el contexto largo o los cache misses representan el 10% o más del uso reciente. Pulsa d/w para alternar entre la vista de 24 horas y la de 7 días.

Para conocer cómo trabajas (no solo cuánto gastaste), ejecuta /insights: analiza hasta tus 200 sesiones más recientes en esta máquina y escribe un informe HTML en ~/.claude/usage-data/report.html que cubre puntos de fricción y sugerencias para usar Claude Code de forma más eficaz. Complementa a /usage, no lo reemplaza.

También deberías habilitar una lectura de contexto en tu statusline para vigilarla de forma continua sin escribir un comando; los detalles están en nuestra guía de cómo personalizar la statusline de Claude Code. La regla: solo las cifras de antes/después te dicen qué técnica valió de verdad el esfuerzo. Ejecuta /context justo antes y justo después de cada cambio de abajo para medir el delta real.

Grupo 1 - Gestión proactiva del contexto (/clear, /compact, resume)

Esta es la palanca más barata y de mayor impacto que existe. La mayoría de los tokens desperdiciados vienen de arrastrar contexto viejo y sin relación a una tarea nueva.

/clear entre tareas sin relación. ¿Acabas de arreglar un bug en el módulo de autenticación y ahora vas a escribir pruebas para el módulo de pagos? Escribe /clear. Reinicia el contexto al inicio: el costo de la "cola de la conversación" vuelve a cerca de US$ 0 para la nueva tarea. Este es el hábito de ahorro de tokens más importante y que la mayoría de la gente se salta.

/compact cuando necesitas mantener el hilo. Cuando quieres seguir con la misma línea de trabajo pero el contexto se ha inflado, /compact comprime la conversación en un resumen. Importante: usa un compact dirigido para no perder exactamente lo que necesitas:

/compact Keep the database schema decisions and the files changed in the payment module; drop the long debug logs

Puedes predefinir "Compact instructions" en CLAUDE.md para que cada compact mantenga las mismas prioridades. Claude Code también tiene auto-compact: cuando el contexto se acerca al límite, compacta por su cuenta para que la sesión no se rompa. Cómodo, pero una advertencia honesta: el auto-compact puede descartar detalles, así que para tareas delicadas ejecuta un compact manual dirigido en vez de dejarlo al azar.

Retoma desde el resumen. Al reabrir una sesión grande, elige retomar desde el resumen en lugar de recargar el historial completo: empiezas con unos pocos miles de tokens en vez de decenas de miles. Para profundizar en este mecanismo, lee nuestra guía de gestionar el contexto y la memoria en Claude Code.

Grupo 2 - Elige el modelo correcto & ajusta el extended thinking

No toda tarea necesita el modelo más potente. Así se reparte por costo (precios de referencia de la API: Opus 5 US$ 5/US$ 25 por 1M de tokens entrada/salida; Sonnet 5 US$ 2/US$ 10; Haiku 4.5 US$ 1/US$ 5):

• Sonnet para la mayor parte de la programación. Sonnet 5 se encarga de la inmensa mayoría de escribir y editar código por una fracción del costo de Opus.
• Reserva Opus para arquitectura & problemas difíciles. Cambia con /model a mitad de sesión cuando topes con algo que exige razonamiento profundo, y luego vuelve a Sonnet.
• Haiku para subagents simples. Para un subagent que hace trabajo puramente mecánico (grep, resumir, formatear), define model: haiku en su definición.

El extended thinking es un arma de doble filo para los tokens. El "pensamiento" se cobra como tokens de salida, y la salida cuesta varias veces más que la entrada. En tareas simples y repetitivas, pensar mucho es solo quemar dinero. Cómo controlarlo:

/effort # tune the reasoning effort to fit the task
MAX_THINKING_TOKENS=8000 # cap thinking tokens (environment variable)

También puedes desactivar el extended thinking en /config. Una salvedad honesta: apagar el pensamiento perjudica las tareas de razonamiento profundo (diseño de algoritmos, depuración multicapa); esto es un compromiso, no una regla de "siempre apagado para ahorrar". Solo bájalo o apágalo cuando la tarea de verdad no necesite mucho razonamiento.

Grupo 3 - Recorta la sobrecarga de MCP & de herramientas

Corrección: Claude Code ahora difiere las definiciones de herramientas MCP por defecto: al principio solo los nombres de las herramientas están en el contexto, y la descripción completa más el schema de parámetros se cargan únicamente cuando Claude usa de verdad esa herramienta. Así que el verdadero "impuesto" de contexto son dos cosas: (a) versiones antiguas de Claude Code o sesiones con la búsqueda de herramientas desactivada aún cargan todo de entrada; y (b) un servidor con un número muy grande de herramientas igual suma solo por los nombres, más un costo único la primera vez que se llama a una herramienta. Usa /context para inspeccionar esto.

• Desactiva los servidores que no uses: /mcp para ver y gestionar los servidores conectados; apaga lo que no necesites en la sesión actual.
• Prefiere las CLI a MCP cuando puedas. Para tareas que ya tienen una herramienta de línea de comandos - gh (GitHub), aws, gcloud - deja que Claude llame a la CLI directamente por Bash en vez de montar un servidor MCP equivalente. Una CLI no lleva el costo permanente de "listado de herramientas" en el contexto.
• Inteligencia de código para lenguajes tipados. Para TypeScript/Java/Go, un plugin de "go to definition" deja que Claude salte directo a una definición en vez de hacer grep y leer una pila de archivos, recortando de forma notable los tokens de lectura de archivos en una base grande.

Para entender MCP y cuándo usarlo o no, mira el texto sobre hooks en Claude Code del próximo grupo: estos dos mecanismos a menudo trabajan juntos para reducir contexto.

Grupo 4 - Descarga el trabajo pesado en hooks & skills

Este es el grupo con la mayor recompensa que menos gente aprovecha. La idea: no dejes que la salida voluminosa fluya directo al contexto de Claude; fíltrala o resúmela primero, en la capa de script.

Un hook para filtrar la salida de las pruebas. Una corrida de una suite grande de pruebas puede imprimir decenas de miles de líneas, pero Claude solo necesita saber qué FALLÓ. Un hook de PreToolUse/posprocesamiento que conserva solo las líneas FAIL/ERROR puede bajar el conteo de tokens de decenas de miles a cientos (según la documentación "Manage costs effectively"). Ejemplo de esqueleto de un script de filtro:

#!/usr/bin/env bash
# filter-test-output.sh - keep only failing lines, cut the noisy log
npm test 2>&1 | grep -E "(FAIL|ERROR|✕|Error:|Expected|Received)" | head -n 100

Una skill de "codebase-overview". En vez de hacer que Claude lea 20 archivos para entender la estructura del proyecto cada vez, empaqueta una skill que describa la arquitectura, las convenciones y dónde viven los módulos principales. Una skill carga bajo demanda, así que no queda de forma permanente en el contexto; pero, cuando se necesita, da contexto al instante en lugar de un aluvión de lecturas de archivos.

Mantén el CLAUDE.md ligero. La documentación de Anthropic recomienda mantener CLAUDE.md por debajo de ~200 líneas. Todo lo de este archivo se carga en cada petición, así que llenarlo hasta el tope es un impuesto de tokens permanente. Mueve las instrucciones especializadas (un procedimiento de despliegue, las convenciones de un módulo) a una skill bajo demanda, y deja en CLAUDE.md solo lo que de verdad usas en cada sesión.

Grupo 5 - Subagents & recuperación just-in-time para bases de código grandes

En un monorepo, el enemigo número uno es dejar que un único contexto "escanee" todo el repositorio. La solución es aislar la lectura pesada lejos del contexto principal.

Delega la investigación a un subagent. Cuando necesitas averiguar "dónde está implementada la funcionalidad X", entrégaselo a un subagent. Lee un lote de archivos en su propio contexto y devuelve solo un resumen; según el artículo de ingeniería de Anthropic, normalmente apenas ~1.000-2.000 tokens en vez de volcar el contenido completo de los archivos en el contexto principal. Mira el recorrido detallado en nuestra guía de subagents en Claude Code.

Recuperación just-in-time con referencias @. No dejes que Claude adivine y ande haciendo grep a ciegas. Apúntalo directo a lo que necesita, cuando lo necesita:

@src/payment/checkout.ts # load exactly one file when needed
@src/payment/ # load exactly one directory

Plan mode para evitar retrabajo caro. Pulsa Shift+Tab para entrar en plan mode: Claude planea antes de editar. Revisar un plan es mucho más barato que dejarlo editar mal un lote de archivos y luego tener que rehacer el trabajo, y cada ciclo de rehacer cuesta tokens. Si va por el camino equivocado, usa /rewind (o pulsa Esc dos veces) para volver a un checkpoint anterior en vez de describir todo desde cero otra vez.

El principio que amarra todo este grupo, tomado prestado de Anthropic: apunta a los mínimos tokens de alta señal: mete lo menos posible en el contexto, pero exactamente las piezas más valiosas. Esta es también la cura para el deterioro del contexto que se mencionó al inicio del artículo.

Grupo 6 - Advisor: una segunda opinión sin correr el modelo fuerte todo el día

El advisor empareja tu modelo principal con un segundo, por lo general más potente; Claude decide cuándo consultarlo, normalmente antes de comprometerse con un enfoque, ante un error recurrente, o antes de declarar terminada una tarea, y no en cada turno. Esta es una técnica genuina de optimización de tokens: sale bastante más barato que correr el modelo fuerte toda la sesión.

Actívalo con /advisor opus (u otro modelo), define advisorModel en tus ajustes, o pasa --advisor para una sola sesión. Apágalo con /advisor off.

Mecánica de costo: cada llamada se cobra a la tarifa del modelo advisor, además del uso de tu modelo principal. En los planes de suscripción, el uso del advisor cuenta para los límites de tu plan como todo lo demás, salvo que un advisor Fable 5 se cobra de los créditos de uso en los planes donde eso aplica. Alternar el advisor a mitad de sesión no invalida la caché de prompt del modelo principal (solo la lectura que el propio advisor hace de la conversación queda sin cachear).

Salvedad honesta: esta es una función experimental, disponible solo a través de la API directa de Anthropic - no en Amazon Bedrock, la Agent Platform de Google Cloud ni Microsoft Foundry - y el comportamiento/precio puede cambiar.

Trampas de tokens: equipos de agentes, workflows dinámicos & sesiones de todo el día

Estas dos inflan tu consumo de maneras difíciles de notar.

Los equipos de agentes ~7x tokens, pero solo cuando los compañeros corren en plan mode. Correr un "equipo" de muchos agentes en paralelo suena poderoso, pero la documentación "Manage costs effectively" advierte que usa alrededor de ~7x los tokens de una sesión estándar cuando los compañeros corren en plan mode, porque cada compañero mantiene su propia ventana de contexto y corre como una instancia de Claude aparte. Cuándo no usarlo: tareas secuenciales, alcance pequeño, o cuando tu presupuesto de tokens está ajustado. Si tienes que hacerlo, corre a los compañeros en Sonnet y cierra el equipo en cuanto termines.

Los workflows dinámicos también pueden inflar el consumo si se dejan sin límite. Escribe la palabra clave ultracode en un prompt (o simplemente pide en lenguaje común "usar un workflow para esto") y Claude escribe y corre un workflow dinámico que orquesta muchos subagents, hasta 1.000 agentes por corrida, con hasta 16 corriendo a la vez. Sigue el progreso con /workflows. Un aviso de "Large workflow" aparece cuando una corrida programa más de 25 agentes o sus tokens proyectados pasan de 1,5 millones (el umbral de 25 agentes se reemplaza por la guía de tamaño que definas en /config; el valor por defecto es medium, por debajo de 15 agentes); es solo un aviso y no detiene la corrida. Con honestidad: no hay una cifra oficial en dólares para una corrida completa de workflow; prueba en una porción pequeña antes de correr todo. Mira la mecánica completa en workflows dinámicos en Claude Code.

Sesiones de todo el día. Dejar una sola sesión corriendo de la mañana a la noche es receta para quemar tokens: el contexto largo se infla, y la caché falla una y otra vez cada vez que te alejas. Sobre la caché, la documentación señala que la duración es de 1 hora en los planes de suscripción frente a 5 minutos con créditos de uso/API; puedes habilitar la caché de 1 hora con una variable de entorno:

ENABLE_PROMPT_CACHING_1H=1

Buenos hábitos: /clear al cambiar de trabajo, cerrar la sesión en pausas largas, retomar desde el resumen cuando vuelvas. (Una nota pequeña para tu tranquilidad: los tokens de fondo de las tareas automáticas de Claude Code son muy baratos; la documentación cita < US$ 0,04/sesión, así que no te preocupes por esa parte.)

Tabla resumen - técnica frente a ahorro de tokens

Ordenada por ROI de tokens (alto apalancamiento / bajo esfuerzo arriba). Donde la columna "ahorro" tiene una fuente de Anthropic, citamos la cifra verificada; las partes medidas en una base real quedan para que Jasmine las complete a partir de su sesión de prueba.

Acelera con un kit prearmado (AgentKit)

Muchas de las técnicas de arriba - la skill de "codebase-overview", subagents especializados, hooks de filtrado de salida - son eficaces pero cuestan trabajo real de construir y ajustar por tu cuenta. Si prefieres tener un conjunto listo de skills, subagents y hooks optimizados para contexto para Claude Code, el kit AgentKit para Claude Code empaqueta este instrumental para que no tengas que escribirlo desde cero.

Una nota para evitar confusiones: el AgentKit de aquí (agentkit.best, CLI ak) es un kit para Claude Code / Codex / Copilot - completamente distinto del AgentKit de OpenAI. Puedes echar un vistazo a AgentKit (20% de descuento por el enlace) y juzgar por ti misma; esta es una sugerencia opcional, no un requisito - toda técnica de este artículo se puede hacer a mano.

Preguntas frecuentes (FAQ)

¿Cuándo uso /compact frente a /clear?

Usa /clear cuando cambias a una tarea sin relación: reinicia el contexto y recorta el costo de la "cola de la conversación" a casi cero. Usa /compact cuando quieres seguir con la misma línea de trabajo pero el contexto se infló; comprime el historial en un resumen manteniendo tu hilo.

¿Claude Code compacta automáticamente?

Sí. Cuando el contexto se acerca al límite, Claude Code hace auto-compact para que la sesión no se rompa. Cómodo, pero puede descartar detalles, así que para tareas importantes ejecuta tú misma un /compact dirigido en vez de dejarlo al azar.

¿Usar Opus es mucho más caro?

Sí - según los precios de referencia de la API, Opus 5 (US$ 5/US$ 25 por 1M entrada/salida) es unas 2,5x más caro que Sonnet 5 (US$ 2/US$ 10). Deja que Sonnet se encargue de la mayor parte de la programación y solo cambia con /model a Opus para arquitectura o problemas difíciles.

¿Cómo veo los tokens que estoy usando?

Escribe /usage para ver el total de tokens de entrada/salida, lectura/escritura de caché y costo; escribe /context para ver qué componentes están ocupando tu contexto actual (CLAUDE.md, herramientas MCP, archivos leídos). Mide con estos dos antes y después de cada cambio.

En una base de código grande, ¿por dónde empiezo a optimizar?

Empieza midiendo con /context, luego prioriza las dos palancas más baratas: /clear entre tareas y recortar el CLAUDE.md por debajo de ~200 líneas. Después de eso, pasa a recortar el MCP de más, usar subagents para investigar, y un hook para filtrar la salida de las pruebas.

¿Apagar el extended thinking es perjudicial?

Puede serlo. Desactivar el pensamiento ahorra tokens de salida pero baja la calidad en tareas de razonamiento profundo (diseño de algoritmos, depuración multicapa). Solo bájalo con /effort o MAX_THINKING_TOKENS=8000 en tareas simples, y conserva el pensamiento para el trabajo que necesita razonamiento.

¿La herramienta advisor cuesta tokens extra?

Sí - cada llamada se cobra a la tarifa del modelo advisor, además del uso de tu modelo principal, y cuenta en /usage como cualquier cosa. Pero Claude solo llama al advisor en los puntos de decisión (comprometerse con un enfoque, un error recurrente, antes de declarar terminado), no en cada turno, así que normalmente sigue saliendo más barato que correr el modelo fuerte toda la sesión.

¿Cuántos tokens usan los workflows dinámicos?

No hay cifra oficial en dólares. El runtime tiene límites duros para acotar el costo desbocado: hasta 1.000 agentes en total, con como máximo 16 corriendo a la vez. El aviso de "Large workflow" en 25 agentes/1,5 millones de tokens es solo un aviso, no detiene la corrida; prueba en una porción pequeña antes de correr todo.

Conclusión + próximos pasos

La fórmula para optimizar tokens en Claude Code cabe en una cadena: medir → recortar contexto → elegir modelo → descargar en hooks/skills → subagents para bases grandes → advisor en vez de cambiar de modelo toda la sesión. No lo hagas todo de una vez; mide con /context y /usage, elige las 2-3 palancas de mayor ROI de la tabla, aplícalas y vuelve a medir. Recuerda que el ahorro depende de tu base de código y tus hábitos - mide en tu propia máquina.

Lee a continuación: gestionar el contexto y la memoria para profundizar en la compactación, precios y planes de Claude Code para elegir el plan que encaja con tu uso, y workflows dinámicos en Claude Code si necesitas orquestar muchos agentes para una tarea grande. Si prefieres usar un instrumental prearmado en vez de optimizar a mano, echa un vistazo a nuestra reseña de AgentKit para Claude Code.