Cómo reducir 18% el consumo de tokens en Claude Code (con datos reales)
Es mucho más eficiente tener muchos archivos pequeños separados por responsabilidades que un archivo grande que haga muchas cosas. Claude Code (y cualquier herramienta de desarrollo con IA) necesita leer y procesar contexto para entender qué hacer. Archivos grandes y mezclados gastan más tokens, tardan más, y pierden el foco.
¿Por qué funciona?
Principio de Responsabilidad Única (SRP) aplicado a eficiencia con IA:
- Contexto preciso → la IA solo lee lo que necesita
- Menos ruido → menor probabilidad de confusión o errores
- Navegación eficiente → los nombres de archivo guían a la IA directamente
- Cambios quirúrgicos → ediciones más pequeñas y precisas
Métricas reales — Experimento Febrero 2026
Prueba real con Claude Code (Haiku): app e-commerce idéntica en dos versiones — 1 archivo monolítico (814 líneas) vs 9 archivos modulares (~35-146 líneas c/u). 4 tareas idénticas ejecutadas en ambas versiones.
| Versión | Archivos | Líneas | Bytes |
|---|---|---|---|
| Monolítico | 1 (app.ts) | 814 | 25,419 |
| Modular | 9 especializados | 784 | 25,987 |
| Tarea | Monolítico | Modular | Diferencia |
|---|---|---|---|
| Bug Fix (validación email) | 49,466 tokens | 40,447 tokens | -18.2% tokens, -92% ruido |
| Agregar Feature (refunds) | 50,350 tokens | 50,949 tokens | +1.2% |
| Explicar Flujo (crear orden) | 50,803 tokens | 53,284 tokens | +4.9% |
| Refactorizar (i18n) | 49,687 tokens | 51,699 tokens | +4.1% |
Hallazgos clave
- Tareas focalizadas (Bug Fix): Modular gana por goleada. El agente fue directo a
validation-utils.ts(67 líneas) sin leer las 814 del monolítico. 18.2% menos tokens, 92% menos ruido. - Tareas cross-cutting: Diferencia mínima (1-5%) a esta escala. Monolítico tiene ligera ventaja por menos lecturas de archivos.
- El factor decisivo es la escala: Con 814 líneas ambos caben en contexto. En proyectos reales (5,000+ líneas), el monolítico se vuelve imposible. Los archivos modulares mantienen tamaño constante.
Conclusión: Para tareas enfocadas (80% del día a día), la estructura modular ahorra ~18% de tokens y reduce el ruido en ~92%. A partir de ~1,000 líneas, la ventaja modular crece exponencialmente.
Organización de archivos
La optimización de mayor impacto. Tres reglas:
- Máximo 150 líneas por archivo — si es más largo, dividir por responsabilidad
- Responsabilidad única — un concepto por archivo
- Nombres descriptivos en kebab-case — el nombre le dice a la IA exactamente qué hay dentro
| Evitar | Preferir | Por qué |
|---|---|---|
utils.ts con 500+ líneas | string-utils.ts, date-utils.ts | La IA sabe cuál leer |
helpers.ts | date-formatting-helpers.ts | Scope claro |
api.ts con todos los endpoints | users-api.ts, products-api.ts | Un grupo por archivo |
index.ts (con lógica) | user-authentication.ts | Index solo re-exporta |
CLAUDE.md optimizado
Tu CLAUDE.md es documentación para la IA, no para humanos. Un CLAUDE.md bien hecho puede reducir consumo de tokens 50-70%.
- Mantenerlo bajo ~500 líneas (lo esencial)
- Especificar estructura del proyecto y comandos clave
- No meter documentación completa — usar triggers que referencien archivos detallados
Un proyecto logró 54% de reducción en tokens iniciales (7,584 → 3,434) poniendo solo triggers en CLAUDE.md e instrucciones detalladas en skills que cargan bajo demanda.
Principio: Claude no necesita toda la info de entrada. Necesita saber cuándo cargarla.
Optimizaciones de contexto y costos
| Comando | Cuándo usar | Beneficio |
|---|---|---|
/clear | Al cambiar de tarea | Elimina contexto irrelevante |
/compact | Conversación larga | Comprime historial |
/context | Para diagnosticar | Ver qué consume tokens |
Tip: Si has corregido a Claude más de 2 veces en el mismo tema → /clear y empieza con un prompt mejor.
- Subagentes: Delegar tests, logs, búsquedas amplias. El output verboso queda en el contexto del subagente — solo el resumen vuelve.
- MCPs: Máximo 10 activos y 80 herramientas totales. Cada MCP consume tokens aunque no lo uses.
- Modelo estratégico: Sonnet para 80% de tareas, Opus para arquitectura compleja, Haiku para tareas simples (hasta 18x más barato).
Skill instalable: token-optimizer
Todo este conocimiento está empaquetado como una Agent Skill que cualquiera puede instalar:
npx skills add alexismunoz1/token-optimizerCompatible con Claude Code, Cursor, Codex y más. Es open source, así que sentite libre de contribuir en GitHub para que, entre todos, hagamos que siga mejorando.