# Subagentes y trabajo en paralelo en Claude Code: ejecución simultánea de tareas

> Guía completa para la paralelización de tareas en Claude Code: arquitectura de subagentes, contexto compartido y aislado, patrones Fan-Out y Swarm, ejecución CLI headless con -p y optimización de tokens.

## 1. Qué son los subagentes en Claude Code: de la ejecución secuencial al pensamiento paralelo

Una sesión estándar de **Claude Code** opera de forma estrictamente secuencial (mediante un bucle de eventos de un solo hilo). El usuario envía una solicitud, el agente recopila contexto, realiza búsquedas, edita archivos, ejecuta linters o pruebas, y solo tras completar toda la secuencia pasa a la siguiente tarea. A medida que un proyecto crece y surgen múltiples tareas independientes, este enfoque lineal genera demoras innecesarias y satura rápidamente la ventana de contexto.

Para superar este cuello de botella, la arquitectura de Claude Code integra el concepto de **subagentes**: instancias de ejecución aisladas y autónomas del modelo a las que se delegan partes independientes del objetivo general.

```mermaid
flowchart TD
    subgraph Sequential ["Modo Secuencial (Sesión Única)"]
        S1["Tarea 1"] --> S2["Tarea 2"] --> S3["Tarea 3"] --> S4["Resultado Final"]
    end

    subgraph Parallel ["Modo Paralelo (Orquestación de Subagentes)"]
        P_Parent["Sesión Principal de Claude Code"] --> P1["Subagente 1: Auth"]
        P_Parent --> P2["Subagente 2: Validation"]
        P_Parent --> P3["Subagente 3: Formatting"]
        P1 --> P_Join{"Agregación de Resultados"}
        P2 --> P_Join
        P3 --> P_Join
        P_Join --> P_Done["Pull Request / Informe Final"]
    end
```

### Características fundamentales de un subagente autónomo

- **Ventana de contexto propia y aislada:** El subagente no carga con el extenso historial de la conversación principal y se enfoca exclusivamente en la instrucción asignada.
- **Acceso compartido al sistema de archivos:** Los subagentes leen la estructura del repositorio, las configuraciones del proyecto y el código fuente con los mismos permisos que el proceso principal.
- **Ejecución asíncrona:** Múltiples subagentes operan simultáneamente, reduciendo el tiempo total de desarrollo en proporción al número de trabajadores paralelos.
- **Agregación automatizada:** Al concluir su tarea, cada subagente genera un resumen estructurado, devuelve sus hallazgos a la sesión principal y libera sus recursos.

> [!NOTE]
> El modelo mental más claro para comprender los subagentes es la gestión de ingeniería moderna. En lugar de que un ingeniero principal redacte documentación para cinco microservicios de manera secuencial, define cinco tareas independientes, las asigna a desarrolladores en paralelo y revisa únicamente el resultado final de cada uno.

---

## 2. Criterios de paralelización: cuándo bifurcar tareas y cuándo trabajar en secuencia

La paralelización no es una solución universal aplicable a cualquier escenario. Su efectividad depende estrictamente de la independencia mutua de las tareas. Intentar ejecutar simultáneamente etapas acopladas genera condiciones de carrera (race conditions) y colisiones lógicas.

| Escenario de desarrollo | Modo recomendado | Justificación arquitectónica |
| :--- | :---: | :--- |
| **Generación de pruebas unitarias para utilidades distintas** | Paralelo | Los módulos no dependen entre sí; archivos autocontenidos |
| **Auditoría multidimensional (Seguridad, SEO, Accesibilidad)** | Paralelo | Cada agente analiza el código desde un ángulo ortogonal en modo lectura |
| **Diseño de esquema de base de datos y creación de migraciones** | Secuencial | Las migraciones no pueden redactarse hasta fijar los modelos de datos |
| **Edición simultánea de un archivo de configuración compartido** | Secuencial | Las escrituras concurrentes provocan sobreescritura de datos |
| **Refactorización por lotes de componentes desacoplados** | Paralelo | Cada componente UI reside en un archivo aislado |

### Cuándo se debe evitar la paralelización

1. **Dependencias secuenciales de datos:** Cuando el paso B consume estrictamente la salida del paso A (por ejemplo: auditar un esquema heredado, diseñar la nueva estructura y solo entonces generar la migración de Prisma).
2. **Archivos compartidos de escritura:** Si el Agente 1 y el Agente 2 intentan modificar simultáneamente `app.ts` o `package.json`, los cambios de uno de ellos se sobrescribirán o corromperán.
3. **Tareas exploratorias con retroalimentación humana continua:** Cuando los requisitos son ambiguos y el desarrollador necesita orientar al modelo mediante preguntas y respuestas iterativas, el trabajo debe permanecer en una sesión interactiva única.

> [!WARNING]
> La regla de oro de la paralelización: antes de lanzar un grupo de subagentes, responda a esta pregunta: **«¿Puede cada agente completar su objetivo de principio a fin sin esperar respuestas intermedias de otros?»**. Si la respuesta es «no», trabaje estrictamente en modo secuencial.

---

## 3. Arquitectura y mecánica de despacho de subagentes mediante Task Tool

Internamente, Claude Code orquesta los subagentes a través de su herramienta de sistema **Task tool**. Cuando el modelo en la sesión principal determina que una solicitud puede dividirse en unidades de trabajo independientes, inicia automáticamente procesos de trabajo en segundo plano.

Los desarrolladores rara vez necesitan invocar manualmente los esquemas JSON de Task tool: basta con definir límites de tarea claros en lenguaje natural para que Claude Code gestione el despacho y la consolidación de forma autónoma.

![Arquitectura de despacho de subagentes en Claude Code y agregación de resultados a la sesión principal](/api/guides-media/ai_agents/claude-code-subagents-and-parallel-work/images/claude-code-subagents-and-parallel-work-step-01.webp)

### Ciclo de vida de la ejecución paralela

1. **Despacho de la tarea:** La sesión principal recibe un prompt compuesto (por ejemplo, escribir pruebas para cinco módulos utilitarios: `auth.ts`, `validation.ts`, `formatting.ts`, `api-client.ts`, `cache.ts`).
2. **Inicialización de contextos hijos:** Se crean subagentes independientes, asignando a cada uno su alcance específico y la ruta del archivo objetivo.
3. **Ejecución autónoma:** Cada agente analiza en paralelo el código fuente de su módulo, examina los tipos, genera la suite de pruebas y valida su ejecución.
4. **Agregación de resultados:** La sesión principal espera la finalización de todos los procesos, recopila los estados de ejecución y presenta al desarrollador un informe consolidado.

---

## 4. Contexto compartido vs. aislado: qué pueden ver los subagentes

Un error frecuente es asumir que los subagentes poseen telepatía o conservan memoria de lo conversado en el paso 50 de la sesión principal. En la práctica, Claude Code mantiene una estricta separación de memoria.

![Contexto compartido y aislado de subagentes: qué recursos están disponibles para todos y qué permanece privado](/api/guides-media/ai_agents/claude-code-subagents-and-parallel-work/images/claude-code-subagents-and-parallel-work-extra-02.webp)

| Recurso o estado del sistema | ¿Compartido entre todos los agentes? | Características técnicas de acceso |
| :--- | :---: | :--- |
| **Archivos del proyecto en disco** | **Sí** | Todos los agentes tienen acceso de lectura y escritura en el repositorio |
| **Instrucciones de CLAUDE.md** | **Sí** | Cada subagente hereda automáticamente las reglas globales del proyecto |
| **Historial de la conversación principal** | **No** | Contexto aislado; cada agente solo ve su prompt directo asignado |
| **Modificaciones de archivos en vivo** | **Requiere precaución** | No existe bloqueo automático de archivos; riesgo de colisión al escribir |

### Principio de propiedad única de escritura (Single Writer Principle)

Para evitar daños en el código durante la ejecución simultánea, aplique de forma rigurosa el principio de **un único escritor por archivo**:

```text
Distribución correcta (sin conflictos):
Subagente 1 ──► src/utils/auth.test.ts        (crea un nuevo archivo)
Subagente 2 ──► src/utils/validation.test.ts  (crea un nuevo archivo)
Subagente 3 ──► src/utils/formatting.test.ts  (crea un nuevo archivo)

Distribución no permitida (condición de carrera):
Subagente 1 ──► src/index.ts  (modifica líneas de exportación)
Subagente 2 ──► src/index.ts  (modifica líneas de exportación)
Subagente 3 ──► src/index.ts  (modifica líneas de exportación)
```

> [!IMPORTANT]
> Si varios subagentes generan módulos que deben registrarse en un archivo central (`src/index.ts` o `src/routes.ts`), **no delegue** esa actualización a los subagentes. Deje que cada subagente cree su archivo aislado y permita que la sesión principal agregue las exportaciones tras recopilar todos los resultados.

---

## 5. Patrones de prompts para invocar agentes en paralelo

Aunque Claude Code incorpora mecanismos para detectar oportunidades de concurrencia, una instrucción explícita elimina cualquier ambigüedad y optimiza los tiempos de planificación.

### Plantillas probadas de prompts

:::tabs
@tab Partición básica
```markdown
Ejecuta las siguientes tres tareas en paralelo mediante subagentes dedicados:

1. Implementa validación de entradas en el formulario de registro (src/components/RegisterForm.tsx).
2. Construye un componente de skeleton de carga para el panel (src/components/DashboardSkeleton.tsx).
3. Añade soporte de paginación en el hook de usuarios (src/hooks/useUsers.ts).

Asegúrate de que cada agente trabaje únicamente en su archivo asignado sin modificar configuraciones compartidas.
```
@tab Investigación Fan-Out
```markdown
Investiga los siguientes temas en paralelo utilizando subagentes:

- Agente 1: Consulta la documentación oficial de Stripe API sobre eventos webhook de suscripciones.
- Agente 2: Audita nuestra implementación actual en src/services/billing.ts en busca de vulnerabilidades.
- Agente 3: Diseña las interfaces TypeScript para los nuevos objetos DTO en src/types/stripe.ts.

Al concluir, consolida los hallazgos en un plan de refactorización unificado en la sesión principal.
```
@tab Auditoría por lotes
```markdown
Realiza una auditoría paralela del repositorio estructurada en cuatro vectores:

- Vector A (Seguridad): Escaneo de secretos en el historial de git y verificación de consultas a la base de datos.
- Vector B (Rendimiento): Detección de patrones N+1 en controladores y análisis del peso de bundles en el cliente.
- Vector C (Tipado estricto): Inspección de TypeScript estricto y eliminación de usos inseguros de any.
- Vector D (Accesibilidad): Comprobación de atributos aria-label, landmarks semánticos y contraste de color.
```
:::

---

## 6. Cuatro esquemas clave de trabajo en paralelo: patrones listos para usar

La experiencia práctica en automatización con Claude Code ha permitido consolidar cuatro patrones de orquestación altamente productivos.

```mermaid
flowchart LR
    subgraph P1 ["1. Research Fan-Out"]
        RF_Q["Decisión Arquitectónica"] --> RF1["PostgreSQL"]
        RF_Q --> RF2["MongoDB"]
        RF_Q --> RF3["SQLite"]
        RF1 & RF2 & RF3 --> RF_M["Matriz Comparativa"]
    end

    subgraph P2 ["2. Audit Swarm"]
        AS_Code["Repositorio"] --> AS1["Security"]
        AS_Code --> AS2["Performance"]
        AS_Code --> AS3["A11y"]
        AS_Code --> AS4["Code Quality"]
        AS1 & AS2 & AS3 & AS4 --> AS_R["Informe de Auditoría"]
    end
```

### Research Fan-Out (Investigación paralela)

Se utiliza cuando es necesario evaluar simultáneamente diversas bibliotecas, tecnologías o enfoques arquitectónicos antes de tomar una decisión técnica. Cada agente investiga una opción bajo criterios normalizados (ventajas, desventajas, tamaño de bundle, licencias) y la sesión principal sintetiza una matriz comparativa.

### Audit Swarm (Auditoría multidisciplinar)

Uno de los patrones más eficientes en términos de ahorro de tiempo. En lugar de que un único agente revise el proyecto cuatro veces consecutivas, cuatro agentes especializados analizan el repositorio al mismo tiempo en modo lectura (read-only), eliminando cualquier riesgo de colisión de archivos.

### Batch Processor (Refactorización por lotes)

Idóneo para migraciones mecánicas a gran escala en las que se aplica una transformación idéntica sobre múltiples archivos independientes:
- Migración de componentes de clase heredados de React a functional hooks en `src/components/`.
- Actualización de suites de pruebas de Jest a Vitest.
- Reestructuración de rutas de importaciones obsoletas en un monorepositorio.

### Feature Sprint (Desarrollo paralelo de módulos)

Desarrollo simultáneo de módulos de interfaz de usuario o endpoints de API independientes:
- Agente 1 implementa el interruptor de modo oscuro (`ThemeToggle.tsx` + contexto).
- Agente 2 desarrolla el buscador global (`SearchBar.tsx` + hook de búsqueda).
- Agente 3 crea el menú desplegable de notificaciones (`NotificationsDropdown.tsx`).

---

## 7. Ejecución paralela desde CLI: Modo Headless y la bandera -p

Más allá de la sesión interactiva, Claude Code ofrece una potente herramienta de automatización del sistema: el **modo no interactivo (headless)** mediante la bandera `-p` (`--print`). En este modo, el agente recibe la instrucción como argumento de consola, ejecuta la tarea de forma autónoma y devuelve la salida directamente en la terminal.

Esto permite aprovechar las capacidades de gestión de procesos en segundo plano de entornos Unix (`&`) y el comando de sincronización `wait`:

```bash
# Lanzamiento simultáneo de tres procesos de Claude Code en bash/zsh
claude -p "Write unit tests for src/utils/auth.ts using Vitest" &
PID_AUTH=$!

claude -p "Write unit tests for src/utils/validation.ts using Vitest" &
PID_VAL=$!

claude -p "Write unit tests for src/utils/formatting.ts using Vitest" &
PID_FMT=$!

# Espera de finalización de todos los procesos en segundo plano
echo "Subagentes lanzados con PID: $PID_AUTH, $PID_VAL, $PID_FMT. Esperando..."
wait $PID_AUTH $PID_VAL $PID_FMT

echo "¡Pruebas generadas correctamente! Iniciando validación..."
npm test
```

### Ventajas de la paralelización vía CLI

- **Automatización sin intervención humana:** Óptimo para flujos nocturnos de CI/CD, generación de documentación o validaciones previas al commit.
- **Aislamiento a nivel de procesos:** Cada proceso de `claude` se ejecuta en un espacio de memoria independiente del sistema operativo.
- **Registro de logs individualizado:** La salida de cada trabajador se redirige fácilmente a un archivo específico: `claude -p "..." > logs/auth.log 2>&1 &`.

> [!TIP]
> En la terminal, el operador `&` envía la ejecución al fondo de forma instantánea. El comando integrado `wait` detiene el script hasta que todos los identificadores de proceso (PID) indicados terminen su ejecución con su respectivo código de salida.

---

## 8. Economía de tokens, límites de API y optimización de costes

La paralelización reduce drásticamente el tiempo de espera del equipo, pero requiere una gestión presupuestaria consciente. Dado que cada subagente inicializa su propia ventana de contexto, ejecutar $N$ agentes en paralelo multiplica el consumo de tokens de contexto base aproximadamente por $N$.

```text
Sesión Secuencial (1 Ventana de Contexto):
[Prompt de Sistema] + [Tarea 1] ──► [Tarea 2] ──► [Tarea 3]
Consumo total de tokens: Contexto Base + ΔT1 + ΔT2 + ΔT3

Subagentes Paralelos (3 Ventanas Independientes):
Subagente 1: [Contexto Base + Tarea 1]
Subagente 2: [Contexto Base + Tarea 2]
Subagente 3: [Contexto Base + Tarea 3]
Consumo total de tokens: (3 × Contexto Base) + ΔT1 + ΔT2 + ΔT3
```

### Cuatro reglas para optimizar el presupuesto de tokens

1. **Delimitación precisa de tareas:** Evite instrucciones genéricas como «Revisa las pruebas del proyecto». Defina alcances concretos: «Escribe 3 pruebas unitarias para parseJwt en src/utils/auth.ts».
2. **Exclusión de archivos pesados:** Configure `.claudeignore` para evitar que los agentes carguen artefactos de compilación, volcados de base de datos o tipos generados.
3. **Uso de `-p` para tareas deterministas:** La ejecución no interactiva previene la acumulación de historial conversacional y devuelve resultados directos.
4. **Agrupación de ajustes triviales:** Iniciar un subagente para corregir un único estilo CSS resulta ineficiente; el coste de inicialización del contexto superará el beneficio de la tarea.

---

## 9. Taller práctico: implementación paso a paso desde pruebas hasta Audit Swarm

Aplique estos principios en un taller práctico con ejecución paso a paso.

### Paso 1. Selección de módulos aislados y preparación

Identifique en su repositorio tres archivos utilitarios sin dependencias mutuas ni importaciones cruzadas:
- `src/utils/auth.ts`
- `src/utils/validation.ts`
- `src/utils/formatting.ts`

Verifique que los archivos de prueba correspondientes no existan o requieran cobertura completa.

### Paso 2. Redacción y envío del prompt paralelo

Inicie una sesión de Claude Code en su terminal y envíe la siguiente instrucción estructurada:

```markdown
Genera pruebas unitarias para los siguientes tres archivos en paralelo mediante subagentes:

1. src/utils/auth.ts -> Guarda las pruebas en src/utils/auth.test.ts
2. src/utils/validation.ts -> Guarda las pruebas en src/utils/validation.test.ts
3. src/utils/formatting.ts -> Guarda las pruebas en src/utils/formatting.test.ts

Requisitos técnicos:
- Utiliza Vitest y comprueba casos límite (null, undefined, cadenas vacías).
- No modifiques los archivos originales de utilidades.
```

### Paso 3. Supervisión y verificación de pruebas

Observe la consola mientras Claude Code inicializa las tareas secundarias, procesa los módulos en paralelo y notifica las finalizaciones.

Ejecute la verificación en su terminal:

```bash
npm run test:run
```

Las tres nuevas suites de pruebas deben ejecutarse y aprobarse sin conflictos de código.

### Paso 4. Ejecución de un Audit Swarm para análisis de calidad

Ahora evalúe el patrón analítico Audit Swarm enviando la siguiente solicitud:

```markdown
Ejecuta una auditoría integral del código a través de cuatro subagentes paralelos:

- Agente de Seguridad: Detección de XSS, CSRF, paquetes vulnerables y secretos en el código.
- Agente de Rendimiento: Análisis del tamaño del bundle, re-renders innecesarios e importaciones pesadas.
- Agente de Accesibilidad: Verificación de etiquetas semánticas HTML, trampas de foco y parámetros ARIA.
- Agente de Calidad de Código: Detección de código muerto, duplicaciones y usos indebidos de any.

Presenta un informe consolidado priorizado por nivel de impacto (Alto / Medio / Bajo).
```

---

## 10. Cuaderno de referencia y lista de verificación para paralelización

Consulte esta lista de comprobación antes de iniciar flujos paralelos de agentes en Claude Code.

### Lista de verificación previa al lanzamiento

- [ ] **Independencia de tareas:** Ninguna tarea requiere artefactos generados por otros subagentes paralelos.
- [ ] **Aislamiento de escritura en archivos:** Cada agente escribe exclusivamente en su propio archivo; no hay concurrencia sobre configuraciones compartidas.
- [ ] **Alcance delimitado:** Se especifican con claridad las rutas de archivos, tecnologías y criterios de éxito.
- [ ] **Viabilidad económica:** La reducción del tiempo de espera justifica la duplicación del contexto base.
- [ ] **Limpieza de contexto:** Los directorios pesados están filtrados mediante `.claudeignore`.

### Matriz de selección de herramientas

| Tarea u objetivo | Enfoque recomendado | Interfaz de ejecución |
| :--- | :--- | :--- |
| **Generación de pruebas en 5+ módulos** | Claude Code interactivo o CLI `-p` | `claude -p "..." &` |
| **Auditoría multifacética del repositorio** | Audit Swarm en sesión interactiva | Prompt con 4 subagentes especializados |
| **Comparación de bibliotecas o tecnologías** | Research Fan-Out | Tabla consolidada de toma de decisiones |
| **Refactorización profunda del núcleo del sistema** | Sesión única secuencial | Sesión interactiva con revisión paso a paso |