Módulo 3: Parallel Sub-Agent Delegation

1. Introducción al Módulo — Cuando la Secuencia No Escala

Descripción

Tus subagents del Módulo 1 tienen roles definidos. Con el Módulo 2, tienen memoria persistente. Trabajan bien — el reviewer analiza, el implementer corrige, el tester verifica. Pero trabajan en fila india. Uno espera a que el otro termine. En un pipeline de 3 agentes esto es tolerable: 2 minutos + 3 minutos + 1 minuto = 6 minutos total. Pero ¿qué pasa cuando necesitas 4 agentes refactorizando módulos independientes? 4 × 3 minutos = 12 minutos. Y si fueran 8 módulos, 24 minutos esperando que cada agente termine antes de iniciar el siguiente.

La delegación paralela rompe esa barrera. Si los 4 módulos son independientes, los 4 agentes pueden trabajar simultáneamente. 4 × 3 minutos en paralelo ≈ 3.5 minutos. No es magia — es concurrencia. La misma lógica que hace que un equipo de 4 desarrolladores termine un sprint más rápido que uno solo, aplicada a subagents de Claude Code.

Pero el paralelismo introduce complejidad que la ejecución secuencial no tiene. ¿Qué pasa si dos agentes modifican archivos relacionados? ¿Qué pasa si un agente falla mientras los otros 3 continúan? ¿Cómo se combinan los resultados de 4 ejecuciones paralelas? ¿Cómo decides qué tareas son realmente independientes? Estas preguntas definen la diferencia entre "lanzar agentes al mismo tiempo" y "orquestar delegación paralela."

Este módulo cierra la Phase 1 porque la delegación paralela es la síntesis de todo lo anterior: subagents bien definidos (Módulo 1) + memoria compartida para consistencia (Módulo 2) + la capacidad de coordinar trabajo simultáneo (este módulo). Al terminar, tendrás la base completa para Agent Teams en Phase 2.

¿Dónde Estamos en la Guía?

Contexto en el Path

Phase 1: Subagents Avanzados
├── Módulo 1: Custom Subagents                    ← completado
├── Módulo 2: Agent Memory y Scopes               ← completado
└── Módulo 3: Parallel Sub-Agent Delegation       ← ESTÁS AQUÍ

Phase 2: Agent Teams y Plugins (Módulos 4-6)
Phase 3: Orquestación (Módulos 7-8)

En el Módulo 1 creaste subagents con identidad propia — roles, restricciones, system prompts. En el Módulo 2 les diste memoria persistente — recuerdan patrones, convenciones, y decisiones entre sesiones. Ahora los pones a trabajar al mismo tiempo. Sin los dos módulos anteriores, la delegación paralela sería lanzar agentes genéricos sin contexto compartido — caos coordinado.

¿Hacia dónde vamos?

Este módulo es el cierre de Phase 1. La progresión completa:

Módulo 1: Crear agentes con identidad ← completado
Módulo 2: Dar memoria a esos agentes ← completado
Módulo 3: Ponerlos a trabajar en paralelo ← AQUÍ — la síntesis de Phase 1
Módulo 4: Formalizar la coordinación con Agent Teams — lo que haces manualmente aquí, Agent Teams lo automatizan
Módulo 5: Empaquetar en plugins — distribuir configuraciones de subagents
Módulo 6: Automatizar con hooks y SDK — control programático
Módulo 7: Operar remotamente — remote control y CLAUDE.md de equipo
Módulo 8: Integrar todo en un sistema multi-agente completo

La delegación paralela que dominas aquí es lo que Agent Teams formalizan en el Módulo 4. Piénsalo así: este módulo te enseña a coordinar manualmente; Agent Teams te da la infraestructura para que la coordinación sea automática. Necesitas entender el "cómo funciona por debajo" antes de usar la abstracción.

El Problema: La Ejecución Secuencial No Escala

Un escenario real

Tienes un proyecto con 4 módulos independientes: auth, products, orders, notifications. Cada uno necesita un refactor — actualizar type hints, mejorar error handling, y standardizar los response models. Los 4 módulos no dependen entre sí para el refactor — cada uno es autocontenido.

Con ejecución secuencial:

Refactor auth          → 3 min
  ↓ (espera)
Refactor products      → 4 min
  ↓ (espera)
Refactor orders        → 3 min
  ↓ (espera)
Refactor notifications → 2 min

Total: 12 minutos (wall-clock time)

Cada agente espera a que el anterior termine. El agente de notifications tiene 10 minutos de tiempo muerto antes de empezar. Si fueras un tech lead con 4 desarrolladores, nunca les dirías "espera a que María termine el módulo auth antes de empezar con products." Les dirías "cada uno agarre un módulo y al final hacemos merge."

Con delegación paralela:

Refactor auth          ──┐
Refactor products      ──┤ → ~4 min (el más lento define el total)
Refactor orders        ──┤
Refactor notifications ──┘
         ↓
    Merge coordinator  → 1 min

Total: ~5 minutos (wall-clock time)

De 12 minutos a 5. Una reducción del 58%. Y el beneficio crece con más tareas independientes.

Cuándo la secuencia está bien

No todo se beneficia del paralelismo. Si las tareas tienen dependencias reales, paralelizarlas es un error:

❌ No paralelizar:
implementer → tester    (el tester NECESITA que el implementer termine primero)
schema → migration      (la migration NECESITA el schema actualizado)
auth → protected routes (las rutas protegidas NECESITAN el sistema de auth)

✅ Sí paralelizar:
refactor auth ║ refactor products    (módulos independientes)
review backend ║ review frontend     (áreas del código sin dependencia)
update docs ║ update tests           (archivos diferentes, sin conflicto)

La regla: si la tarea B necesita el resultado de la tarea A para empezar, no puedes paralelizarlas. Si ambas pueden empezar ahora mismo con la información que ya existe, son candidatas a paralelización.

El costo de paralelizar mal

Paralelizar tareas con dependencias ocultas produce resultados silenciosamente incorrectos:

Dos agentes editan el mismo archivo → uno sobreescribe los cambios del otro
Un agente asume un schema que otro agente está cambiando → inconsistencia
Un agente genera tests para una interfaz que otro agente está refactorizando → tests inválidos

Estos problemas no generan errores inmediatos — los cambios se aplican, los tests tal vez pasan, pero el resultado tiene conflictos lógicos que solo se descubren después. Por eso la identificación correcta de dependencias es el skill más importante de este módulo.

Objetivo del Módulo

Al terminar este módulo serás capaz de:

✅ Identificar tareas independientes que se benefician de delegación paralela vs tareas con dependencias que deben ser secuenciales
✅ Lanzar múltiples subagents en paralelo usando prompts de delegación y el campo background: true en frontmatter
✅ Usar isolation: worktree para que agentes paralelos editen archivos sin conflictos via git worktrees
✅ Diseñar un dependency graph mental para determinar qué tareas van en paralelo y cuáles esperan
✅ Coordinar el merge de resultados cuando múltiples agentes completan al mismo tiempo
✅ Implementar timeout con maxTurns y error handling con estrategias de fallback
✅ Orquestar un refactor paralelo de 4 módulos con un merge coordinator al final

Objetivo profesional

Cuando tengas un refactor que toca 4 módulos independientes, no pasarás 15 minutos esperando que cada agente termine en secuencia. Lanzarás 4 agentes en paralelo, cada uno en su worktree aislado, y un coordinador mergeará los resultados. Tu equipo verá un PR limpio con cambios en 4 módulos — completado en una fracción del tiempo secuencial.

Roadmap del Módulo

Mapa de cápsulas

#	Cápsula	Qué aprenderás	Tipo
01	Introducción (esta)	Cuándo la secuencia no escala, el caso para paralelismo, dependency graphs	Intro
02	Delegación Paralela: Syntax y Patterns	Cómo Claude Code ejecuta subagents en paralelo, `background: true`, Ctrl+B, worktrees, límites	Técnica
03	Dependency Resolution y Merge	Identificar dependencias, coordinar resultados, git worktrees para merge limpio, conflictos	Técnica
04	Timeout y Error Handling	`maxTurns`, manejo de fallos, permissions en background, fallback strategies, debugging	Técnica
05	Proyecto: Refactor Paralelo de 4 Módulos	4 subagents en paralelo + merge coordinator, paso a paso, con errores reales	Proyecto

Flujo de aprendizaje

Primero entenderás cómo lanzar subagents en paralelo — la sintaxis, los campos de frontmatter, y los patrones de prompting que activan la ejecución concurrente (cápsula 02). Luego aprenderás cómo coordinar resultados — qué pasa cuando 4 agentes terminan en momentos diferentes y cómo se resuelven conflictos cuando dos tocan archivos relacionados (cápsula 03). Después verás qué pasa cuando algo falla — timeout, errores de permisos en background, y estrategias de fallback (cápsula 04). Finalmente, construirás un refactor paralelo real de 4 módulos con aislamiento via worktrees y un merge coordinator (cápsula 05).

La progresión es: lanzar en paralelo → coordinar resultados → manejar errores → construir sistema completo.

Cada cápsula construye sobre la anterior. No saltes a la 03 sin entender el lanzamiento paralelo de la 02 — la coordinación asume que ya sabes cómo los agentes se ejecutan concurrentemente.

Duración estimada del módulo: 1-1.25 horas.

Conexión con el Proyecto

Mini-proyecto de este módulo: Refactor Paralelo de 4 Módulos

En la cápsula 05 construirás un sistema de refactorización paralela:

4 subagents workers — Cada uno refactoriza un módulo independiente (auth, products, orders, notifications). Cada uno opera en un git worktree aislado para evitar conflictos de archivos.
1 subagent coordinator — Espera a que los 4 workers terminen, revisa los cambios de cada uno, resuelve cualquier inconsistencia, y produce un reporte consolidado.

Tu prompt:
"Refactoriza los 4 módulos en paralelo y consolida los resultados"

↓

worker-auth          ──┐
worker-products      ──┤  (paralelo, cada uno en su worktree)
worker-orders        ──┤
worker-notifications ──┘
         ↓
merge-coordinator    → Reporte consolidado + PR-ready changes

Conexión con el proyecto final (Módulo 8)

El sistema multi-agente del Módulo 8 opera con delegación paralela como comportamiento por defecto. El frontend agent y el backend agent trabajan en paralelo. El tester espera a ambos (dependencia). El documentador trabaja en paralelo con el tester (independiente). Sin dominar la delegación paralela, el proyecto final sería un sistema secuencial disfrazado — lento y subutilizado.

Prerequisitos

Conocimientos necesarios

✅ Módulo 1 completado — Sabes crear subagents custom con frontmatter YAML y system prompts
✅ Módulo 2 completado — Tus subagents tienen memoria persistente configurada
✅ Git intermedio — Entiendes branches, merge, y estás familiarizado con el concepto de worktrees
✅ Concurrencia básica — Entiendes la diferencia entre secuencial y paralelo (no necesitas threading o async)

No necesitas

❌ Experiencia con Agent Teams — se cubre en el Módulo 4
❌ Conocimiento de git worktrees — se explica en este módulo
❌ Experiencia con sistemas distribuidos — la concurrencia aquí es coordinada por Claude Code
❌ Scripts de automatización — todo se configura con subagent files y prompts

Setup para el Módulo

Lo que necesitas tener listo

1. Un proyecto con 4+ módulos en src/:

Necesitas un proyecto con múltiples módulos independientes. No necesitan ser exactamente 4, pero al menos 2 para que la paralelización tenga sentido. La estructura ideal es:

your-project/
├── src/
│   ├── auth/           ← módulo 1
│   ├── products/       ← módulo 2
│   ├── orders/         ← módulo 3
│   └── notifications/  ← módulo 4
├── tests/
├── CLAUDE.md
└── ...

Si no tienes un proyecto con esta estructura, puedes adaptar los ejercicios a los módulos que tengas. Lo importante es que haya código en directorios separados que puedas refactorizar en paralelo.

2. Subagents del Módulo 1 configurados:

Los subagent files del Módulo 1 (code-reviewer.md, code-implementer.md, code-tester.md) deben existir en .claude/agents/. No los usaremos directamente, pero los workers de este módulo siguen los mismos patrones de diseño.

ls .claude/agents/

3. Memoria del Módulo 2 configurada:

Si tus subagents tienen memory: project, la memoria compartida ayuda a los workers paralelos a seguir las mismas convenciones. No es obligatorio pero mejora la consistencia.

ls .claude/agent-memory/ 2>/dev/null

4. Claude Code actualizado:

claude --version

Asegúrate de tener v2.1.63 o posterior — las versiones más recientes soportan background: true, isolation: worktree, y todos los campos de frontmatter que usaremos.

5. Git limpio:

git status

Los git worktrees requieren un estado de git limpio (sin cambios uncommitted). Si tienes cambios pendientes, commitéalos o haz stash antes de empezar.

git stash

Cómo Funciona la Delegación Paralela — Vista General

Antes de entrar a la mecánica detallada (cápsulas 02-04), aquí tienes una vista general de cómo todo encaja:

Los tres pilares

La delegación paralela en Claude Code se apoya en tres mecanismos:

1. Background execution — Un subagent se ejecuta en segundo plano mientras Claude continúa con otros subagents o con tu conversación. Se activa con background: true en el frontmatter o con Ctrl+B.

---
name: worker
background: true     ← se ejecuta en background
---

2. Worktree isolation — Cada subagent trabaja en su propia copia del repositorio (un git worktree temporal). Los cambios de un agente no afectan a los demás hasta que se hace merge al final.

---
name: worker
isolation: worktree  ← trabaja en copia aislada del repo
---

3. Merge coordination — Un subagent (o Claude main) revisa los resultados de todos los workers, verifica consistencia, y combina los cambios en un resultado coherente.

Estos tres mecanismos trabajan juntos:

Background → permite ejecución simultánea
Worktree   → previene conflictos de archivos
Merge      → produce resultado coherente

Lo que Claude Code maneja automáticamente

Crear y destruir worktrees temporales
Esperar a que todos los subagents background terminen
Pre-aprobar permisos para subagents en background
Gestionar el ciclo de vida de cada subagent

Lo que tú necesitas gestionar

Diseñar el dependency graph (qué es paralelo, qué es secuencial)
Definir los subagent files con los campos correctos
Escribir los prompts de orquestación
Decidir la estrategia de error handling (fail-fast vs resilient)
Verificar la consistencia de los resultados

Conceptos Clave que Usaremos

Antes de entrar a las cápsulas técnicas, asegúrate de tener claros estos conceptos:

Delegación paralela: Lanzar múltiples subagents simultáneamente para que trabajen al mismo tiempo en tareas independientes. Reduce wall-clock time proporcionalmente al número de tareas paralelas.
Background execution: Un subagent que se ejecuta en segundo plano mientras tú (o Claude) continúas con otra cosa. Se activa con background: true en el frontmatter o presionando Ctrl+B durante la ejecución.
Git worktree: Una copia aislada del repositorio que comparte el mismo historial de git pero tiene su propio working directory. Permite que múltiples agentes editen archivos sin conflictos de escritura simultánea. Se activa con isolation: worktree.
Dependency graph: El modelo mental de qué tareas dependen de cuáles. Las tareas sin dependencias entre sí son candidatas a paralelización. Las que tienen dependencias deben ejecutarse en secuencia.
Merge coordination: El proceso de combinar los resultados de agentes paralelos en un resultado coherente. Incluye detectar conflictos, resolver inconsistencias, y producir un output unificado.
maxTurns: Campo del frontmatter que limita cuántos turnos agénticos puede tomar un subagent. Funciona como timeout para evitar ejecuciones infinitas.

Límites: Qué NO Se Cubre en Este Módulo

❌ Agent Teams — Se cubre en el Módulo 4. Aquí coordinas manualmente; Agent Teams automatizan la coordinación
❌ Plugins — Se cubren en el Módulo 5. Aquí los subagents son archivos locales
❌ Hooks avanzados — Se cubren en el Módulo 6. Aquí se mencionan hooks solo cuando son relevantes para error handling
❌ SDK headless — Se cubre en el Módulo 6. Aquí todo es interactivo en Claude Code
❌ CI/CD pipelines — Se cubren en la guía siguiente. Aquí la paralelización es en tiempo de desarrollo
❌ Concurrencia a nivel de código (threads, async) — La paralelización es a nivel de subagents, no de código fuente

Evidencia de Éxito

Al terminar este módulo, sabrás que tuviste éxito si:

✅ Puedes identificar en 30 segundos si un conjunto de tareas es paralelizable o tiene dependencias que requieren secuencia
✅ Has ejecutado al menos 2 subagents en paralelo y verificado que ambos completaron correctamente
✅ Entiendes la diferencia entre background: true y isolation: worktree — y cuándo usar cada uno
✅ Puedes manejar un escenario donde un subagent paralelo falla — sin perder el trabajo de los demás
✅ Has completado el refactor paralelo de 4 módulos con merge coordinado
✅ Puedes explicar a un colega por qué no se paraleliza todo — y cuándo la secuencia es la decisión correcta

Test rápido de autoevaluación

Si puedes responder estas preguntas al terminar el módulo, vas por buen camino:

¿Cuándo es mejor ejecutar subagents en paralelo vs en secuencia?
¿Qué es un git worktree y por qué lo necesitas para ediciones paralelas?
¿Qué pasa si un subagent en background falla por falta de permisos?
¿Cómo se coordinan los resultados cuando 4 agentes terminan en momentos diferentes?
¿Qué campo del frontmatter limita la ejecución de un subagent como timeout?

La Analogía del Equipo de Desarrollo

Si tienes experiencia liderando equipos, la delegación paralela es intuitiva. Piénsalo como gestionar un sprint:

Project manager (tú) con 4 desarrolladores:

Opción A — Secuencial:
"María, haz el módulo auth. Cuando termines,
 Juan, haz products. Cuando termine Juan,
 Ana, haz orders. Cuando termine Ana,
 Carlos, haz notifications."
→ 4 sprints de 1 semana cada uno = 4 semanas

Opción B — Paralelo:
"María: auth. Juan: products. Ana: orders. Carlos: notifications.
 Los 4 empiezan hoy. Nos reunimos el viernes para integrar."
→ 1 sprint de 1 semana + 1 día de integración ≈ 1.2 semanas

La delegación paralela con Claude Code es exactamente Opción B. Cada subagent es un "desarrollador" con su propio workspace (worktree), su propio scope de trabajo, y sus propias restricciones. El merge coordinator es la reunión del viernes donde se integra todo.

Dónde la analogía se rompe

A diferencia de un equipo humano, los subagents:

No se comunican entre sí durante la ejecución — no hay Slack, no hay preguntas en tiempo real
No tienen contexto implícito compartido — lo que sabe uno no lo sabe el otro (a menos que tengan memory: project)
No pueden improvisar — si el system prompt no cubre un escenario, no pueden preguntar
No tienen ego — nunca discuten sobre la mejor forma de nombrar una variable

Esto hace que la planificación previa (dependency graph, convenciones en CLAUDE.md, system prompts detallados) sea más importante que en un equipo humano. Un equipo humano puede coordinarse ad-hoc. Los subagents paralelos necesitan todo definido de antemano.

Nota sobre Features

Las features de delegación paralela que cubrimos — background: true, isolation: worktree, y maxTurns — son funcionalidad estable de Claude Code. Background execution y worktree isolation funcionan con subagents custom. La variable de entorno CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 está disponible para debugging.

Última verificación de funcionalidad: Marzo 2026

Resumen

La ejecución secuencial no escala cuando tienes múltiples tareas independientes — 4 tareas × 3 min = 12 min secuencial vs ~4 min en paralelo
La delegación paralela es la síntesis de Phase 1: subagents con identidad (M1) + memoria compartida (M2) + ejecución concurrente (M3)
El dependency graph es la herramienta mental clave: si la tarea B no necesita el resultado de A, pueden ir en paralelo
Git worktrees (isolation: worktree) permiten que agentes paralelos editen archivos sin conflictos de escritura
La coordinación de resultados — no el lanzamiento — es el skill que distingue paralelización efectiva de caos concurrente
El mini-proyecto construye un refactor de 4 módulos en paralelo con un merge coordinator final
Todo lo aprendido aquí se formaliza en Agent Teams (Módulo 4) — este módulo te da el entendimiento manual que Agent Teams automatizan

Recursos Adicionales

Create Custom Subagents (Anthropic Docs) — Documentación oficial que incluye campos background, isolation, y maxTurns en frontmatter
Claude Code Sub-agents — Background Execution — Referencia de ejecución en background y permisos pre-aprobados
Claude Code Best Practices — Buenas prácticas de delegación y paralelización
Claude Code CLI Reference — Referencia de flags y variables de entorno como CLAUDE_CODE_DISABLE_BACKGROUND_TASKS
Git Worktrees Documentation — Referencia oficial de git worktrees para entender el mecanismo subyacente
Claude Code Overview — Contexto general del modelo de ejecución de Claude Code

Siguiente cápsula: En la cápsula 02 aprenderás la mecánica concreta de la delegación paralela — cómo Claude Code ejecuta subagents en background, la sintaxis del campo background: true, el atajo Ctrl+B, los prompts que activan ejecución concurrente, y el campo isolation: worktree que previene conflictos de archivos. Pasarás de entender por qué paralelizar a saber cómo hacerlo.

← Anterior5. Proyecto — Memory Hierarchy para 3 Subagents Siguiente →2. Delegación Paralela — Syntax, Patterns, y Límites