Optimizar la velocidad de Claude Code: diagnosticar sesiones lentas y trabajar mejor

Cuando Claude Code parece lento, no conviene culpar primero al modelo. En la práctica, la lentitud suele venir de un historial enorme, demasiados archivos leídos, logs sin filtrar o instrucciones que invitan a explorar todo el repositorio. En este sitio también ocurrió: escritura, traducción, build, deploy y depuración dentro de la misma sesión hacían que cada respuesta fuera más pesada. La mejora real llegó al mirar /usage y /context, compactar con intención y limitar el alcance desde el primer prompt. Esta guía explica un flujo sencillo para principiantes: diagnosticar la causa, reducir exploración, configurar CLAUDE.md, usar subagentes cuando conviene y evitar los errores que empeoran la velocidad.

Diagnostica antes de ajustar

Empieza por medir. /usage es la entrada actual para ver uso: usuarios API ven tokens de sesión y coste estimado localmente; suscriptores ven barras de plan y atribución de uso. No lo uses como factura final, sino como panel operativo. Después mira /context. Ahí puedes ver si pesa más el historial, la memoria, MCP, herramientas o reglas cargadas. Si el problema es un CLAUDE.md gigante o servidores MCP innecesarios, cambiar de modelo no basta. /compact resume el historial, pero funciona mejor si indicas qué debe conservar: archivos modificados, tests fallidos, decisiones y dudas abiertas. Así la sesión queda más ligera sin perder continuidad.

# Run these inside Claude Code before changing the workflow
/usage
/context
/compact Preserve changed files, test failures, decisions, and open questions

Crea un workflow rápido por defecto

Mi bucle base es: revisar /usage y /context al iniciar una tarea pesada, ejecutar /compact en cortes naturales y usar /clear cuando se cambia a una tarea sin relación. Limpiar contexto a veces es la opción más barata. El segundo hábito es acotar. En lugar de pedir que entienda todo el proyecto, indica qué archivos leer primero, qué test ejecutar, qué carpetas evitar y qué evidencia debe devolver. El tercero es mantener CLAUDE.md pequeño. La guía oficial de memory lo plantea como lugar para hechos que se necesitan en cada sesión; procedimientos largos y casos raros deben ir a rules o skills.

claude -p "Fix only the null-check bug in src/api/auth.ts.
Read src/api/auth.ts and tests/auth.test.ts first.
Do not scan node_modules, dist, coverage, or unrelated feature folders.
Return the changed files, commands run, and remaining risks."

Pon en CLAUDE.md solo hechos necesarios siempre

El ejemplo es corto a propósito: da a Claude un mapa estable del repositorio sin convertir la memoria en un vertedero permanente de documentación.

# CLAUDE.md

## Project commands
- Build: npm run build
- Test: npm run test
- Type check: npm run typecheck

## Fast navigation
- API code: src/api/
- UI components: src/components/
- Tests: tests/

## Do not read unless explicitly requested
- node_modules/
- dist/
- coverage/
- .wrangler/

## Compact instructions
When compacting, preserve changed files, failing tests, decisions, credentials policy, and next actions.

Mide con un benchmark pequeño

No optimices solo por sensación. Ejecuta una tarea similar con prompt amplio y con prompt acotado, y compara tiempo, archivos leídos y calidad de la evidencia.

$runs = @(
  @{ Name = "wide"; Prompt = "Find and fix the auth bug in this project" },
  @{ Name = "scoped"; Prompt = "Fix the null-check bug in src/api/auth.ts only" }
)

foreach ($run in $runs) {
  $elapsed = Measure-Command { claude -p $run.Prompt }
  [pscustomobject]@{
    Name = $run.Name
    Seconds = [math]::Round($elapsed.TotalSeconds, 1)
  }
}

Tres casos de uso prácticos

Corrección pequeña

Entrega el archivo, el test que falla y la condición de aceptación. La exploración baja de muchos archivos a pocos y la revisión final es más clara.

Refactor grande

Separa investigación, cambio, prueba y revisión. Compacta al cerrar cada fase conservando decisiones y riesgos.

Pipeline de contenidos

Traducciones, listados y comprobaciones repetitivas pueden ir a subagentes. La sesión principal conserva decisiones y verificación final.

Fallos que conviene evitar

Usar /compact sin instrucciones puede borrar detalles útiles del resumen, como el comando que falló o la razón de una decisión.
Meterlo todo en CLAUDE.md crea una carga permanente: incidentes antiguos, notas personales y playbooks raros se leen siempre.
Quitar verificación para ganar velocidad sale caro. Filtra logs, pero conserva la línea fallida, el resultado esperado y el comando de reproducción.

Documentación oficial revisada

Claude Code costs and /usage: https://code.claude.com/docs/en/costs
Claude Code monitoring and telemetry: https://code.claude.com/docs/en/monitoring-usage
Claude Code memory and CLAUDE.md: https://code.claude.com/docs/en/memory

Qué verifiqué en esta reescritura

La revisión usa la documentación actual de Costs, Monitoring y Memory, y reemplaza hábitos centrados solo en /cost por /usage, /context, /compact y CLAUDE.md.

Siguiente paso

Si tu equipo quiere acelerar Claude Code, no empieces comprando un modelo mayor ni añadiendo más automatización. Primero estandariza el prompt, la memoria y el recibo de verificación.