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.

Nota

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

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).
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.
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.

Atención

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 Збільшити

Arquitectura de despacho de subagentes en Claude Code y agregación de resultados a la sesión principal

Ciclo de vida de la ejecución paralela

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).
Inicialización de contextos hijos: Se crean subagentes independientes, asignando a cada uno su alcance específico y la ruta del archivo objetivo.
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.
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 Збільшити

Contexto compartido y aislado de subagentes: qué recursos están disponibles para todos y qué permanece privado

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)

Importante

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

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 &.

Consejo

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

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».
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.
Uso de -p para tareas deterministas: La ejecución no interactiva previene la acumulación de historial conversacional y devuelve resultados directos.
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