Si llevas más de unas semanas usando Claude Code, probablemente hayas notado que las sesiones largas se vuelven costosas. Una sesión prolongada con Opus en una refactorización de múltiples archivos puede costar más que un café. Multiplica eso por un equipo de cinco personas y uso diario, y los números empiezan a importar. La buena noticia es que la mayor parte de ese costo es innecesario: la mayoría de los tokens en una sesión típica van a tareas donde un modelo más rápido y barato habría producido resultados idénticos.
Este artículo es un complemento práctico de mi publicación anterior sobre agentes de IA en el flujo de trabajo del desarrollador. Esa trataba sobre seguridad, permisos y el modelo mental general. Esta cubre la función específica de Claude Code que mayor diferencia marcó en mis costos y velocidad: los subagentes y el enrutamiento deliberado de modelos.
Todo lo aquí descrito se basa en mi configuración real de producción. Los ejemplos de configuración son archivos reales de este proyecto.
GitHub template: publiqué el setup completo como repositorio público: Claude Code PHP Agents. Incluye AGENTS.md, CLAUDE.md, los subagentes de este artículo y plantillas para WordPress Bedrock, WordPress clásico, Laravel y proyectos PHP genéricos.
Qué son realmente los subagentes
Un subagente en Claude Code es un asistente especializado con su propio modelo, su propia lista permitida de herramientas y su propio prompt del sistema. Cuando la sesión principal delega una tarea a un subagente, este ejecuta en una ventana de contexto aislada: todos los tokens que consume y todos los archivos que lee permanecen dentro de esa ventana. La sesión principal solo ve el resultado final.
Ese aislamiento tiene dos efectos que se potencian mutuamente. Primero, el subagente puede usar un modelo más barato sin afectar la calidad de la conversación principal. Segundo, el contexto principal se mantiene pequeño, lo que significa que cada mensaje posterior en la sesión principal también es más barato.
Los subagentes se definen como archivos Markdown en .claude/agents/. Uno mínimo se ve así:
---
name: repo-explorer
description: Use this agent when you need to find files, understand code structure, or search for patterns before editing.
model: haiku
tools:
- Read
- Grep
- Glob
- Bash
---
Search the codebase and return findings as path:line pointers. Do not modify any files.Ese es el archivo completo. El campo model acepta haiku, sonnet, opus o un ID de modelo completo. El campo tools es una lista permitida explícita: si lo omites, el subagente hereda todas las herramientas, lo cual está bien para algunos agentes y es peligroso para los de solo lectura. El prompt del sistema (todo después del frontmatter) le dice al subagente exactamente qué hacer y qué no hacer.
Los agentes a nivel de proyecto en .claude/agents/ deben comprometerse al repositorio para que todo el equipo comparta la misma configuración. Los agentes a nivel de usuario en ~/.claude/agents/ se aplican a todos tus proyectos.
El patrón de tres niveles de modelos
La idea central detrás de la optimización de tokens con subagentes es que diferentes tareas tienen requisitos de razonamiento muy diferentes. Una búsqueda de archivos no necesita la misma profundidad que una decisión arquitectónica. Usar el mismo modelo potente para ambas es como contratar a un ingeniero senior para ejecutar grep.
No recomiendo publicar una promesa como “esto ahorra exactamente el 70%” salvo que hayas medido tus propias sesiones. En mis proyectos, el ahorro se volvió evidente cuando el modelo caro dejó de hacer búsqueda de archivos, lectura de logs y verificaciones mecánicas en el navegador. La cifra exacta depende del tamaño del repositorio, la frecuencia de delegación y el modelo que uses como sesión principal.
| Modelo | Mejor para | Qué evitar |
|---|---|---|
| Haiku | Búsqueda de archivos, exploración de código, lectura de docs, escritura de pruebas, formateo, mensajes de commit, changelogs | Decisiones arquitectónicas, depuración compleja, refactorizaciones multi-archivo |
| Sonnet | Implementación de features, corrección de bugs, refactorización estándar, revisión de código, la mayoría de las tareas diarias | Tareas donde la velocidad importa más que la profundidad |
| Opus | Planificación arquitectónica, codebases desconocidas, análisis complejo multi-archivo, cambios de alto riesgo, refactorizaciones transversales | Tareas rutinarias, cualquier cosa donde Sonnet sea suficientemente rápido |
La sesión principal corre en Sonnet. Los subagentes Opus manejan planificación y revisión. Los subagentes Haiku manejan descubrimiento y generación. Esta no es una regla rígida: es un punto de partida que ajustas a tu proyecto.
Archivos listos para .claude/agents/
Este es el set mínimo que puedes copiar al proyecto y adaptar. Mantengo los system prompts en inglés porque son más fáciles de reutilizar entre equipos y repositorios.
.claude/agents/explorer.md
---
name: explorer
description: Use proactively when a task needs codebase discovery before planning or editing. Finds relevant files, symbols, routes, tests, and existing patterns. Returns path:line references only.
model: haiku
tools:
- Read
- Grep
- Glob
- Bash
---
You are a read-only codebase explorer.
Find the files, symbols, routes, tests, configuration, documentation, and existing patterns relevant to the user's task.
Rules:
- Do not modify files.
- Do not propose an implementation plan unless asked.
- Prefer precise path:line references over broad summaries.
- If you use Bash, use read-only commands only.
- If the evidence is weak, say what you could not find.
Return:
1. Relevant files and why they matter.
2. Existing patterns or helpers to reuse.
3. Tests or verification paths nearby.
4. Open questions or missing context.
.claude/agents/planner.md
---
name: planner
description: Use after explorer for architecture decisions, multi-file changes, auth, billing, migrations, routing, caching, i18n, or risky refactors. Produces a plan; does not edit code.
model: opus
tools:
- Read
- Grep
- Glob
---
You are a senior implementation planner.
Use the provided task brief and explorer findings to produce a practical implementation plan.
Rules:
- Do not edit files.
- Do not run shell commands.
- Prefer the smallest safe change unless the user explicitly asks for a larger refactor.
- Call out risks, unknowns, and rollback considerations.
Return:
1. Recommended approach.
2. Files to change, with the reason for each file.
3. Step-by-step implementation order.
4. Tests and manual verification.
5. Risks and decisions needed from the developer.
.claude/agents/reviewer.md
---
name: reviewer
description: Use after implementation for high-risk changes or before committing. Reviews changed files first and expands only when needed for correctness or safety.
model: opus
tools:
- Read
- Grep
- Glob
- Bash
---
You are a strict code reviewer.
Review the current changes for correctness, regressions, security issues, missing tests, and unintended side effects.
Rules:
- Start from the diff and changed files.
- Read unchanged files only when needed to verify a specific risk.
- Do not rewrite code.
- If you use Bash, prefer read-only commands such as git diff, git status, and test discovery.
Return findings first, ordered by severity. If there are no findings, say that clearly and list residual risk.
.claude/agents/browser-tester.md
---
name: browser-tester
description: Use for local UI smoke tests, regression checks, console/network inspection, and screenshot capture. Requires the local dev server to be running.
model: haiku
tools:
- mcp__chrome_devtools__navigate_page
- mcp__chrome_devtools__take_snapshot
- mcp__chrome_devtools__take_screenshot
- mcp__chrome_devtools__list_console_messages
- mcp__chrome_devtools__list_network_requests
- mcp__chrome_devtools__click
- mcp__chrome_devtools__fill
- mcp__chrome_devtools__press_key
---
You are a browser regression tester.
Follow the provided flow in the local browser and report observable results.
Rules:
- Do not modify source files.
- Do not invent expected behavior.
- Capture screenshots for visual regressions or unclear states.
- Check console errors and failed network requests.
Return the flow tested, what passed, what failed, console/network errors, and screenshot notes.
Siete consejos para reducir costos de tokens en Claude Code
Consejo 1: Explorer antes que planner
El error más costoso en una sesión de Claude Code es pedirle a Opus que planifique algo sin decirle primero dónde están las cosas. Opus leerá archivos, buscará patrones y construirá contexto por sí mismo. Todo eso cuesta tokens de Opus cuando podría costar tokens de Haiku.
El patrón que soluciona esto es simple: siempre ejecutar un subagente explorer rápido antes de llamar al planner. El explorer devuelve punteros ruta:línea. El planner recibe esos punteros y puede enfocarse en razonar en lugar de descubrir.
---
name: planner
description: Use this agent before implementing billing, auth, multi-layer features, complex refactors, or any change requiring multi-file impact analysis. Call after explorer.
model: opus
tools:
- Read
- Grep
- Glob
---
Analyse the codebase context provided. Return a concise written plan with specific file paths, function names, and a clear ordering of steps.
Note tradeoffs. Flag risks. Do not write production code.El planner no tiene Bash ni Write. Es un agente de lectura y razonamiento, no de ejecución. Los tokens de Opus son caros; los comandos de shell de Opus son caros y riesgosos a la vez.
Consejo 2: Reviewer solo en las superficies cambiadas
La revisión de código es otro lugar donde los desarrolladores desperdician tokens. Pedirle a un agente reviewer que lea todo el codebase para cada cambio es como pedirle a un ingeniero senior que audite todo el repositorio antes de aprobar una corrección de una línea.
La solución es hacer el reviewer diff-first: lee solo los archivos modificados a menos que una pregunta de seguridad requiera contexto más amplio. Esta restricción suele ahorrar mucho contexto porque el reviewer deja de releer todo el repositorio para evaluar un diff pequeño.
Consejo 3: Haiku para todo lo que no requiere razonamiento
Una gran clase de tareas en el flujo de desarrollo no requiere razonamiento en absoluto: escribir un mensaje de commit, generar una entrada de changelog, describir una función para documentación, ejecutar verificaciones de lint, leer un archivo de log, formatear una respuesta JSON. Haiku las maneja bien y cuesta aproximadamente entre 10 y 20 veces menos por token que Opus.
Un subagente browser-tester es otro ejemplo. La verificación de UI mediante Chrome DevTools MCP es principalmente mecánica: navegar, capturar pantalla, verificar errores de consola, reportar hallazgos. El subagente no necesita razonar profundamente; necesita ejecutar de manera confiable. Escala a Sonnet manualmente solo cuando la reproducción del bug apunta a una interacción compleja que Haiku no puede razonar.
Consejo 4: Usa CLAUDE.md como herramienta de eficiencia de tokens
La mayoría de los desarrolladores trata CLAUDE.md como un documento de configuración único. El enfoque más útil es que es el único contenido garantizado de sobrevivir cualquier evento de compresión de contexto. Cuando Claude Code auto-compacta una sesión larga, el contexto principal se resume. CLAUDE.md no: se reinyecta al inicio de cada turno.
Cualquier instrucción que te encuentres repitiendo en la conversación debe moverse a CLAUDE.md. Anthropic aplica caché de prompts automáticamente a CLAUDE.md y otro contenido de sistema repetido. Los tokens de entrada en caché cuestan aproximadamente un 90% menos que los no cacheados. Un CLAUDE.md detallado y bien mantenido no es solo más claro para el agente; es más barato para ti.
Consejo 5: La higiene de sesión importa más que la elección del modelo
El modelo que eliges importa menos que lo que hay en el contexto cuando lo llamas. Un contexto limpio de 10.000 tokens con Opus cuesta menos que un contexto obsoleto de 80.000 tokens con Sonnet, y la respuesta de Opus es mejor porque la relación señal-ruido es mayor.
Tres hábitos que marcan la mayor diferencia: una tarea por sesión; ejecuta /compact al 60% de capacidad del contexto en lugar de esperar el auto-compact al 95%; ejecuta /clear entre tareas no relacionadas en la misma sesión.
Consejo 6: Protégete contra los bucles de subagentes
Los subagentes son poderosos, pero introducen un modo de fallo que no existe en sesiones de un solo agente: los bucles. Si la sesión principal delega al explorer, el explorer es incierto, y la sesión principal delega nuevamente, puedes quemar tokens en la misma pregunta repetidamente sin acercarte a una respuesta.
La solución es una política escrita de anti-bucle en las reglas de delegación: no invocar el mismo subagente dos veces para la misma pregunta sin resolver; reutilizar la salida existente del planner o reviewer a menos que la implementación haya cambiado materialmente; si dos llamadas consecutivas a subagentes devuelven contenido superpuesto, dejar de delegar y actuar con lo que tienes.
Consejo 7: Nunca envíes salida sin procesar a Opus
Archivos de log grandes, exports completos de bases de datos, respuestas API sin procesar, salida larga de grep: nunca los pases directamente a un agente Opus. Opus leerá cada token. Resume primero, luego pasa el resumen. Si tu reviewer necesita entender una migración de 500 líneas, no vuelques todo el archivo. Pasa el diff, el nombre de la tabla y un párrafo describiendo la intención.
Una configuración real: los cuatro subagentes que uso en este proyecto
Para contexto: este es un sitio WordPress Bedrock con backend PHP, un tema personalizado, Polylang para cuatro idiomas y caché LiteSpeed. Los cuatro subagentes en .claude/agents/: explorer (Haiku) para descubrimiento rápido de archivos y símbolos; planner (Opus) para análisis arquitectónico y planificación; reviewer (Opus) para revisión post-implementación de cambios de alto riesgo; browser-tester (Haiku) para verificación de UI mediante Chrome DevTools MCP.
La política de delegación en CLAUDE.md le dice a la sesión principal cuándo llamar a cada subagente. La sesión principal corre en Sonnet. Opus está reservado para los dos agentes que realmente necesitan razonamiento profundo. Haiku maneja los dos agentes que necesitan velocidad y amplitud.
Esta configuración no surgió de la teoría. Surgió de observar qué tareas se beneficiaban de un mejor razonamiento, cuáles solo necesitaban ejecución rápida, y dónde ocurrían los bucles. Empieza más simple y añade agentes cuando identifiques un patrón claro que se repite.
¿Vale la pena publicar tu configuración de subagentes como proyecto open source?
Sí, si lo presentas bien. Yo lo hice en claude-code-php-agents: un repositorio público pequeño con AGENTS.md, CLAUDE.md, archivos .claude/agents/ reutilizables y plantillas para PHP, WordPress y Laravel. Es más útil que dejar la configuración solo dentro de un artículo porque el lector puede clonar el repositorio, copiar lo que necesita y adaptar las reglas a su proyecto.
La salvedad principal es que las definiciones de subagentes están estrechamente acopladas al contexto del proyecto. Lo que se transfiere bien es el patrón: la estructura de tres niveles, las restricciones de solo lectura para planificadores y revisores, las reglas anti-bucle, la política de delegación en CLAUDE.md. Los archivos específicos son un punto de partida, no una solución lista para usar.
Si publicas, considera estructurarlo como «aquí está el razonamiento detrás de cada decisión» en lugar de «aquí están los archivos para copiar». El razonamiento envejece mejor que la configuración.
Lo que esto no resuelve
Los subagentes y el enrutamiento de modelos hacen Claude Code considerablemente más barato y rápido. No cambian el modelo de seguridad fundamental del artículo anterior. Un planner Opus con acceso de escritura a producción no es más seguro que un agente Sonnet con el mismo acceso: el nivel del modelo se refiere al costo y la profundidad de razonamiento, no a la confianza. Los controles de permisos, hooks y puertas de revisión humana del flujo de seguridad siguen aplicándose a cada agente independientemente del modelo que ejecute.
Los subagentes son un multiplicador. Como la mayoría de los multiplicadores, amplifica lo que llevas a la conversación.
Artículos relacionados
- Agentes de IA en el flujo de trabajo del desarrollador — el modelo de seguridad detrás de esta configuración de subagentes: permisos, MCP, pruebas en navegador, review gates y control manual del despliegue.
- Cuando un secreto filtrado en Git acabó reescribiendo cuatro años de historial — por qué las credenciales con scope importan antes de dar acceso a sistemas reales a cualquier agente.
