Guía completa de Claude Agent Teams

Introducción

Si ha utilizado los Subagent de Claude Code, probablemente considere que el desarrollo en paralelo ya es bastante poderoso. Sin embargo, los Subagent tienen una limitación: solo pueden reportar resultados al Agent principal, pero no pueden comunicarse entre sí.

Agent Teams cambia esto por completo. Imagine lo siguiente: un Agent se encarga de la auditoría de seguridad, otro de la optimización del rendimiento y un tercero de la cobertura de pruebas, y no solo pueden trabajar en paralelo, sino que también pueden dialogar directamente, desafiarse mutuamente y llegar a consensos. Este es el valor central de Agent Teams.

Comprender Agent Teams

La arquitectura de Agent Teams se asemeja mucho a un equipo de desarrollo real:

┌─────────────────────────────────────────────────────────┐
│                    Usted (usuario)                       │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                    Team Lead                             │
│        (Instancia principal de Claude, coordina)         │
└─────────────────────────────────────────────────────────┘
         │              │              │
         ▼              ▼              ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ Teammate 1  │  │ Teammate 2  │  │ Teammate 3  │
│ Aud. segur. │◄─►│ Opt. rendim. │◄─►│ Cob. pruebas │
└─────────────┘  └─────────────┘  └─────────────┘
         │              │              │
         └──────────────┼──────────────┘
                        ▼
              ┌─────────────────┐
              │ Lista de tareas │
              │   compartida    │
              └─────────────────┘

Diferencias con Subagent

En pocas palabras: Subagent es un contratista al que envía a ejecutar tareas; Agent Teams es un equipo de proyecto que colabora en la misma sala.

Por qué Agent Teams es efectivo

La idea clave: la especialización genera enfoque.

Cuando un único Agent maneja tareas complejas de múltiples pasos, el contexto crece constantemente y con frecuencia necesita reiniciarse con /clear. Agent Teams permite que cada Teammate mantenga un área de enfoque reducida, con un contexto limpio y un rendimiento más estable.

Habilitar Agent Teams

Agent Teams es actualmente una funcionalidad experimental, deshabilitada por defecto. Es necesario habilitarla manualmente:

Opción 1: Variable de entorno

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Opción 2: settings.json (recomendado, efecto permanente)

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

Uso principal

Crear su primer Agent Team

Una vez habilitado, simplemente indique a Claude en lenguaje natural que cree un equipo:

Crea un agent team para revisar el PR #142.
Genera tres revisores:
- Uno enfocado en problemas de seguridad
- Uno que verifique el impacto en el rendimiento
- Uno que valide la cobertura de pruebas
Que cada uno revise y reporte sus hallazgos.

Consejo sobre palabras clave: Use "create an agent team" o "spawn an agent team". Si solo dice "spawn agents", podría confundir Subagent con Agent Teams.

Modos de visualización

Agent Teams soporta dos modos de visualización:

El valor predeterminado es auto: si se ejecuta dentro de tmux se usan split panes, de lo contrario se usa in-process.

Configurar el modo de visualización:

{
  "teammateMode": "in-process"
}

Especificar para una sesión individual:

claude --teammate-mode in-process

Atajos de teclado

Delegate Mode (importante)

Delegate Mode es una de las funcionalidades más importantes de Agent Teams:

Por qué se necesita Delegate Mode:

Sin esta restricción, el Lead tiende a "acaparar el trabajo": aunque hay tres Teammates esperando para trabajar, el Lead comienza a escribir código por su cuenta. Al activar Delegate Mode, el Lead se ve forzado a ser un gerente de proyecto puro, pudiendo únicamente gestionar tareas, comunicarse con los Teammates y revisar los resultados.

# Presione Shift+Tab inmediatamente después de iniciar el equipo

Casos prácticos

Caso 1: Revisión de código en paralelo

Un único revisor tiende a profundizar demasiado en cierto tipo de problemas. Al dividir las dimensiones de revisión en áreas independientes, la seguridad, el rendimiento y la cobertura de pruebas reciben la misma atención:

Crea un agent team para revisar este PR. Genera tres revisores:
- Revisor de seguridad: verifica autenticación, autorización, vulnerabilidades de inyección
- Revisor de rendimiento: analiza complejidad algorítmica, consultas a base de datos, estrategias de caché
- Revisor de pruebas: valida cobertura de pruebas, condiciones límite, manejo de errores

Que revisen individualmente y luego discutan entre sí los problemas encontrados.

Caso 2: Depuración con hipótesis competitivas

Cuando la causa raíz no está clara, un único Agent tiende a encontrar una explicación aparentemente razonable y detenerse. Hacer que los Teammates se desafíen mutuamente evita este problema:

Los usuarios reportan que la aplicación se cierra después de enviar un mensaje,
en lugar de mantener la conexión.

Genera 5 agent teammates para investigar diferentes hipótesis. Que discutan entre sí,
intenten refutar las teorías de los demás, como en un debate científico.
Actualicen los hallazgos consensuados en el informe de investigación.

Mecanismo clave: estructura de debate. Múltiples investigadores independientes intentan activamente refutar las teorías de los demás; las hipótesis que sobreviven tienen más probabilidades de ser la verdadera causa raíz.

Caso 3: Producción de contenido en masa

Esta es una aplicación típica para tareas no técnicas: transformar una entrada en múltiples salidas:

Crea un agent team para convertir este guion de video en contenido para cuatro plataformas:
- Autor de artículo para LinkedIn
- Autor de hilo para Twitter
- Autor de newsletter
- Autor de artículo de blog

Ubicación del guion: /content/scripts/video-20.md

Cada Teammate crea de forma independiente, pero manteniendo la coherencia del contenido.

Caso 4: Clúster de verificación de calidad QA

Una verificación de calidad para un sitio web de blog, desplegando 5 Agents para probar diferentes aspectos en paralelo:

Crea un agent team para una verificación de calidad integral del blog:
- Agent 1: pruebas de páginas principales (inicio, acerca de, contacto)
- Agent 2: pruebas de páginas de artículos (renderizado, navegación, metadatos SEO)
- Agent 3: verificación de enlaces (internos, externos, enlaces rotos)
- Agent 4: validación SEO (títulos, descripciones, datos estructurados)
- Agent 5: pruebas de accesibilidad (etiquetas ARIA, contraste, navegación por teclado)

Genera un informe de problemas ordenado por prioridad.

Resultado: en cuestión de minutos se completa una verificación integral que normalmente requeriría ejecución secuencial manual. Cada Agent se enfoca en su propia área y al final se consolida en una lista de problemas ordenada por prioridad.

Caso 5: Modo de discusión en múltiples rondas

Un patrón de prompt útil: hacer que los Teammates discutan como en una reunión:

Usa Agent Teams para crear 4 teammates que discutan [decisión técnica],
realizando 3 rondas de discusión. Que los teammates intercambien opiniones en cada ronda.
Uno de los teammates debe encargarse específicamente de la perspectiva Red Team, planteando críticas.

Este patrón es especialmente adecuado para escenarios que requieren evaluar múltiples perspectivas, como decisiones de arquitectura y selección de tecnología.

Caso 6: Proyecto del compilador de C

Anthropic utilizó 16 Agents para construir desde cero un compilador de C capaz de compilar el kernel de Linux:

Resultado final: un compilador en Rust capaz de construir Linux 6.9 arrancable en x86, ARM y RISC-V.

Gestión del equipo

Especificar Teammates y modelos

Claude decide automáticamente cuántos Teammates generar según la tarea, pero usted también puede especificarlo explícitamente:

Crea 4 teammates para refactorizar estos módulos en paralelo.
Cada teammate debe usar el modelo Sonnet.

Solicitar aprobación del plan

Para tareas complejas o de alto riesgo, puede requerir que los Teammates elaboren un plan antes de ejecutar:

Genera un teammate arquitecto para refactorizar el módulo de autenticación.
Antes de que hagan cualquier cambio, requiere aprobación del plan.

El Teammate envía una solicitud de aprobación al Lead después de completar el plan. El Lead puede aprobarlo o devolver observaciones para modificación.

Comunicarse directamente con los Teammates

Cada Teammate es una sesión completa de Claude Code. Usted puede enviar mensajes directamente a cualquier Teammate:

• Modo in-process: cambie con Shift+Down y luego escriba el mensaje
• Modo split-pane: haga clic directamente en el panel correspondiente

Cerrar Teammates

Por favor cierra el teammate de auditoría de seguridad

El Lead envía una solicitud de cierre, y el Teammate puede aprobarla o rechazarla (explicando el motivo).

Limpiar el equipo

Al finalizar, permita que el Lead limpie los recursos:

Limpia el equipo

Importante: siempre limpie a través del Lead. No permita que los Teammates ejecuten la limpieza, ya que podría causar inconsistencia en el estado de los recursos.

Mejores prácticas

Control del tamaño del equipo

Recomendaciones de tamaño:

Regla general: asignar 5-6 tareas a cada Teammate es adecuado. Si tiene 15 tareas independientes, 3 Teammates es un buen punto de partida.

Granularidad de las tareas

• Demasiado pequeñas: la sobrecarga de coordinación supera los beneficios
• Demasiado grandes: los Teammates trabajan demasiado tiempo sin puntos de control, aumentando el riesgo de desperdicio
• Adecuadas: unidades de trabajo independientes y completas con resultados claros (una función, un archivo de pruebas, un informe de revisión)

Evitar conflictos de archivos

Dos Teammates editando el mismo archivo provocarán sobrescrituras. Al dividir el trabajo, asegúrese de que cada Teammate sea responsable de un conjunto diferente de archivos:

Teammate 1: responsable del directorio src/auth/
Teammate 2: responsable del directorio src/api/
Teammate 3: responsable del directorio src/utils/

Monitoreo y orientación

Verifique periódicamente el progreso de los Teammates y corrija las direcciones inadecuadas a tiempo. Dejar que el equipo se ejecute sin supervisión durante demasiado tiempo aumenta el riesgo de desperdicio.

Si el Lead comienza a implementar tareas por sí mismo en lugar de esperar a los Teammates:

Espera a que tus teammates completen sus tareas antes de continuar

Proporcionar suficiente contexto

Los Teammates cargan automáticamente el contexto del proyecto (CLAUDE.md, MCP servers, Skills), pero no heredan el historial de conversación del Lead. Proporcione suficientes detalles de la tarea al generarlos:

Genera un teammate de auditoría de seguridad con el siguiente prompt:
"Revisa las vulnerabilidades de seguridad del módulo de autenticación en src/auth/.
Enfócate en el manejo de tokens, gestión de sesiones y validación de entradas.
La aplicación usa JWT tokens almacenados en httpOnly cookies.
Al reportar hallazgos, incluye una calificación de severidad."

Patrón de verificación con auto-reporte

Incluya criterios de verificación claros en la descripción de la tarea para asegurar que los Teammates se auto-verifiquen al completarla:

Al completar la tarea, reporta al Lead:
1. Qué archivos revisaste
2. Qué problemas encontraste
3. Qué modificaciones realizaste
4. Si se cumplieron los criterios de verificación (pruebas pasaron, lint sin advertencias, etc.)

Este patrón reduce la carga de verificación del Lead y al mismo tiempo asegura que la tarea esté realmente completada y no solo "aparentemente completada".

Técnicas avanzadas

Usar Hooks para imponer puertas de calidad

Mediante Hooks, puede imponer reglas cuando los Teammates completen su trabajo:

{
  "hooks": {
    "TeammateIdle": [
      {
        "command": "your-validation-script.sh"
      }
    ],
    "TaskCompleted": [
      {
        "command": "your-quality-check.sh"
      }
    ]
  }
}

• TeammateIdle: se ejecuta cuando un Teammate está a punto de quedar inactivo. Devolver exit code 2 envía retroalimentación y hace que el Teammate continúe trabajando
• TaskCompleted: se ejecuta cuando una tarea se marca como completada. Devolver exit code 2 puede bloquear la finalización y enviar retroalimentación

Pre-aprobación de permisos

Las solicitudes de permisos de los Teammates se propagan al Lead, lo que puede causar interrupciones frecuentes. Pre-apruebe las operaciones comunes antes de generarlos:

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Write(src/**)",
      "Bash(npm test)"
    ]
  }
}

Combinación con Worktree

Agent Teams puede usarse junto con Worktree, donde cada Teammate trabaja en su propio worktree:

Crea un agent team donde cada teammate trabaje en un worktree independiente,
para evitar conflictos de archivos.

Herramientas de orquestación de terceros

Además del Agent Teams nativo, la comunidad también ha desarrollado algunas herramientas de orquestación:

Estas herramientas ofrecen alternativas fuera de la funcionalidad experimental de Agent Teams, pero requieren más configuración manual. Si el Agent Teams nativo satisface sus necesidades, se recomienda priorizar la funcionalidad oficial.

Limitaciones actuales

Agent Teams sigue siendo una funcionalidad experimental; es importante conocer sus limitaciones:

Consideraciones de costo

El consumo de tokens de Agent Teams es significativamente mayor que el de una sesión individual:

Análisis de costos:

• Cada Teammate es una instancia completamente independiente de Claude con su propio contexto
• La comunicación entre Teammates también consume tokens
• El Lead necesita coordinar a todos los Teammates, lo que genera costos adicionales

Cuándo vale la pena:

• Vale la pena para tareas de investigación que requieren exploración en paralelo
• Vale la pena para revisiones multiperspectiva (seguridad, rendimiento, pruebas)
• Vale la pena para decisiones que requieren discusión y consenso
• No vale la pena para tareas rutinarias que pueden completarse secuencialmente
• No vale la pena para tareas paralelas que no necesitan comunicación entre sí (usar Subagent es más económico)

Mi experiencia de uso

Cuándo usar Agent Teams

Mis criterios de decisión:

1. La tarea requiere múltiples perspectivas: conocimiento especializado de diferentes áreas (seguridad + rendimiento + pruebas)
2. Se necesita discusión y consenso: hipótesis competitivas, decisiones de arquitectura
3. La exploración en paralelo tiene valor: comparación de múltiples enfoques de implementación

Si solo necesita ejecución en paralelo sin comunicación mutua, Subagent o Worktree son más adecuados.

Comience con investigación y revisión

Si es nuevo en Agent Teams, comience con tareas que no requieran escribir código: revisar PRs, investigar soluciones técnicas, investigar bugs. Estas tareas tienen límites claros, demuestran el valor de la exploración en paralelo y al mismo tiempo evitan los desafíos de coordinación de la implementación en paralelo.

Combinación con otras funcionalidades

Conclusión

Agent Teams representa un nuevo paradigma en el desarrollo asistido por IA: de "un asistente de IA" a "un equipo de IA".

Anthropic utilizó 16 Agents durante 2 semanas, con un costo de $20,000, para escribir un compilador de C de 100 mil líneas de código. La lección clave de este proyecto es: la calidad de las pruebas es lo más importante de todo. Los Agents resolverán autónomamente el problema que usted les asigne, por lo que el validador de tareas debe ser casi perfecto; de lo contrario, los Agents resolverán el problema equivocado.

Recuerde tres puntos clave:

Comenzar es sencillo:

Crea un agent team para [su tarea]

Lecturas relacionadas:

• Guía completa de Claude Worktree -- Comprender la combinación de Worktree con Agent Teams
• Guía completa de Claude Subagent -- Comparar los casos de uso de Subagent y Agent Teams
• Guía rápida de inicio de Tmux -- Usar Tmux para gestionar múltiples sesiones de Agent

Materiales de referencia:

• Claude Code Official Documentation - Agent Teams
• Building a C compiler with a team of parallel Claudes
• Claude Code Agent Teams: The Complete Guide
• Multi-Agent Orchestration: Running 10+ Claude Instances in Parallel

Tutoriales en video:

• 7 Unexpected Use Cases for Claude Code Agent Teams -- 7 demostraciones de casos de uso no técnicos
• Claude Code Multi-Agent Workflows -- Explicación detallada de flujos de trabajo multiagente
• Agent Teams Orchestration Deep Dive -- Análisis profundo de orquestación de equipos
• Claude Code Agent Teams Setup Guide -- Tutorial completo de configuración