Arquitectura híbrida: Agent Teams + subagentes en Claude Code

Visión general

El sistema tiene dos capas:

1. Agent Team — Lead + 3 teammates que debaten entre sí para construir el artefacto
2. Subagentes — 3 agentes que el Lead lanza para tareas acotadas (investigar, validar, publicar)

La separación no es cosmética — define herramientas disponibles, modelos asignados y estructura de comunicación.

Diagrama de la arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                          AGENT TEAM                             │
│                                                                 │
│   ┌─────────────────────────────────┐                           │
│   │              LEAD               │                           │
│   │         Modelo: Sonnet          │                           │
│   └─────────────────────────────────┘                           │
│         │              │              │                          │
│      FASE 1          FASE 2        FASE 3                        │
│    (subagente)     (teammates)   (subagentes)                    │
│         │              │              │                          │
│         v              v              v                          │
│                                                                 │
│  ┌──────────────┐      │      ┌──────────────┐  ┌────────────┐  │
│  │ Investigador │      │      │  Validador   │  │ Publisher  │  │
│  └──────────────┘      │      └──────────────┘  └────────────┘  │
│  Subagente             │      Subagentes — corren dentro del Lead│
│  Sin sesión propia     │                                        │
│                        v                                        │
│          ┌─────────────────────────────┐                        │
│          │      Shared Task List       │                        │
│          └──────┬──────────┬───────────┘                        │
│                 │          │          │                          │
│                 v          v          v                          │
│          ┌──────────┐ ┌──────────┐ ┌──────────┐                 │
│          │Arquitecto│◇│ Revisor  │◇│Optimizador│                │
│          └──────────┘ └──────────┘ └──────────┘                 │
│          Teammates — Modelo: Opus (siempre)                      │
│          Sesión propia. Se comunican via Mailbox                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Las 3 fases del pipeline

Fase 1 — Solo el Lead

1. Lead recibe el request del usuario
2. Lead detecta ambigüedades bloqueantes → pregunta antes de arrancar
3. Lead lanza Investigador (subagente, SIN team_name) → recibe research

El Lead no empieza el trabajo sin el research. Si el Investigador no encontró fuente primaria para un comando, lo reporta — el Arquitecto no inventa comandos sin fuente.

Fase 2 — El equipo entra con contexto

4. Lead crea task list con dependencias
5. Lead spawna Arquitecto + Revisor + Optimizador (CON team_name)
   → incluye research del Investigador en el spawn prompt
6. Arquitecto escribe SKILL.md usando la información investigada
7. Revisor cuestiona → debate directo con Arquitecto (máx 2 rondas)
8. Optimizador comprime → elimina lo que Claude ya sabe (< 500 líneas)

Fase 3 — Validación y publicación

9. Lead lanza Validador (subagente, SIN team_name) → PASS o FAIL
10. Si pasa: Lead lanza Publisher (subagente, SIN team_name) → verifica en portal

El Publisher no corre si el Validador falló.

La asimetría del Task Tool

Este es el comportamiento crítico que define la arquitectura:

Los teammates NO tienen acceso al Task Tool. Solo el Lead puede lanzar subagentes.

Si un teammate intenta lanzar un subagente, falla silenciosamente o el sistema lo convierte en un teammate adicional (con team_name), lo que cambia el modelo de Sonnet a Opus y rompe el diseño.

Precaución

Las demos donde el Investigador fue lanzado con team_name por error corrieron en Opus en vez de Sonnet. La diferencia de costo es significativa cuando la skill requiere múltiples iteraciones de búsqueda.

La regla:

• Investigador, Validador, Publisher → lanzados por el Lead SIN team_name = subagentes en Sonnet
• Arquitecto, Revisor, Optimizador → lanzados por el Lead CON team_name = teammates en Opus

El descubrimiento del model routing

Agent Teams asigna Opus a los teammates automáticamente, sin importar lo que configures.

Mecanismo	Funciona
model: haiku en CLAUDE.md	No — ignorado
”Usa el modelo Sonnet” en el spawn prompt	No — es texto, no parámetro de sistema
Modelo global para todos los teammates	Sí — pero sin diferenciación por rol
Modelo del Lead session	Sí — los subagentes heredan del Lead

Datos reales de 37 llamadas analizadas:

Componente	Pedido	Real
Lead	Haiku	Sonnet (hereda del usuario)
Todos los teammates	Haiku / Sonnet por rol	Opus siempre
Subagentes (sin team_name)	Haiku	Sonnet (hereda del Lead)
Haiku usado	—	Nunca, en ninguna demo

Condiciones de salida por rol

Cada rol tiene una condición de salida explícita para evitar loops:

Rol	Condición de salida
Lead	Skill publicada y verificada en el portal
Investigador	Buscó en máximo 2 fuentes primarias
Arquitecto	SKILL.md escrito y Revisor aprobó
Revisor	Máximo 2 rondas de objeciones
Optimizador	Body < 500 líneas Y eliminó al menos 1 bloque
Validador	Ejecutó validate.sh y devolvió resultado
Publisher	Publicó en portal y verificó con curl

→ Ver los roles en detalle: contratos y reglas