Claude Code subagents: desarrollo en paralelo

Los subagents son una de las capacidades más potentes de Claude Code. Permiten dividir tareas complejas en subtareas independientes que se ejecutan simultáneamente, reduciendo el tiempo total de ejecución. La clave es que trabajan simultáneamente: mientras un subagent analiza el frontend, otro puede estar revisando el backend, y un tercero ejecutando tests.

Cómo funcionan internamente

Cuándo Claude Code detecta que puede paralelizar trabajo, lanza subagents usando la herramienta Task. Cada subagent es una instancia independiente que:

• Recibe una instrucción específica y acotada del coordinador
• Tiene acceso a las herramientas del sistema (lectura de archivos, búsqueda, ejecución de comandos)
• Opera sin ver el historial completo de la conversación
• Devuelve un resultado que el agente principal integra en su respuesta
• Tiene su propia ventana de contexto independiente

Es un patrón de tipo Coordinator-Worker: el agente principal actúa como coordinador que planifica, distribuye y sintetiza. Los subagents son workers especializados que ejecutan y reportan.

Internamente, el flujo es: tu prompt llega al coordinador, que analiza si puede paralelizar. Si detecta tareas independientes, lanza N subagents con instrucciones específicas. Cada uno trabaja de forma aislada. Cuando todos terminan, el coordinador recibe los N resultados y los sintetiza en una respuesta coherente para ti.

Cuándo usar subagents (y cuándo no)

Los subagents brillan cuando tienes tareas independientes entre sí. Estos son los escenarios ideales:

• Investigación multi-archivo: analizar 5 archivos distintos para entender una arquitectura
• Refactoring paralelo: actualizar imports en múltiples módulos que no dependen entre sí
• Testing distribuido: ejecutar tests de frontend y backend simultáneamente
• Auditoría de código: revisar seguridad, rendimiento y estilo en paralelo
• Generación de contenido: crear documentación para varias funciones al mismo tiempo
• Análisis de codebase: explorar estructura, dependencias y patrones de un proyecto nuevo

Cuándo NO usar subagents:

• Tareas secuenciales: si el paso 2 depende del resultado del paso 1, un solo agente es más eficiente
• Ediciones del mismo archivo: dos subagents editando el mismo archivo generan conflictos
• Tareas triviales: no lances subagents para algo que el coordinador puede hacer en 5 segundos
• Decisiones con contexto compartido: si la decisión requiere ver el panorama completo, el coordinador debe hacerlo él mismo

Tipos de subagents según su propósito

Aunque Claude Code no tiene "tipos" formales de subagents, en la práctica se diferencian por el tipo de tarea que realizan:

Explorer (investigador): lee archivos, busca patrones, analiza estructura. No modifica nada. Es el más seguro porque es read-only.

# El coordinador lanza un explorer:
"Lee src/api/ y documenta todos los endpoints,
 sus métodos HTTP y parámetros"

Builder (constructor): crea o modifica archivos. Implementa cambios concretos. Requiere instrucciones precisas porque opera sin ver el contexto completo.

# El coordinador lanza un builder:
"Añade validación Zod a todos los endpoints en
 src/api/routes/users.ts siguiendo el patrón de auth.ts"

Reviewer (revisor): analiza código existente buscando problemas. Devuelve hallazgos sin modificar archivos.

# El coordinador lanza un reviewer:
"Revisa src/services/payment.ts buscando:
 race conditions, error handling incompleto,
 y validación de inputs"

Planner (planificador): analiza requisitos y propone un plan de implementación. No ejecuta, solo planifica.

# El coordinador lanza un planner:
"Analiza el PRD en docs/prd-auth.md y propón
 los archivos que hay que crear/modificar,
 en qué orden, y las dependencias entre ellos"

Validator (validador): ejecuta tests, verifica tipos, comprueba linting. Confirma que los cambios son correctos.

# El coordinador lanza un validator:
"Ejecuta npm run test y npm run lint.
 Reporta solo los errores, agrupados por archivo"

La herramienta Task

Claude Code lanza subagents mediante la herramienta Task. No necesitas invocarla manualmente en la mayoría de casos: Claude decide cuándo paralelizar basándose en tu petición.

Por ejemplo, si le pides "analiza la seguridad y el rendimiento de este proyecto", Claude puede lanzar dos subagents: uno para seguridad y otro para rendimiento.

# Lo que tú escribes:
"Analiza este proyecto: revisa la seguridad, el rendimiento
y la calidad del código"

# Lo que Claude Code hace internamente:
# Task 1 → Subagent "Analizar seguridad" (busca vulnerabilidades)
# Task 2 → Subagent "Analizar rendimiento" (busca bottlenecks)
# Task 3 → Subagent "Analizar calidad" (busca code smells)
# Coordinador → Espera los 3, sintetiza en una respuesta unificada

Cada subagent trabaja de forma aislada. No comparten contexto entre sí, lo que evita interferencias y mantiene cada análisis enfocado en su dominio.

Cómo influir en la paralelización:

Puedes guiar a Claude Code para que use subagents estructurando tu prompt de forma que las tareas independientes sean evidentes:

# Prompt que favorece paralelización:
"Haz estas 3 tareas en paralelo:
1. Busca todos los TODOs en src/
2. Lista las dependencias desactualizadas
3. Cuenta las líneas de código por directorio"

# Prompt que favorece ejecución secuencial:
"Primero lee el PRD, después diseña la API basándote
en el PRD, y finalmente implementa el primer endpoint"

Ejemplos prácticos reales

Ejemplo 1: Investigar un bug en fullstack

# Prompt que activa subagents:
"Este bug afecta al checkout. Investiga en paralelo:
1. El componente React de checkout (src/components/Checkout/)
2. La API de pagos en el backend (src/api/payments/)
3. Las migraciones de base de datos recientes (supabase/migrations/)"

Claude lanzará tres subagents, cada uno buscando en su zona. En segundos tienes una visión completa del problema desde tres perspectivas sin tener que investigar secuencialmente.

Ejemplo 2: Migración de dependencias

# Actualizar múltiples archivos de configuración:
"Migra de lodash a es-toolkit en todo el proyecto.
Hay imports en src/utils/, src/hooks/ y src/components/"

Cada directorio se procesa por un subagent diferente. El resultado se consolida sin conflictos porque cada subagent trabaja en archivos distintos.

Ejemplo 3: Documentación automática

# Generar docs para múltiples módulos:
"Genera docstrings para todas las funciones públicas
en src/api/routes/, src/services/ y src/models/"

Ejemplo 4: Auditoría de seguridad multi-capa

# Revisión completa de seguridad:
"Audita la seguridad del proyecto:
1. Busca SQL injection y XSS en los endpoints
2. Revisa la configuración de CORS y headers
3. Verifica que todas las rutas protegidas tienen auth middleware
4. Comprueba que no hay secrets hardcoded en el código"

Cuatro subagents especializados, cada uno enfocado en un vector de ataque. El coordinador sintetiza los hallazgos priorizados por severidad.

Ejemplo 5: Onboarding en proyecto nuevo

# Entender un proyecto desconocido:
"Analiza este proyecto que no conozco:
1. Lee package.json y describe el stack y dependencias
2. Mapea la estructura de directorios y su propósito
3. Identifica los entry points (main, routes, pages)
4. Busca documentación existente (README, docs/, comments)"

Modos de aislamiento

Los subagents pueden operar con diferentes niveles de aislamiento según la tarea:

Aislamiento de contexto (por defecto): cada subagent tiene su propio contexto. No ve la conversación del coordinador ni la de otros subagents. Es suficiente para la mayoría de tareas de lectura y análisis.

Aislamiento de directorio: combina subagents con worktrees de git. Cada subagent trabaja en un directorio de trabajo diferente del repositorio. Esto permite que múltiples subagents modifiquen archivos sin conflictos de git.

# Patrón: subagent + worktree para ramas paralelas
"Crea una feature branch para auth y otra para payments.
En paralelo:
- Branch feat/auth: implementa login con JWT
- Branch feat/payments: integra Stripe checkout"

Aislamiento de permisos: puedes restringir lo que un subagent puede hacer. Por ejemplo, un subagent de análisis puede tener acceso de solo lectura, mientras que uno de implementación tiene acceso de escritura.

Patrones de ejecución paralela

Fan-out / Fan-in

El patrón más común con subagents. El coordinador "abanica" (fan-out) la tarea en N subtareas independientes, espera a que todas terminen, y luego consolida (fan-in) los resultados en una respuesta unificada.

# Fan-out: 1 tarea → N subagents
Coordinador → [Subagent 1, Subagent 2, Subagent 3]

# Fan-in: N resultados → 1 respuesta
[Resultado 1, Resultado 2, Resultado 3] → Coordinador → Tu respuesta

Pipeline con etapas paralelas

Combina secuencialidad con paralelismo. Primero, una fase secuencial (planificación). Luego, una fase paralela (ejecución). Después, otra fase secuencial (validación).

# Fase 1 (secuencial): Coordinador analiza requisitos
# Fase 2 (paralela):   3 subagents implementan en paralelo
# Fase 3 (secuencial): Coordinador válida coherencia

Subagent como validador post-cambio

Después de que el agente principal modifica código, lanza subagents para validar: uno ejecuta tests, otro verifica tipos, otro revisa linting. Si alguno falla, el agente principal corrige y re-válida.

Map-Reduce sobre archivos

Para operaciones que afectan a muchos archivos (ej: añadir header de licencia, migrar imports, actualizar APIs deprecated):

# Map: un subagent por grupo de archivos
Subagent 1 → procesa src/api/*.ts
Subagent 2 → procesa src/services/*.ts
Subagent 3 → procesa src/components/*.tsx

# Reduce: coordinador verifica coherencia global

Optimización de costes con subagents

Los subagents consumen tokens. Cada uno tiene su propia invocación al modelo. Estas estrategias minimizan el coste:

1. Instrucciones concisas: cada token en la instrucción del subagent se paga. "Busca vulnerabilidades SQL injection en src/api/" es mejor que una explicación de tres párrafos sobre qué es SQL injection.

2. Limita el scope: "Revisa src/api/routes/users.ts" consume menos que "Revisa todo src/". Un subagent con scope acotado es más barato y más preciso.

3. Usa subagents de lectura antes que de escritura: un subagent que lee y reporta es más barato que uno que lee, decide y modifica. Haz la fase de investigación con subagents baratos, y la implementación con el coordinador que ya tiene el contexto completo.

4. No paralelices tareas triviales: si una tarea toma 5 segundos al coordinador, lanzar un subagent para ella es overhead innecesario. El coste de setup del subagent (instrucción + contexto mínimo) no compensa.

5. Agrupa tareas relacionadas: en vez de 10 subagents para 10 archivos del mismo directorio, usa 3 subagents para 3 grupos de archivos. Menos overhead de coordinación.

Limitaciones y buenas prácticas

• Contexto reducido: los subagents no ven la conversación completa. Dale instrucciones claras y auto-contenidas. Si necesitan saber algo del contexto, inclúyelo explícitamente en la instrucción.
• Sin comunicación entre subagents: no pueden hablar entre sí. Solo reportan al coordinador. Si el resultado de un subagent afecta a otro, necesitas un patrón secuencial, no paralelo.
• Conflictos de archivos: si dos subagents modifican el mismo archivo, habrá conflicto. Diseña tareas que operen en archivos distintos, o usa worktrees para aislamiento git.
• Coste de tokens: cada subagent consume contexto independiente. No lances 10 subagents para una tarea trivial. El sweet spot es 2-5 subagents para tareas sustanciales.
• Verificación obligatoria: siempre revisa el resultado consolidado. El coordinador puede perder matices al sintetizar N resultados en una respuesta. Pide detalles si algo parece superficial.
• Timeout: subagents con tareas muy complejas pueden tardar. Si un subagent se atasca, el coordinador espera. Diseña tareas acotadas con resultados predecibles.

Preguntas frecuentes

Puedo forzar a Claude Code a usar subagents?

Sí. Estructura tu prompt con tareas numeradas y añade "en paralelo" o "simultáneamente". Claude Code interpreta esto como señal para usar Task tool. También puedes decir explícitamente "usa subagents para esto".

Qué pasa si un subagent falla?

El coordinador recibe el error como resultado. Puede decidir reintentar con instrucciones diferentes, hacer la tarea él mismo, o reportarte el fallo. No se queda bloqueado esperando indefinidamente.

Los subagents pueden usar herramientas MCP?

Sí. Los subagents tienen acceso a las mismas herramientas que el agente principal: lectura/escritura de archivos, ejecución de comandos, búsqueda, y servidores MCP configurados.

Cuántos subagents puedo lanzar a la vez?

No hay un límite duro oficial, pero el límite práctico es 2-5 para la mayoría de tareas. Más de 5 subagents simultáneos generan overhead de coordinación y la síntesis de resultados pierde calidad.

Los subagents ven mi CLAUDE.md?

Sí. Los subagents cargan el mismo CLAUDE.md que el coordinador. Heredan las reglas del proyecto. Esto garantiza que siguen las mismas convenciones aunque operen de forma independiente.

Siguiente paso

Los subagents multiplican la capacidad de Claude Code para tareas paralelas. Combínalos con worktrees para aislamiento git, con skills para workflows repetibles que usen subagents internamente, y con servidores MCP para ampliar las herramientas disponibles a cada subagent.

Empieza con un caso simple: la próxima vez que necesites analizar múltiples archivos, pide a Claude Code que lo haga en paralelo. Verás la diferencia en velocidad de respuesta.