$ man how-to/agent-teams-claude-code

Los Equipos de Agentes son sesiones de Claude Code que pueden comunicarse entre sí. Las entradas anteriores de agentes paralelos en esta guía cubren los subagentes, que son de tipo disparar-y-olvidar. Lanzas un subagente, hace su tarea, reporta al padre. Eso es todo. No hay comunicación entre subagentes. No hay seguimiento de tareas compartido. No hay coordinación más allá de lo que el padre orquesta. Los Equipos de Agentes agregan tres cosas que los subagentes no tienen. Primero, una lista de tareas compartida que cada miembro del equipo puede leer y actualizar. Segundo, mensajería directa entre agentes, no solo de padre a hijo sino de par a par. Tercero, gestión del ciclo de vida para que el líder del equipo pueda crear, asignar, monitorear y cerrar miembros del equipo desde una sola sesión. La diferencia práctica: los subagentes son buenos para tareas paralelas independientes donde ningún agente necesita saber qué está haciendo otro agente. Los equipos son buenos para tareas paralelas coordinadas donde los agentes necesitan traspasar contexto, verificar el trabajo del otro o adaptarse basándose en lo que un compañero descubrió. Si alguna vez has gestionado un pequeño equipo de personas, el modelo mental es idéntico. Asignas tareas, las personas trabajan en paralelo, te envían mensajes con preguntas, revisas la salida y decides cuándo el trabajo está terminado.

CODE

Los Equipos de Agentes son experimentales a partir de febrero 2026. Habilítalos agregando la variable de entorno a tu configuración de Claude Code: En ~/.claude/settings.json: { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } } Reinicia Claude Code después de agregar esto. La característica no se activará hasta la siguiente sesión. Una vez habilitado, puedes pedirle a Claude que cree un equipo naturalmente o sucede a través de la herramienta TeamCreate. Un equipo obtiene un nombre, una descripción y un archivo de configuración en ~/.claude/teams/{team-name}/config.json. La configuración rastrea los miembros del equipo con sus nombres, IDs de agente y roles. Cada equipo obtiene una lista de tareas correspondiente en ~/.claude/tasks/{team-name}/. Este es el rastreador de trabajo compartido que cada miembro del equipo puede leer y escribir. Los modos de visualización importan. El predeterminado es in-process, donde todos los miembros del equipo se ejecutan en la terminal principal y usas Shift+Down para alternar entre ellos. Si tienes tmux o iTerm2, configura "teammateMode": "tmux" en settings.json y cada miembro del equipo obtiene su propio panel dividido. La vista de panel facilita monitorear trabajo paralelo. También puedes pasar --teammate-mode en la línea de comandos para sesiones únicas.

PATTERN

Las tareas son la columna vertebral de la coordinación. Cada pieza de trabajo obtiene una tarea con un asunto, descripción, estado (pending, in_progress, completed) y dependencias opcionales. Las dependencias son la característica clave. La Tarea 4 puede estar bloqueada por las Tareas 2 y 3. Eso significa que nadie toma la Tarea 4 hasta que ambas 2 y 3 estén terminadas. Esto aplica la disciplina de oleadas automáticamente. No necesitas supervisar la secuenciación. La lista de tareas la aplica. El flujo de trabajo: el líder del equipo crea tareas, establece dependencias y asigna responsables. Los miembros del equipo revisan la lista de tareas después de completar cada pieza de trabajo para encontrar qué está disponible a continuación. Reclaman tareas desbloqueadas, las trabajan, las marcan como completas y buscan la siguiente. Consejo: prefiere asignar tareas en orden de ID (primero las más bajas) cuando hay múltiples disponibles. Las tareas anteriores frecuentemente establecen contexto del que las tareas posteriores dependen. Este es el mismo patrón de oleadas de la guía de agentes paralelos, solo formalizado en un sistema de tareas en lugar de orquestación manual.

PATTERN

Los miembros del equipo se comunican a través de SendMessage. Existen tres tipos de mensajes. Los mensajes directos van a un miembro específico del equipo por nombre. El investigador envía hallazgos al líder del equipo. El escritor le hace una pregunta al revisor. Estos son los más comunes y los mensajes más económicos. Los broadcasts van a todos los miembros del equipo a la vez. Úsalos con moderación porque cada broadcast envía un mensaje separado a cada agente, lo que significa que N miembros del equipo equivalen a N llamadas de API. Uso válido: un bloqueador crítico que afecta a todos. Uso inválido: una actualización de estado que solo le importa al líder. Las solicitudes de shutdown le dicen a un miembro del equipo que termine y salga. El miembro del equipo puede aprobar (y terminar) o rechazar con una razón. Así es como terminas limpiamente una sesión de equipo sin matar procesos. Los mensajes se entregan automáticamente. No necesitas consultar una bandeja de entrada. Cuando un miembro del equipo envía un mensaje, llega a tu conversación como un nuevo turno. Si estás ocupado a mitad de turno, los mensajes se encolan y se entregan cuando tu turno termine.

PRO TIP

Los agentes no son el avance. La capa de gestión lo es. Sin restricciones, los agentes paralelos crean caos. Dos agentes editan el mismo archivo y la última escritura gana silenciosamente. Un agente toma una decisión arquitectónica que conflictúa con la suposición de otro agente. Un despliegue sale antes de que todos los agentes terminen. La capa de gestión es un archivo de restricciones que cada miembro del equipo lee antes de hacer cualquier cambio. Mi TEAM-CONSTRAINTS.md aplica seis reglas: 1. Propiedad de archivos. Un escritor por archivo por oleada. No dos agentes tocan el mismo archivo simultáneamente. 2. Registro de decisiones. Cuando un agente toma una decisión (convención de nombres, ruta de importación, estructura de datos), envía un mensaje al líder del equipo con un prefijo [DECISION]. Esa decisión se hace disponible para todos los miembros del equipo. 3. Leer antes de escribir. Cada agente lee un ejemplo existente de lo que está por crear. El código existente ES la guía de estilo. 4. Disciplina de oleadas. Tareas de fundación primero, consumidores segundo, integración tercero, validación al final. No se salta adelante. 5. Puerta de build. No se despliega hasta que el build pase limpio y el líder del equipo confirme. 6. Contexto antes de acción. Cada miembro del equipo recibe el archivo de restricciones, una descripción específica de la tarea, referencias a archivos y límites de propiedad. Si falta alguno, el agente pregunta antes de proceder. No necesitas mi archivo de restricciones exacto. Necesitas UN archivo de restricciones. Las reglas específicas importan menos que tener reglas. Sin ellas, los agentes divagan. Con ellas, los agentes se coordinan.

FORMULA

Usa subagentes (la herramienta Task) cuando las tareas son completamente independientes. Ningún agente necesita la salida de otro agente. Ningún agente necesita verificar el trabajo de otro agente. Cada tarea tiene una entrada clara y una salida clara sin dependencias cruzadas. Ejemplo: tres agentes cada uno escribiendo una página wiki separada que no referencia a las otras. Usa equipos cuando las tareas son coordinadas. Los agentes necesitan traspasar contexto. La salida de un agente alimenta la entrada de otro agente. Alguien necesita revisar antes de que el siguiente paso comience. Ejemplo: un investigador recopila datos, un escritor los convierte en contenido, un revisor verifica el cumplimiento de la voz, y un agente de despliegue hace push del resultado. La diferencia de costo importa. Los equipos usan aproximadamente 7x más tokens que una sola sesión porque cada miembro del equipo ejecuta su propia ventana de contexto. Mantén los equipos pequeños (2 a 4 agentes), mantén las tareas enfocadas y limpia cuando termines. No crees un equipo para una tarea que un solo agente enfocado puede manejar. Limitaciones actuales a conocer: un equipo por sesión, no hay equipos anidados (los miembros del equipo no pueden crear sus propios equipos), el rol de líder es fijo (no se puede transferir el liderazgo a mitad de sesión), y la reanudación de sesión no funciona con miembros del equipo in-process. Estas son restricciones experimentales que probablemente mejorarán. El marco de decisión: si puedes describir la tarea en un solo prompt y el agente puede terminar sin preguntarle a nadie, usa un subagente. Si la tarea involucra traspasos, revisiones o coordinación de múltiples pasos, usa un equipo.