Guía práctica para decidir cuándo usar sub-agents
Claude Code tiene un Agent tool que permite lanzar sub-agents independientes durante una conversación. Cada sub-agent tiene su propio contexto, ejecuta su tarea y devuelve el resultado al agent principal.
Suena poderoso, pero en la práctica, la mayoría de las veces no lo necesitas. Este artículo aclara cuándo usar sub-agents realmente aporta valor y cuándo solo añade complejidad innecesaria.
No puedes llamar al Agent tool directamente desde CLAUDE.md o un slash command: es una herramienta interna que Claude Code decide usar por su cuenta. Lo que sí puedes hacer es influir en esa decisión a través de tus prompts.
Así funciona el flujo:
Características clave:
- Contexto independiente: el sub-agent no ve el historial de la conversación principal, solo el prompt que recibió al iniciar
- Compresión de resultados: sin importar cuántos archivos leyó o cuántos comandos ejecutó internamente, lo que regresa al agent principal es un resumen
- Ejecución en paralelo: se pueden lanzar múltiples sub-agents simultáneamente
El caso más clásico. Le pides a Claude Code que investigue un problema y necesitas explorar varias direcciones al mismo tiempo.
Por ejemplo: "¿Cómo está implementado el sistema de autenticación en este proyecto?"
Sin sub-agents, Claude Code ejecutaría todo en secuencia: leer el auth controller, luego el middleware, luego las rutas, luego el modelo, luego la configuración... paso a paso. Lento.
Con sub-agents:
Lanzar 3 sub-agents en paralelo:
- Agent 1: investigar la lógica de autenticación en controllers y middleware
- Agent 2: analizar el diseño de usuarios y sesiones en la capa de modelos
- Agent 3: revisar archivos de configuración y variables de entorno relacionadas con autenticación
Tres direcciones al mismo tiempo, resultados consolidados. En tu CLAUDE.md puedes guiar esto así:
## Tareas de investigación
Cuando necesites investigar un problema que abarca múltiples módulos,
prioriza lanzar varios sub-agents en paralelo para explorar cada área,
y luego consolida las conclusiones.
La ventana de contexto de Claude Code es limitada. Si una subtarea requiere leer muchos archivos pero al final solo necesitas una conclusión, un sub-agent puede absorber todo ese "ruido del proceso" sin contaminar el contexto principal.
Ejemplos típicos:
Lo que tienen en común estas tareas: mucha entrada, poca salida. El sub-agent digiere toda la información internamente y solo devuelve lo esencial.
Para tareas donde no estás seguro del resultado, puedes usar un sub-agent con el parámetro isolation: "worktree". Esto lo hace trabajar en un git worktree independiente. Si algo sale mal, tu directorio de trabajo actual no se ve afectado.
## Refactorizaciones de alto riesgo
Para refactorizaciones de gran alcance, usa sub-agents con aislamiento worktree.
Confirma que el resultado es correcto antes de hacer merge.
Escenarios ideales:
- Refactorizaciones exploratorias: no sabes si un enfoque funcionará, deja que el sub-agent lo pruebe primero
- Comparación de enfoques en paralelo: implementar la misma funcionalidad de dos formas distintas y comparar
- Generación de código: generar código boilerplate en volumen, revisarlo y luego integrarlo
"Renombrar esta función de camelCase a snake_case" — solo hazlo directamente. El overhead de lanzar un sub-agent (construir contexto, esperar respuesta, interpretar resultado) es mayor que simplemente ejecutar la tarea.
Regla práctica: si un Grep + un Edit resuelven el problema, no dividas en sub-agents.
"Leer la configuración → modificar el código según la configuración → actualizar los tests según los cambios"
En tareas con dependencias en cadena, cada paso depende del resultado del anterior. Si las divides en sub-agents, tendrías que pasar resultados intermedios de un prompt a otro: es complicado y propenso a perder información. Mejor ejecutar en secuencia.
Un sub-agent devuelve texto resumido, no datos estructurados. Si necesitas que haga una modificación exacta (como insertar código específico en la línea 47), es más confiable que lo haga el agent principal directamente.
Los sub-agents son buenos para "investigar y dar conclusiones", no para "ejecutar cambios con precisión".
Si la conversación acaba de empezar y la ventana de contexto está prácticamente vacía, no tiene sentido dividir en sub-agents para "proteger el contexto". Espera a que la conversación crezca y el agent principal empiece a comprimir el historial; ahí sí considera delegar trabajo pesado a sub-agents.
Veamos un escenario concreto: investigar todos los controllers que usan before_action en un proyecto Rails y analizar los patrones de autenticación y autorización.
Sin sub-agents:
Claude Code lee los archivos de controllers uno por uno, y cada lectura ocupa espacio en el contexto principal. Con 20 controllers, solo el contenido de los archivos podría consumir una cantidad enorme de tokens. Para cuando te da el análisis final, los detalles que leyó al principio probablemente ya fueron comprimidos y perdidos.
Con sub-agents:
Lanzar sub-agent: "Lee todos los controllers en app/controllers/,
encuentra todos los callbacks before_action, analiza los patrones
de autenticación y autorización, y devuelve un resumen clasificado."
El sub-agent lee todos los archivos en su propio contexto y devuelve un resumen limpio. El contexto del agent principal casi no se consume, y con la conclusión en mano puede seguir avanzando.
No puedes forzar a Claude Code a usar o no usar sub-agents, pero puedes establecer preferencias a través de CLAUDE.md:
## Preferencias de uso de agents
### Tareas que conviene delegar a sub-agents
- Investigación transversal (consultar 3 o más directorios)
- Búsqueda y análisis de código a gran escala
- Refactorizaciones exploratorias (con aislamiento worktree)
### Tareas que NO deben usar sub-agents
- Modificaciones en un solo archivo
- Operaciones secuenciales con dependencias
- Bug fixes donde ya se sabe exactamente qué cambiar
¿El "proceso" de esta tarea es mucho más grande que la "conclusión"?
Si la respuesta es sí — usa un sub-agent para que digiera el proceso y solo devuelva la conclusión.
Si no — hazlo directamente, sin capas intermedias.
Los sub-agents no son mejores por ser más. Son una herramienta de gestión de contexto, no un framework de programación concurrente. Bien usados, mantienen a Claude Code lúcido en proyectos grandes. Mal usados, solo desperdician tiempo de arranque.