Agent Teams en Claude Code: Cuando un Agente No es Suficiente

Estás debuggeando un bug crítico en producción. Tienes tres hipótesis sobre la causa: podría ser el caché de Redis, un race condition en el worker de Celery, o un problema con el load balancer de Nginx.

Con Claude Code normal, investigas una hipótesis a la vez. Pierdes 20 minutos descartando Redis. Otros 30 explorando Celery. Para cuando llegas a Nginx, ya pasó una hora y el bug sigue ahí.

¿Y si pudieras investigar las tres hipótesis en paralelo?

Eso es exactamente lo que permite Agent Teams, la nueva funcionalidad experimental de Claude Code que acaba de llegar en enero de 2026.

No estamos hablando de subagents (esos ayudantes rápidos que reportan resultados y desaparecen). Agent Teams son instancias completas de Claude Code que:

• Trabajan en paralelo, cada una con su propio contexto
• Se comunican directamente entre sí para compartir hallazgos
• Pueden desafiar las teorías de los demás
• Coordinan trabajo mediante una lista de tareas compartida

En este post exploramos qué son los Agent Teams, cuándo usarlos vs. subagents, casos de uso reales, y sus limitaciones actuales.

¿Qué son los Agent Teams?

Agent Teams es un sistema que te permite coordinar múltiples instancias de Claude Code trabajando juntas como un equipo. Una sesión actúa como team lead (líder del equipo), coordinando el trabajo, asignando tareas y sintetizando resultados. Los teammates (compañeros de equipo) trabajan de forma independiente, cada uno con su propio contexto, y pueden enviarse mensajes directamente.

Diferencia clave con subagents:

Los subagents ejecutan tareas focalizadas y reportan resultados al agente principal. Los Agent Teams son instancias completas que colaboran entre sí.

Ejemplo visual de la diferencia:

SUBAGENTS (jerárquico):
Main Agent
├── Subagent 1: Ejecuta tests → Reporta resultados
├── Subagent 2: Revisa docs → Reporta hallazgos
└── Subagent 3: Busca ejemplos → Reporta referencias

AGENT TEAMS (colaborativo):
Team Lead (coordina)
├─┬ Teammate 1: Security Review
│ └─→ Mensajea a Teammate 2: "Encontré vulnerabilidad en auth"
├─┬ Teammate 2: Performance Review
│ └─→ Responde: "Eso explica la latencia que vi"
└─┬ Teammate 3: Test Coverage
  └─→ Broadcast: "Añadí tests para los 2 casos"

Con subagents, el flujo es lineal: el agente principal delega, espera resultados, y procesa. Con Agent Teams, los teammates colaboran activamente y el lead sintetiza los hallazgos.

Arquitectura de Agent Teams

Un Agent Team consiste en:

Ubicación de archivos (local):

• Team config: ~/.claude/teams/{team-name}/config.json
• Task list: ~/.claude/tasks/{team-name}/

Cuando un teammate completa una tarea que bloquea otras, las tareas dependientes se desbloquean automáticamente sin intervención manual.

Contexto y comunicación:

Cada teammate tiene su propio contexto. Cuando se genera (spawn), recibe:

• Mismo contexto del proyecto que una sesión normal (CLAUDE.md, MCP servers, skills)
• El prompt de spawn del lead
• NO recibe el historial de conversación del lead (eso sería duplicar tokens)

Los teammates comparten información mediante:

• Mensajes directos: Un teammate envía a otro específicamente
• Broadcast: Mensaje a todos los teammates simultáneamente (cuidado: escala con el tamaño del equipo)
• Notificaciones automáticas: Cuando un teammate termina y queda idle, notifica al lead automáticamente
• Task list compartida: Todos ven el estado de las tareas y pueden reclamar trabajo disponible

Casos de Uso: Cuándo Usar Agent Teams

Agent Teams son más efectivos cuando la exploración paralela aporta valor real. Funcionan mejor para:

Caso 1: Code Review Paralelo con Dominios Especializados

Un revisor único tiende a gravitarse hacia un tipo de issue a la vez. Dividir los criterios de review en dominios independientes garantiza que seguridad, performance y test coverage reciban atención exhaustiva simultáneamente.

Prompt típico:

Crea un agent team para revisar PR #142. Genera tres reviewers:
- Uno enfocado en implicaciones de seguridad
- Uno checkeando impacto en performance
- Uno validando test coverage
Que cada uno revise y reporte hallazgos.

Cada reviewer trabaja desde el mismo PR pero aplica un filtro diferente. El lead sintetiza hallazgos de los tres después de que terminen.

Por qué funciona mejor en paralelo:

Con un solo agente, revisa seguridad, encuentra 3 issues, y reporta. Luego revisa performance, encuentra 2 issues. Test coverage queda superficialmente revisado porque ya gastaste el contexto. Con tres teammates, cada dominio recibe atención completa y especializada.

Caso 2: Debugging con Hipótesis Competidoras

Cuando la causa raíz no está clara, un agente único tiende a encontrar una explicación plausible y dejar de buscar. El prompt combate esto haciendo que teammates sean explícitamente adversariales: el trabajo de cada uno no es solo investigar su teoría, sino desafiar las teorías de los demás.

Prompt típico:

Los usuarios reportan que la app se cierra después de un mensaje en lugar
de mantener la conexión. Genera 5 agent teammates para investigar diferentes
hipótesis. Que hablen entre sí para intentar refutar las teorías de los otros,
como un debate científico. Actualiza el doc findings.md con el consenso que emerja.

Por qué la estructura de debate es clave:

La investigación secuencial sufre de anchoring bias: una vez que una teoría es explorada, la investigación subsecuente está sesgada hacia ella. Con múltiples investigadores independientes intentando activamente refutarse, la teoría que sobrevive es mucho más probable que sea la causa real.

Ejemplo real de resultado:

Teammate 1 (Redis hypothesis): "No encontré timeouts en Redis. Latencia < 5ms."
Teammate 2 (Celery hypothesis): "Workers procesando OK. No hay queue backup."
Teammate 3 (WebSocket hypothesis): "¡Encontrado! El heartbeat está en 30s pero
                                   el nginx timeout es 25s. Conexión se cierra prematuramente."
Teammate 4 (Client hypothesis): "Confirmo: logs del cliente muestran 'connection lost'
                                 justo a los 25 segundos. No es un bug del cliente."
Teammate 5 (Network hypothesis): "Descartado. Packet loss < 0.01%."

Lead synthesis: "Consensus alcanzado. Root cause: nginx timeout (25s) menor que
                WebSocket heartbeat (30s). Fix: reducir heartbeat a 20s o aumentar
                nginx timeout a 35s."

Sin la estructura de debate paralelo, probablemente habrías gastado 2 horas investigando Redis y Celery antes de llegar a WebSockets.

Caso 3: Nuevos Módulos o Features con Componentes Independientes

Cuando estás construyendo una feature con partes que no comparten archivos, teammates pueden trabajar en paralelo sin conflictos.

Prompt típico:

Implementa un sistema de autenticación OAuth2 con JWT. Crea un team con:
- Teammate 1: Database schema (users, tokens, refresh_tokens)
- Teammate 2: API endpoints (login, refresh, logout)
- Teammate 3: Frontend React components (LoginForm, AuthProvider)
- Teammate 4: Test suite (unit + integration tests)

Por qué funciona:

Cada teammate trabaja en archivos distintos (migrations, routes, components, tests). No hay conflictos. El lead coordina dependencias: la API no puede completarse hasta que el schema esté, pero tests pueden escribirse en paralelo al desarrollo.

Caso 4: Research y Comparativas

Agent Teams destacan en tareas de investigación donde queremos múltiples perspectivas sobre un mismo problema.

Prompt típico:

Investiga opciones para implementar full-text search en nuestra app.
Genera 4 teammates:
- PostgreSQL full-text search (built-in)
- Elasticsearch (dedicado)
- Meilisearch (ligero)
- Algolia (managed)

Que cada uno investigue: performance, costo, complejidad de setup,
y features. Compara resultados en comparison.md.

El lead recibe análisis detallados de 4 opciones en paralelo y puede generar una tabla comparativa informada.

Cómo Empezar con Agent Teams

Habilitar Agent Teams (Experimental)

Agent Teams están deshabilitados por defecto. Para habilitarlos, añade a tu settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

O exporta la variable de entorno en tu shell:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Crear Tu Primer Team

Una vez habilitado, dile a Claude que cree un agent team y describe la tarea en lenguaje natural. Claude crea el equipo, genera teammates, y coordina el trabajo.

Ejemplo que funciona bien:

Estoy diseñando un CLI tool que ayuda a developers a trackear comentarios
TODO en su codebase. Crea un agent team para explorar esto desde diferentes
ángulos: un teammate en UX, uno en arquitectura técnica, uno jugando
devil's advocate.

Este ejemplo funciona porque los tres roles son independientes y pueden explorar el problema sin esperarse entre sí.

Claude:

• Crea un team con lista de tareas compartida
• Genera teammates para cada perspectiva
• Los tiene explorando el problema
• Sintetiza hallazgos
• Intenta limpiar el team cuando termina

Modos de Visualización

Agent Teams soporta dos modos de visualización:

In-process (por defecto):

Todos los teammates corren dentro de tu terminal principal. Usa Shift+Up/Down para seleccionar un teammate y escribe para enviarle un mensaje directo. Funciona en cualquier terminal, sin setup extra.

Split panes (requiere tmux o iTerm2):

Cada teammate obtiene su propio panel. Ves el output de todos a la vez y puedes hacer click en un panel para interactuar directamente. Requiere tmux o iTerm2.

Configuración en settings.json:

{
  "teammateMode": "in-process"
}

O como flag para una sesión específica:

claude --teammate-mode in-process

Para split-pane mode, instala tmux:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt-get install tmux

# Para iTerm2: instala it2 CLI y habilita Python API en preferencias

Controlar el Team

Especificar teammates y modelos:

Claude decide cuántos teammates generar según la tarea, o puedes especificar:

Crea un team con 4 teammates para refactorizar estos módulos en paralelo.
Usa Sonnet para cada teammate.

Requerir aprobación de plan:

Para tareas complejas o riesgosas, puedes requerir que teammates planifiquen antes de implementar:

Genera un teammate architect para refactorizar el módulo de autenticación.
Requiere aprobación del plan antes de hacer cambios.

El teammate trabaja en modo read-only hasta que el lead apruebe el plan. Si se rechaza, revisa según feedback y resubmite.

Delegate mode:

Sin delegate mode, el lead a veces empieza a implementar tareas en lugar de esperar a teammates. Delegate mode previene esto restringiendo al lead a herramientas de coordinación: generar teammates, enviar mensajes, apagar teammates, y gestionar tareas.

Útil cuando quieres que el lead se enfoque solo en orquestación, sin tocar código directamente.

Para habilitarlo, primero crea un team, luego presiona Shift+Tab para entrar en delegate mode.

Hablar directamente con teammates:

Cada teammate es una sesión completa de Claude Code. Puedes enviar mensajes a cualquier teammate para dar instrucciones adicionales, hacer preguntas de seguimiento, o redirigir su enfoque.

• In-process mode: Shift+Up/Down para seleccionar, escribe para enviar mensaje. Enter para ver la sesión del teammate, Escape para interrumpir. Ctrl+T para toggle task list.
• Split-pane mode: Click en el panel del teammate para interactuar directamente.

Cerrar teammates:

Para terminar la sesión de un teammate de forma elegante:

Pide al teammate researcher que se apague

El lead envía solicitud de shutdown. El teammate puede aprobar (saliendo elegantemente) o rechazar con explicación.

Limpiar el team:

Cuando termines, pide al lead que limpie:

Limpia el team

Esto elimina recursos compartidos del equipo. El lead verifica teammates activos y falla si alguno sigue corriendo, así que apágalos primero.

⚠️ Importante: Siempre usa el lead para limpiar. Los teammates no deberían ejecutar cleanup porque su contexto de team puede no resolverse correctamente, dejando recursos inconsistentes.

Mejores Prácticas

Dale Suficiente Contexto a los Teammates

Los teammates cargan contexto del proyecto automáticamente (CLAUDE.md, MCP servers, skills), pero no heredan el historial de conversación del lead. Incluye detalles específicos de la tarea en el prompt de spawn:

Genera un teammate security reviewer con el prompt: "Revisa el módulo de
autenticación en src/auth/ en busca de vulnerabilidades. Enfócate en manejo
de tokens, gestión de sesiones, y validación de input. La app usa JWT tokens
almacenados en cookies httpOnly. Reporta issues con ratings de severidad."

Tamaño Apropiado de Tareas

• Demasiado pequeñas: El overhead de coordinación supera el beneficio
• Demasiado grandes: Los teammates trabajan mucho tiempo sin check-ins, incrementando riesgo de esfuerzo desperdiciado
• Tamaño ideal: Unidades auto-contenidas que producen un deliverable claro (una función, un archivo de tests, un review)

💡 Tip: El lead divide el trabajo en tareas y las asigna automáticamente. Si no está creando suficientes tareas, pídele que divida el trabajo en piezas más pequeñas. Tener 5-6 tareas por teammate mantiene a todos productivos y permite al lead reasignar trabajo si alguien se atasca.

Espera a que los Teammates Terminen

A veces el lead empieza a implementar tareas en lugar de esperar a teammates. Si notas esto:

Espera a que tus teammates completen sus tareas antes de proceder

Evita Conflictos de Archivos

Dos teammates editando el mismo archivo resulta en sobrescrituras. Divide el trabajo para que cada teammate tenga ownership de un conjunto distinto de archivos.

Monitorea y Dirige

Revisa el progreso de teammates, redirige enfoques que no están funcionando, y sintetiza hallazgos a medida que llegan. Dejar un team corriendo sin supervisión por mucho tiempo incrementa el riesgo de esfuerzo desperdiciado.

Empieza con Research y Review

Si eres nuevo en agent teams, empieza con tareas que tengan límites claros y no requieran escribir código: revisar un PR, investigar una librería, o investigar un bug. Estas tareas muestran el valor de exploración paralela sin los desafíos de coordinación que vienen con implementación paralela.

Uso de Tokens y Costos

Agent Teams usan significativamente más tokens que una sesión única. Cada teammate tiene su propio contexto, y el uso de tokens escala con el número de teammates activos.

Ejemplo de cálculo:

Sesión única:
- 1 agente × 100,000 tokens = 100,000 tokens

Agent Team (5 teammates):
- 1 lead × 50,000 tokens = 50,000 tokens
- 5 teammates × 80,000 tokens cada uno = 400,000 tokens
- Total: 450,000 tokens (4.5× más que sesión única)

Cuándo vale la pena:

Para research, review y desarrollo de nuevas features, los tokens extra suelen valer la pena porque reduces el tiempo total significativamente. Para tareas rutinarias, una sesión única es más cost-effective.

Mitigación de costos:

• Usa Haiku para teammates en tareas menos críticas (code review básico, research)
• Reserva Sonnet para el lead y teammates en tareas complejas
• Cierra teammates cuando terminen sus tareas específicas, no los dejes idle
• Usa delegate mode para evitar que el lead desperdicie tokens implementando

Limitaciones Actuales

Agent Teams están en fase experimental. Limitaciones actuales a tener en cuenta:

No Hay Resumption de Sesión con Teammates In-Process

/resume y /rewind no restauran teammates in-process. Después de resumir una sesión, el lead puede intentar enviar mensajes a teammates que ya no existen. Si esto ocurre, dile al lead que genere nuevos teammates.

El Estado de Tareas Puede Retrasarse

Los teammates a veces fallan en marcar tareas como completadas, lo que bloquea tareas dependientes. Si una tarea parece atascada, verifica si el trabajo está realmente hecho y actualiza el estado de la tarea manualmente o dile al lead que empuje al teammate.

Shutdown Puede Ser Lento

Los teammates terminan su request o tool call actual antes de apagarse, lo que puede tomar tiempo si están en medio de una operación compleja.

Un Team por Sesión

Un lead solo puede gestionar un team a la vez. Limpia el team actual antes de crear uno nuevo.

Sin Teams Anidados

Los teammates no pueden generar sus propios teams o teammates. Solo el lead puede gestionar el team.

El Lead es Fijo

La sesión que crea el team es el lead de por vida. No puedes promover un teammate a lead o transferir liderazgo.

Permisos Set at Spawn

Todos los teammates empiezan con el modo de permisos del lead. Puedes cambiar modos individuales después de generar, pero no puedes establecer modos per-teammate al momento de spawn.

Split Panes Requiere tmux o iTerm2

El modo in-process por defecto funciona en cualquier terminal. Split-pane mode no está soportado en VS Code integrated terminal, Windows Terminal, o Ghostty.

Agent Teams vs Claude Cowork: ¿Cuál Usar?

Si leíste mi post sobre Claude Cowork, te preguntarás cómo se relacionan.

¿Se complementan?

Absolutamente. En un día típico podrías usar:

• Mañana: Agent Teams para debuggear un race condition con 3 hipótesis en paralelo
• Tarde: Claude Cowork para generar un reporte ejecutivo con métricas de los fixes

Son herramientas complementarias para diferentes dominios del trabajo.

Conexión con el Ecosistema de Agentes

Agent Teams son un ejemplo perfecto de orquestación multi-agente. Si leíste mis posts sobre agentes de IA y aOrchestra, verás el patrón:

aOrchestra: Sistema de orquestación que delega tareas a sub-agentes especializados en entornos de ejecución aislados.

Agent Teams: Sistema de orquestación integrado en Claude Code donde teammates son instancias completas de Claude con contexto independiente.

Diferencia clave:

aOrchestra usa agentes especializados (Python Agent, React Agent, etc.) en sandboxes. Agent Teams usa instancias genéricas de Claude Code que heredan el mismo contexto del proyecto.

Similitud: Ambos implementan el patrón divide-and-conquer con coordinación explícita y lista de tareas compartida.

Conclusión

Agent Teams en Claude Code representa un avance significativo en colaboración multi-agente para desarrollo de software.

Lo más importante:

• ✅ Sí, es potente: Debugging paralelo y code review especializado ahorran horas
• ⚠️ No es barato: Cada teammate consume tokens como una sesión independiente
• 🎯 Mejor para: Research, code review, debugging con hipótesis competidoras, nuevos módulos independientes
• 🚫 No reemplaza: Subagents para tareas simples, o un solo agente para trabajo secuencial

La tecnología está en fase experimental, lo que significa:

• Funciona, pero no hay resumption de sesión con teammates in-process
• El estado de tareas puede retrasarse ocasionalmente
• La UI y herramientas seguirán mejorando rápidamente
• Los costos en tokens son significativos (4-5× una sesión normal)

Mi recomendación: Experimenta con Agent Teams para code review y debugging de issues complejos. Empieza con tareas de research sin código para familiarizarte con la mecánica. No los uses para tareas simples donde un solo agente basta.

Agent Teams no son una solución perfecta, pero son un paso tangible hacia un futuro donde equipos de agentes de IA colaboran tan fluidamente como equipos humanos.

---

Recursos:

• Documentación oficial de Agent Teams (en inglés)
• Comparison: Subagents vs Agent Teams (en inglés)
• Git Worktrees para sesiones paralelas manuales (en inglés)

Temas relacionados:

• Claude Cowork: Claude Code para el Resto de Tu Trabajo
• Sistema de Memoria de Claude Code: Gestión Jerárquica
• Claude Code 101: Setup y Fundamentos en PyCharm
• aOrchestra: Automatización Multi-Agente con Orquestación
• Introducción a Agentes de IA: Del Concepto a la Práctica

---

¿Has experimentado con Agent Teams o tienes dudas sobre cómo podrían aplicarse a tu workflow? Contáctame o conectemos en LinkedIn.