Módulo 4: Agent Teams

1. Introducción al Módulo — De Orquestación Manual a Agent Teams

Descripción

En la Phase 1 aprendiste a crear subagents con identidad propia, a darles memoria persistente, y a delegarles tareas en paralelo. Coordinaste todo manualmente — tú decidías qué agente hacía qué, cuándo empezaba, cómo se resolvían las dependencias, y qué pasaba cuando un agente terminaba antes que otro. Funcionó. Pero si eres honesto, notaste el patrón: a medida que agregas más agentes y más dependencias, la coordinación manual se convierte en el cuello de botella. No es el código lo que te frena — es la logística.

Agent Teams formalizan esa coordinación. En lugar de ser tú el director de orquesta que mueve cada pieza, defines un equipo con un team lead que coordina y teammates que ejecutan. El team lead sabe qué tareas existen, quién puede hacerlas, qué depende de qué, y cuándo reasignar trabajo. Tú pasas de "director de agentes" a "diseñador de equipos" — configuras la estructura una vez y dejas que el team lead resuelva la ejecución.

Este módulo abre la Phase 2 porque Agent Teams son la evolución natural de todo lo que construiste en Phase 1. Los subagents custom del módulo 1 se convierten en teammates. La memoria del módulo 2 da contexto a cada miembro del equipo. La delegación paralela del módulo 3 se automatiza con un task board y dependencias explícitas. Agent Teams no reemplazan lo que aprendiste — lo empaquetan en una abstracción que escala.

Al terminar, tendrás un equipo de 3 agentes (team lead + frontend agent + backend agent) con un task board de 5+ tareas y dependencias reales. No como demo — como sistema funcional que puedes adaptar a tu proyecto.

⚠️ FEATURE EXPERIMENTAL

Agent Teams es una feature experimental de Claude Code. La API, configuración, y comportamiento pueden cambiar significativamente entre versiones. Este módulo enseña el modelo mental (team lead, teammates, task board, dependencias) que es transferible independientemente de la API específica, y la configuración práctica según la implementación disponible a marzo 2026.

Si Agent Teams no está accesible en tu versión de Claude Code, cada cápsula incluye una sección de alternativa manual usando los patrones de Phase 1. No te quedes bloqueado.

Última verificación de funcionalidad: Marzo 2026

¿Dónde Estamos en la Guía?

Contexto en la Guía

Esta guía tiene 8 módulos organizados en 3 phases:

Phase 1: Subagents Avanzados (Módulos 1-3)           ← COMPLETADA
├── Módulo 1: Custom Subagents                        ✅
├── Módulo 2: Agent Memory y Scopes                   ✅
└── Módulo 3: Parallel Sub-Agent Delegation            ✅

Phase 2: Agent Teams y Plugins (Módulos 4-6)
├── Módulo 4: Agent Teams                              ← ESTÁS AQUÍ
├── Módulo 5: Plugins: Crear y Distribuir
└── Módulo 6: Hooks Avanzados y SDK Headless

Phase 3: Orquestación (Módulos 7-8)
├── Módulo 7: Remote Control y CLAUDE.md para Equipos
└── Módulo 8: Proyecto: Sistema Multi-Agente Completo

Duración total estimada: 8-10 horas (self-paced).

¿Qué cambia en Phase 2?

En Phase 1 aprendiste los building blocks: subagents con identidad, memoria, y delegación paralela. Controlabas todo — cada prompt, cada secuencia, cada merge. Phase 2 introduce abstracciones de coordinación: Agent Teams automatizan la orquestación, plugins empaquetan configuraciones reutilizables, y hooks + SDK dan control programático. El cambio mental es: dejas de operar agentes individuales y empiezas a diseñar sistemas.

El Problema: La Coordinación Manual No Escala

Lo que viviste en Phase 1

En el módulo 3 delegaste tareas en paralelo. Quizás algo como esto:

"Ejecuta en paralelo:
 1. El reviewer analiza src/api/ buscando problemas de seguridad
 2. El implementer agrega input validation a los endpoints
 3. El tester corre la suite de integration tests

 Cuando todos terminen, consolida los resultados."

Funcionó con 3 agentes. Pero hubo fricciones:

Dependencias implícitas: El tester debería correr después del implementer, pero lo lanzaste en paralelo y tuvo que usar el código pre-cambios.
Conflictos de archivos: El reviewer y el implementer tocaron los mismos archivos simultáneamente.
Merge manual: Consolidar 3 reportes con formatos ligeramente diferentes requirió que tú (o Claude) interpretara cada output.
Sin visibilidad: No sabías qué agente estaba haciendo qué hasta que todos terminaron.

Escala el escenario a 5 agentes

Imagina un equipo real de desarrollo:

1. architect    → Diseña la estructura de la feature
2. frontend     → Implementa los componentes UI
3. backend      → Implementa los endpoints API
4. tester       → Escribe y corre tests
5. reviewer     → Revisa el código de frontend y backend

Las dependencias ahora son complejas:

architect ─────→ frontend ─────→ reviewer
           └──→ backend  ──┬──→ reviewer
                           └──→ tester

Frontend y backend dependen del architect. El reviewer depende de frontend Y backend. El tester depende de backend. Coordinar esto manualmente implica:

Lanzar el architect primero
Esperar a que termine
Lanzar frontend y backend en paralelo
Esperar a que ambos terminen
Lanzar reviewer y tester en paralelo
Consolidar todo

Y si el backend falla a mitad de camino, ¿qué pasa con el tester que lo esperaba? ¿Y el reviewer que necesita ambos? Cada bifurcación multiplica la complejidad de tu prompt de orquestación.

Lo que Agent Teams resuelven

Con Agent Teams, esa coordinación se declara, no se programa:

Team Lead: "Tengo 5 tareas con estas dependencias. 
            Asigno cada una al teammate apropiado.
            Cuando una tarea termina, verifico dependencias 
            y lanzo las siguientes automáticamente."

Tú defines la estructura del equipo y las dependencias. El team lead resuelve la ejecución. Si un teammate falla, el team lead decide si reasigna, reintenta, o escala. Eso es lo que este módulo enseña.

Agent Teams: El Modelo Mental

Los 4 componentes

┌─────────────────────────────────────────────────┐
│                  AGENT TEAM                      │
│                                                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐   │
│  │ Teammate │    │ Teammate │    │ Teammate │   │
│  │ frontend │    │ backend  │    │ tester   │   │
│  └────┬─────┘    └────┬─────┘    └────┬─────┘   │
│       │               │               │          │
│       └───────┬───────┘───────────────┘          │
│               │                                  │
│        ┌──────┴──────┐                           │
│        │  Team Lead  │                           │
│        │  (coordina) │                           │
│        └──────┬──────┘                           │
│               │                                  │
│        ┌──────┴──────┐                           │
│        │  Task Board │                           │
│        └─────────────┘                           │
└─────────────────────────────────────────────────┘

1. Team Lead — El agente principal que coordina. No ejecuta tareas de código directamente — asigna trabajo, monitorea progreso, resuelve dependencias y conflictos. Se configura como el agente principal con claude --agent team-lead.

2. Teammates — Subagents especializados disponibles para el team lead. Cada teammate tiene su rol, herramientas, y expertise definidos en un agent file. El team lead conoce sus capacidades y les asigna tareas apropiadas.

3. Task Board — La lista de tareas con estados (pending, in-progress, done, blocked), dependencias, y prioridades. El team lead gestiona el task board, decidiendo qué tarea lanzar y cuándo.

4. Dependencias — Relaciones entre tareas: "test depende de implementation," "review depende de frontend Y backend." Las dependencias determinan el orden de ejecución — no se lanza una tarea hasta que sus dependencias estén completas.

La analogía correcta

No pienses en Agent Teams como "subagents con un manager." Piensa en un tablero kanban con asignación automática:

BACKLOG          IN PROGRESS       DONE
┌──────────┐     ┌──────────┐     ┌──────────┐
│ design   │ ──→ │ frontend │ ──→ │ backend  │
│ review   │     │ (agent)  │     │ (done)   │
│ tests    │     └──────────┘     └──────────┘
└──────────┘

Dependencies:  frontend → waits for design
               tests → waits for backend
               review → waits for frontend AND backend

El team lead es quien mueve las tarjetas. Cuando una tarea pasa a DONE, verifica qué tareas bloqueadas se desbloquean y las asigna al teammate apropiado.

Agent Teams vs Subagents: la diferencia clave

Aspecto	Subagents (Phase 1)	Agent Teams (Phase 2)
Quién coordina	Tú (o Claude como proxy)	El team lead
Dependencias	Implícitas en el orden del prompt	Explícitas y declaradas
Visibilidad	Ves el resultado al final	Task board con estados
Fallo de un agente	Tú decides qué hacer	Team lead reasigna o escala
Escalabilidad	2-3 agentes cómodo	5+ agentes manejable
Configuración	Prompt de orquestación	Agent files + team config

La inversión de control es el cambio fundamental: en Phase 1, el control es tuyo. En Agent Teams, el control es del team lead — tú defines las reglas, él las ejecuta.

Objetivo del Módulo

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

✅ Configurar un Agent Team con team lead y 2+ teammates usando agent files
✅ Definir roles y especialidades de cada teammate con boundaries claros
✅ Crear un task board con 5+ tareas, dependencias explícitas, y prioridades
✅ Configurar messaging entre teammates para coordinación directa
✅ Manejar conflictos y failures: teammate que falla, resultados contradictorios, reasignación
✅ Observar y analizar cómo el team lead resuelve la ejecución de un task board complejo

Objetivo profesional

Agent Teams representa cómo será el desarrollo con IA en los próximos años: no un solo agente que hace todo, sino equipos de agentes especializados con coordinación automática. Dominar el modelo mental de team lead, task board y dependencias te prepara para cualquier framework de orquestación multi-agente — la API específica puede cambiar, pero los patrones de coordinación son universales.

Roadmap del Módulo

Mapa de cápsulas

#	Cápsula	Qué aprenderás	Tipo
01	Introducción (esta)	Contexto, modelo mental, por qué Agent Teams importan	Intro
02	Team Lead: Configuración	Configurar el team lead, su system prompt, modelo, y lista de teammates	Técnica
03	Teammates: Roles y Límites	Definir teammates con especialidades, skills, y boundaries claros	Técnica
04	Task Board y Dependencias	Crear y gestionar un task board con dependencias entre tareas	Técnica
05	Messaging y Conflictos	Comunicación entre teammates, resolución de conflictos, failure modes	Técnica
06	Proyecto: Team de 3 Agentes	Team lead + frontend + backend con task board y dependencias reales	Proyecto

Flujo de aprendizaje

Primero entenderás cómo se configura el team lead — el agente que coordina todo y la pieza central del equipo (cápsula 02). Luego aprenderás a definir teammates con roles y límites claros — porque un equipo sin especialización es un grupo de agentes genéricos (cápsula 03). Después verás cómo funciona el task board — asignar tareas, declarar dependencias, gestionar prioridades (cápsula 04). Continuarás con messaging entre teammates y resolución de conflictos — la comunicación que hace que el equipo funcione como unidad (cápsula 05). Finalmente, construirás un equipo funcional de 3 agentes con un task board real (cápsula 06).

La progresión es: configurar líder → definir miembros → asignar trabajo → resolver problemas → construir sistema.

Cada cápsula construye sobre la anterior. El task board (04) necesita teammates definidos (03), que a su vez necesitan un team lead configurado (02). No saltes cápsulas.

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

Conexión con el Proyecto

Proyecto del módulo: Team de 3 Agentes con Task Board

En la cápsula 06 construirás un equipo funcional:

Team Lead — Coordina el equipo, asigna tareas del task board, resuelve dependencias y conflictos. No escribe código directamente.
Frontend Agent — Especializado en componentes UI, estilos, y estructura del frontend. Solo toca archivos en directorios frontend.
Backend Agent — Especializado en endpoints API, lógica de negocio, y acceso a datos. Solo toca archivos en directorios backend.

Tu prompt:
"Implementa la feature de perfil de usuario con edición de datos"

↓

Team Lead:
├── Task 1: "Diseñar schema de datos" → backend agent
├── Task 2: "Endpoint GET /profile"   → backend agent (depende de T1)
├── Task 3: "Endpoint PUT /profile"   → backend agent (depende de T1)
├── Task 4: "Componente ProfilePage"  → frontend agent (depende de T2)
├── Task 5: "Form de edición"         → frontend agent (depende de T3, T4)
└── Task 6: "Integración y review"    → team lead (depende de T2-T5)

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

El equipo de 3 agentes es el prototipo del sistema de 5 agentes del proyecto integrador. En el módulo 8, expandirás el team lead para coordinar architect, frontend, backend, tester, y reviewer. Los patrones de task board, dependencias, y conflict resolution que aprendes aquí se aplican directamente — solo cambia la escala.

Prerequisitos

Conocimientos necesarios

✅ Módulos 1-3 completados — Custom subagents, memory scopes, delegación paralela
✅ Subagent files — Sabes crear archivos Markdown con frontmatter YAML
✅ Tool restriction — Entiendes allowlists, denylists, y permission modes
✅ Delegación paralela — Has ejecutado múltiples subagents simultáneamente
✅ Output parsing — Sabes diseñar system prompts que producen outputs parseables

Verificación rápida

Si puedes responder "sí" a estas preguntas, estás listo:

¿Puedes crear un subagent como archivo .md con frontmatter YAML en menos de 5 minutos?
¿Sabes la diferencia entre tools (allowlist) y disallowedTools (denylist)?
¿Has delegado al menos 2 tareas en paralelo y consolidado los resultados?
¿Puedes explicar por qué un reviewer no debe tener acceso a Write?
¿Entiendes el concepto de "solo el mensaje final regresa al padre"?

No necesitas

❌ Experiencia previa con Agent Teams — se cubre completamente aquí
❌ Conocimiento de plugins — se cubre en el módulo 5
❌ Experiencia con SDK headless — se cubre en el módulo 6
❌ Un proyecto grande — funciona con cualquier codebase de 5+ archivos

Setup para el Módulo

Lo que necesitas tener listo

1. Claude Code actualizado:

claude --version

Asegúrate de tener la versión más reciente. Agent Teams requiere soporte para agent files con el campo que define teammates.

2. Los subagents de Phase 1 disponibles:

Si completaste los módulos 1-3, ya tienes subagent files en .claude/agents/. Los adaptaremos para Agent Teams en este módulo.

ls .claude/agents/

3. Directorio para el equipo:

mkdir -p .claude/agents

4. Verificar soporte de Agent Teams:

claude --help | grep -i agent

Si el flag --agent aparece en la ayuda, tienes soporte para ejecutar agent files como punto de entrada. Si Agent Teams con team lead y teammates no está disponible en tu versión, las cápsulas incluyen alternativas manuales.

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

❌ Plugins — Se cubren en el Módulo 5. Aquí los agent files son locales, no empaquetados
❌ Hooks avanzados y SDK — Se cubren en el Módulo 6. Aquí usamos hooks básicos cuando sea necesario
❌ Remote control — Se cubre en el Módulo 7. Aquí todo es local
❌ Más de 5 teammates — Cubrimos equipos de 2-3 teammates. Equipos más grandes siguen los mismos patrones pero con complejidad adicional
❌ Agent Teams en CI/CD — Se cubre en la guía de CI/CD Pipelines. Aquí todo es interactivo

Alternativa Manual: Si Agent Teams No Está Disponible

Si tu versión de Claude Code no soporta Agent Teams como feature formal, puedes implementar el mismo modelo mental con los patrones de Phase 1:

Team Lead     → Un subagent "coordinator" con Agent(teammate1), Agent(teammate2)
Task Board    → System prompt del coordinator con la lista de tareas y dependencias
Dependencias  → Lógica en el system prompt: "No lances Task B hasta que Task A reporte DONE"
Messaging     → El coordinator pasa outputs entre subagents manualmente

Cada cápsula incluye una sección "Alternativa manual" con el patrón equivalente. El modelo mental es idéntico — la diferencia es que con Agent Teams la coordinación es automática, y sin ellos la programas en el system prompt del coordinator.

La ventaja de aprender Agent Teams aunque uses la alternativa: cuando la feature esté GA, ya entiendes los conceptos y la migración es directa.

Evidencia de Éxito

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

✅ Puedes configurar un team lead con su lista de teammates en un agent file
✅ Cada teammate tiene un rol claro con boundaries que el team lead respeta
✅ El task board tiene 5+ tareas con dependencias y prioridades
✅ El team lead asigna tareas al teammate correcto basándose en su descripción
✅ Los teammates pueden intercambiar información cuando necesitan coordinarse
✅ El team lead resuelve al menos un caso de conflicto o failure durante la ejecución
✅ Puedes explicar la diferencia entre orquestación manual (Phase 1) y Agent Teams

Test rápido de autoevaluación

Si puedes responder estas preguntas al terminar:

¿Cuál es la diferencia entre un team lead y un subagent coordinador?
¿Cómo se declara una dependencia entre tareas?
¿Qué pasa cuando un teammate falla a mitad de una tarea?
¿Cómo se configura qué teammates puede invocar el team lead?
¿Por qué el team lead no debería ejecutar tareas de código directamente?

Resumen

Este módulo marca la transición de orquestación manual a diseño de equipos — defines la estructura, el team lead resuelve la ejecución
Agent Teams tienen 4 componentes: team lead (coordina), teammates (ejecutan), task board (lista de tareas), y dependencias (orden de ejecución)
La diferencia clave con Phase 1: las dependencias son explícitas y el team lead coordina automáticamente en lugar de que tú lo hagas
Agent Teams es una feature experimental (última verificación: marzo 2026) — el módulo enseña patrones transferibles y proporciona alternativas manuales
El proyecto construye un equipo de 3 agentes (team lead + frontend + backend) con task board y dependencias reales
Todo lo aprendido en Phase 1 (subagents, memoria, delegación paralela) es la base — Agent Teams empaquetan esos building blocks en una abstracción que escala

Recursos Adicionales

Claude Code Sub-Agents (Anthropic Docs) — Documentación oficial de subagents como base de Agent Teams
Create Custom Subagents — Referencia de agent files, frontmatter YAML, y tool restriction
Claude Code CLI Reference — Flag --agent para ejecutar un agent file como punto de entrada
Claude Code Best Practices — Buenas prácticas de delegación y coordinación
Claude Code Settings — Configuración de permisos y herramientas
Claude Code Overview — Contexto general de Claude Code como agente
Prompt Engineering: System Prompts — Principios de system prompts aplicables al team lead
Multi-Agent Orchestration Patterns — Patrones de coordinación multi-agente de Anthropic

Siguiente cápsula: En la cápsula 02 configurarás el team lead — el agente que coordina todo el equipo. Verás qué lo hace diferente de un subagent regular, cómo definir su system prompt para coordinación (no ejecución), cómo declarar la lista de teammates disponibles, y qué modelo usar para que tome buenas decisiones de asignación.

← Anterior5. Proyecto — Refactor Paralelo de 4 Módulos Siguiente →2. Team Lead — Configuración y Rol del Coordinador