Optimización de tokens en Claude Code: reduce coste con /usage sin perder calidad

Optimizar tokens en Claude Code no es solo bajar la factura. Cuando el contexto crece demasiado, las respuestas se vuelven más lentas, se mezclan decisiones antiguas con la tarea actual y Claude vuelve a leer logs, diffs y notas que ya no aportan. El objetivo real es mantener la misma calidad con menos contexto irrelevante.

En junio de 2026, el punto de entrada práctico es /usage. La referencia oficial de comandos lo describe como el comando para ver session cost, plan usage limits y activity stats. /cost y /stats existen como alias, pero para documentación y hábitos de equipo conviene hablar de /usage. En planes Pro, Max, Team y Enterprise también puede mostrar atribución por skills, subagentes, plugins y servidores MCP.

El método de este artículo tiene cuatro capas: observar, reducir contexto base, separar trabajo ruidoso y medir los flujos repetibles. Un hook es un script o endpoint que se ejecuta en un evento fijo del ciclo de Claude Code; un subagente es un contexto separado para una tarea estrecha; un harness es el andamiaje que hace que el trabajo del agente sea repetible y seguro.

flowchart LR
  A["Observar: /usage y /context"] --> B["Reducir: CLAUDE.md y entradas acotadas"]
  B --> C["Separar: hooks / skills / subagentes"]
  C --> D["Medir: OpenTelemetry y reglas de equipo"]

Empieza con /usage

No necesitas ejecutar /usage después de cada prompt. Úsalo cuando la sesión se note lenta, después de una salida grande de herramientas, antes de pasar la tarea a otra persona o agente, y al terminar un flujo que vas a repetir. Combínalo con /context para saber si el coste viene de la tarea actual, del historial viejo, de memoria o del contexto de herramientas.

La parte de facturación requiere cuidado. El bloque Session de /usage es una estimación local calculada desde tokens. Los usuarios de API deben confirmar la facturación real en Claude Console. En suscripciones, el dollar figure de la sesión no debe leerse como factura directa; las barras de uso del plan y la atribución de actividad son más útiles.

# Dentro de Claude Code
/usage
/context

# Si la conversación es larga pero la tarea continúa
/compact Preserve changed files, failing tests, decisions, and unresolved questions.

# Al cambiar a una tarea no relacionada
/clear

/compact resume estado importante para seguir trabajando. /clear empieza un contexto nuevo. Si limpias demasiado pronto, se pierden decisiones; si nunca limpias, cada tarea paga por el contexto anterior.

Mantén corta la memoria cargada siempre

Los tokens no vienen solo de lo que acabas de escribir. También cuentan el historial, CLAUDE.md, auto memory, logs, salidas de herramientas, servidores MCP y notas de investigación. Divide la información en tres grupos.

Tipo	Mejor lugar	Ejemplo
Siempre necesario	CLAUDE.md corto	Build, tests, restricciones duras
Solo para esta tarea	Conversación y /compact	Archivos cambiados, tests fallidos, decisiones abiertas
Desechable tras mirar	Salida filtrada	Logs largos, diffs generados, búsquedas amplias

La documentación oficial de memory explica que CLAUDE.md se carga como contexto. Cuanto más largo sea, más coste fijo tendrá cada sesión. Separar instrucciones con imports puede ordenar el archivo, pero no reduce tokens si todo se carga al inicio.

# 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/

## Avoid by default
- Do not scan node_modules/, dist/, coverage/, or generated clients.
- Do not paste full logs. Ask for the failing command and relevant lines.

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

Listas largas de revisión, reglas de traducción o runbooks de migración suelen encajar mejor como skills o documentos separados. Una skill se invoca cuando hace falta; CLAUDE.md se paga desde el arranque.

Filtra antes de que Claude lea

El desperdicio más común es pegar todo el log o todo el diff. Claude necesita evidencia, no un volcado. Guarda el artefacto completo en disco y pásale primero las líneas que pueden cambiar la decisión.

# No pegues todo el log de producción: usa request ID y errores cercanos
tail -n 800 logs/app.log | grep -E -n -C 4 "request_id=abc123|ERROR|WARN"

# Mira el tamaño del PR antes de leer todo el diff
git diff --stat
git diff -- src/auth.ts tests/auth.test.ts

# Guarda la salida completa y muestra a Claude solo la zona fallida
npm test 2>&1 | tee test.log
grep -E -n -C 6 "FAIL|ERROR|Error|failed|Assertion" test.log | head -160

Esto no oculta información. Solo define el primer corte que ve Claude. Si no basta, amplías con otro archivo o más líneas del log.

Usa hooks con cuidado

Si repites el mismo filtro, puedes convertirlo en hook. Un hook no debe ocultar fallos ni aprobar comandos arriesgados en silencio. Empieza con ask, revisa el comando reescrito y pruébalo localmente.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
set -euo pipefail

input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')

case "$cmd" in
  npm\ test*|pnpm\ test*|pytest*|go\ test*)
    filtered="$cmd 2>&1 | grep -E -n -C 6 '(FAIL|ERROR|Error|failed|Assertion)' | head -160"
    jq -n --arg command "$filtered" '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "ask",
        permissionDecisionReason: "Run test command with filtered output",
        updatedInput: { command: $command }
      }
    }'
    ;;
  *)
    echo '{}'
    ;;
esac

El ejemplo requiere jq. Para uso de equipo, guarda también el log completo y conserva el exit code original. El hook solo merece la pena si reduce ruido sin reducir evidencia.

Separa el trabajo verboso

Los subagentes son útiles cuando el proceso es largo pero el resultado que necesita la sesión principal es corto: revisar documentación oficial y devolver cambios, validar diez locales y devolver bloqueos, o ejecutar un test fallido y resumir el primer stack trace accionable.

No crees subagentes por costumbre. Cada uno tiene su propio contexto, memoria, herramientas y coste. Úsalos para proteger el contexto de decisión, no para paralelizar trabajo ambiguo. Lo mismo aplica a las skills: saca de CLAUDE.md los playbooks largos y poco frecuentes.

Mide los flujos de equipo

Para una persona, /usage y /context suelen bastar. En equipos, OpenTelemetry convierte coste, tokens, modelo, duración y actividad de herramientas en datos compartidos. Empieza con console exporter antes de conectar un collector.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_LOGS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=10000
export OTEL_LOGS_EXPORT_INTERVAL=5000

claude

Mide calidad junto al uso. Si los tokens bajan un 30%, pero suben las rondas de corrección o los defectos en revisión, el proceso empeoró.

Casos de uso reales

Investigación de logs

Pasa request ID, errores recientes, timestamps, comportamiento esperado y líneas cercanas. Empieza pequeño y amplía solo si falta evidencia.

Revisión de código

Entrega git diff --stat, archivos cambiados, salida de tests y focos de revisión. Divide PR grandes en seguridad, rendimiento y compatibilidad.

Publicación multilingüe

Deja las decisiones del artículo canónico en la sesión principal. Traducción, enlaces, description y CTA pueden revisarse en contextos separados.

Día de formación

En talleres, la concurrencia sube. Reglas como “leer cinco archivos primero”, “máximo 160 líneas de fallo” y “justificar ampliar scope” estabilizan el consumo.

Errores a evitar

• Documentar solo /cost. Usa /usage y menciona /cost y /stats como alias.
• Recortar evidencia. Reproducción, salida esperada, comando fallido y decisiones deben sobrevivir.
• Convertir CLAUDE.md en un cuaderno operativo. Los flujos raros van mejor en skills.
• Activar demasiados MCP. Revisa /mcp y usa CLI si resuelve lo mismo con menos contexto.
• Esconder fallos con hooks. Guarda el log completo y muestra un corte filtrado.
• Asumir que los subagentes siempre son más baratos. Aíslan ruido, pero tienen contexto propio.

Script breve de handoff

Este script Node.js sin dependencias resume archivos cambiados, tamaño del diff y fallos de test.

#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";

function git(args) {
  return execFileSync("git", args, { encoding: "utf8" }).trim();
}

const testLogPath = process.argv[2];
const changedFiles = git(["diff", "--name-only"])
  .split(/\r?\n/)
  .filter(Boolean);
const diffStat = git(["diff", "--stat"]);
const testLog = testLogPath && existsSync(testLogPath)
  ? readFileSync(testLogPath, "utf8")
  : "";
const failures = testLog
  .split(/\r?\n/)
  .filter((line) => /(FAIL|ERROR|Error|failed|Assertion)/.test(line))
  .slice(0, 80);

console.log("# Claude handoff brief\n");
console.log("## Changed files");
console.log(changedFiles.length ? changedFiles.map((file) => `- ${file}`).join("\n") : "- None");
console.log("\n## Diff stat");
console.log(diffStat || "No diff");
console.log("\n## Test failures");
console.log(failures.length ? failures.map((line) => `- ${line}`).join("\n") : "- No matching failure lines");

node scripts/claude-brief.mjs test.log > claude-brief.md

Documentación oficial revisada

• Commands para /usage, /context, /compact y /clear.
• Manage costs effectively para costes, MCP, hooks, skills, subagentes y esfuerzo de modelo.
• How Claude remembers your project para CLAUDE.md y auto memory.
• Hooks reference y Monitoring para PreToolUse y OpenTelemetry.

También puedes leer optimización de velocidad, guía de permisos y guía de harness engineering.

Resultado probado

En esta reescritura usé el artículo japonés como canónico y validé la documentación oficial antes de actualizar los diez locales. La mejora más práctica fue separar memoria permanente, estado de tarea y logs desechables. Un brief con archivos cambiados, líneas fallidas y verificación dio mejores respuestas que pegar toda la salida de tests.

Para prompts y material reutilizable, empieza en ClaudeCodeLab products. Para rollout de equipo, permisos, política de revisión, telemetría y formación, usa Claude Code training and consultation.