Patrones de Composición de Equipos de Agentes

Heurísticas de tamaño de equipo

Simple

1–2

Revisión unidimensional, bug aislado, feature pequeña. Coordinación mínima.

Moderado

2–3

Cambios en múltiples archivos, 2–3 preocupaciones separadas, features medianas.

Complejo

3–4

Concerns transversales, features grandes, debugging profundo con múltiples hipótesis.

Muy complejo

4–5

Full-stack, revisiones exhaustivas, problemas sistémicos. Overhead de coordinación alto.

Equipos diseñados para CULTIVA IA Platform v2

Equipo Migración — Pydantic v1 → v2
Tarea 1: Actualizar 12.000 LOC en 4 módulos
4 agentes
L
Coordinador de migración
team-lead
Planificación y coordinación entre módulos
I
Implementador — skills-runner
team-implementer
Módulos skills-runner + scheduler
I
Implementador — webhook-router
team-implementer
Módulos webhook-router + report-generator
R
Verificador de corrección
team-reviewer
Validación semántica post-migración

          Patrón: Migration Team
          lead + 2×impl + reviewer
          Complejo
        

Equipo Auditoría de Seguridad

Tarea 2: Audit pre-release endpoints, secrets, deps

4 agentes

R

Revisor OWASP / Vulnerabilidades

team-reviewer

SQLi, XSS, RCE, deserialización

R

Revisor Auth / Control de acceso

team-reviewer

JWT, RBAC, OAuth flows

R

Revisor Dependencias / Supply chain

team-reviewer

CVEs en requirements.txt, lockfiles

R

Revisor Secrets / Configuración

team-reviewer

Env vars, hardcoded keys, .env leaks

Equipo Feature — Panel de Analíticas

Tarea 3: React frontend + FastAPI backend + tests

4 agentes

L

Tech Lead de feature

team-lead

Diseño de API, coordinación capas

F

Frontend — React + Recharts

team-implementer

Dashboard, gráficas, filtros UI

B

Backend — FastAPI async

team-implementer

Endpoints /metrics, aggregations

T

Test Engineer — pytest + Playwright

team-implementer

Unit tests, E2E, cobertura >80%

Equipo Debug — Worker Silencioso

Tarea 4: Worker scheduled falla sin error log

3 agentes

D

Investigador — Hipótesis excepción silenciosa

team-debugger

try/except bare, swallowed exceptions

D

Investigador — Hipótesis race condition

team-debugger

async locks, task cancellation, asyncio

D

Investigador — Hipótesis scheduler config

team-debugger

Cron expr, timezone offset, missed triggers

Equipo Research — Selección de Queue para Scheduler v2

Tarea 5: Comparar Redis Streams vs BullMQ vs Celery 5 — throughput, fiabilidad, DX, costo ops

3 agentes

S

Researcher — Redis Streams

general-purpose

Benchmarks, consumer groups, at-least-once

S

Researcher — BullMQ (Node/Redis)

general-purpose

Worker pools, concurrency, TypeScript SDK

S

Researcher — Celery 5 + Redis broker

general-purpose

Python-native, beat scheduler, flower UI

Tabla de selección de tipo de agente (subagent_type)

Tipo	Herramientas	Usar para	¿Escribe?
general-purpose	ReadWrite EditBash WebSearchWebFetch	Implementación, investigación, cualquier tarea que requiera acceso completo	Sí
Exploresolo lectura	ReadGrep Glob	Research de codebase, exploración de estructura, análisis estático	No
Plansolo lectura	ReadGrep Glob	Planificación de arquitectura, descomposición de tareas, diseño	No
team-reviewer	ReadGrep BashTaskUpdate SendMessage	Revisión de código con hallazgos estructurados, auditorías de calidad y seguridad	No
team-debugger	ReadGrep BashTaskUpdate SendMessage	Investigación de bugs por hipótesis, diagnosis en paralelo, análisis de trazas	No
team-implementer	ReadWrite EditBash TaskUpdateSendMessage	Construcción de features dentro de límites de propiedad de archivos definidos	Sí
team-lead	ReadGrep BashAgent TaskListSendMessage	Orquestación de equipo, spawn de agentes, coordinación y descomposición de trabajo	Coord.

Reglas para equipos personalizados

1

Siempre hay un coordinador

Designa un team-lead o coordina tú directamente. Sin coordinador, los agentes generan trabajo duplicado.

2

Roles ↔ tipos de agente

Usa agentes especializados cuando estén disponibles. No asignes implementación a agentes Explore o Plan (son read-only).

3

Sin roles duplicados

Dos agentes haciendo lo mismo desperdicia tokens. Si los reviewers detectan los mismos issues, redefine los focos (logic / security / perf).

4

Define límites desde el inicio

Cada implementador necesita propiedad clara de archivos o responsabilidades. Los conflictos de merge matan la eficiencia del equipo.

5

Empieza pequeño

2–4 agentes es el punto óptimo. Con 5+ el overhead de coordinación supera las ganancias de paralelismo.

6

Contexto completo al spawnar

Los agentes spawneados no tienen historial previo. El lead debe incluir TODO el contexto relevante en el prompt inicial de cada agente.

Modos de visualización

"tmux" activo en CULTIVA IA

Cada agente en un panel tmux independiente. Ideal para workflows de desarrollo: monitoreo visual en tiempo real, inspección de outputs en paralelo.

"iterm2"

Cada agente en un tab iTerm2. Para usuarios macOS que prefieren iTerm2 sobre tmux. Requiere iTerm2 instalado.

"in-process"

Todos los agentes en el mismo proceso. Ideal para CI/CD y entornos sin terminal interactiva. No requiere tmux ni iTerm2.

// ~/.claude/settings.json — configuración activa CULTIVA IA Platform
{
  "teammateMode": "tmux",
  "agentTeams": {
    "maxConcurrentTeams": 3, // migration + security + feature en paralelo
    "defaultTimeout": 600000, // 10 min por agente
    "logLevel": "verbose"
  }
}

Patrones de Composiciónde Equipos de Agentes

Patrones de Composición
de Equipos de Agentes