Coordina 3–5 agentes con Claude Code para ingenieros

Un equipo de agentes en Claude Code es un conjunto de sesiones coordinadas (un lead y varios teammates) que trabajan sobre el mismo objetivo con visibilidad compartida entre ellas. Para activarlos necesitas la variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS y una versión de Claude Code igual o posterior a la v2.1.32. Su mejor uso no es acelerar tareas triviales, sino repartir trabajo genuinamente paralelo: refactors simultáneos en módulos distintos, debugging con hipótesis contrapuestas o una pre-revisión de PR antes de que llegue a un humano.

---

En resumen:

• Los equipos de agentes en Claude Code deben usarse solo para tareas paralelas complejas y no para trabajos triviales, ya que incrementan el consumo de tokens.
• Es recomendable limitar el número de teammates a entre 3 y 5 para mantener un equilibrio entre eficiencia y coste, asegurándose de tener procesos claros.
• La coordinación efectiva requiere el uso de un CLAUDE.md, plantillas de revisión y registros detallados de los cambios realizados.
• Los costos aumentan linealmente con la cantidad de teammates, por lo que conviene evitar conflictos de archivos y usar herramientas como git worktrees para el aislamiento.

---

Tabla de contenidos

• Qué es un equipo de agentes en Claude Code y cómo se organiza
• Equipos de agentes frente a subagents: cuándo usar cada uno
• Cómo habilitar los equipos de agentes en tu entorno
• Cómo lanzar tu primer equipo sin romper nada
• Buenas prácticas: CLAUDE.md, plantillas y controles de revisión
• Permisos, hooks y manejo de secretos: la parte que no puedes saltarte
• Cuánto cuesta realmente y qué límites tiene hoy
• Artefacts como salida compartible del trabajo del equipo
• Qué hacer cuando algo falla: soluciones a los fallos más comunes
• Qué muestran los casos reales sobre el ahorro operativo
• Cuándo apostar por equipos de agentes y cuándo esperar
• agent-swarm.dev como capa de orquestación para equipos que ya usan Claude Code
• Fuentes
• Preguntas frecuentes

Qué es un equipo de agentes en Claude Code y cómo se organiza

Un equipo tiene una jerarquía sencilla: un agente lead que reparte trabajo y varios teammates que lo ejecutan. El lead no escribe código directamente en la mayoría de los flujos; interpreta el objetivo, lo descompone en tareas y decide qué teammate se encarga de cada una. Los teammates, por su parte, trabajan de forma semiautónoma y reportan avances sin que el humano tenga que microgestionar cada paso.

La coordinación ocurre a través de dos mecanismos concretos. El mailbox es el canal de mensajería interno donde los teammates avisan al lead (o entre ellos) cuando terminan una subtarea, encuentran un bloqueo o necesitan una decisión. La task list es el tablero compartido que muestra qué está pendiente, en curso o completado, y sirve como fuente de verdad cuando varias sesiones tocan el mismo repositorio.

A eso se suman los artefacts, salidas persistentes que el equipo genera y actualiza en tiempo real: un resumen de PR, un informe de incidente, un panel de progreso. Anthropic presentó artefactos autoactualizables que mantienen historial de versiones, disponibles en beta para organizaciones con planes Team y Enterprise.

Cómo ves todo esto en pantalla depende del modo de visualización:

• In-process: todos los teammates corren dentro de la misma terminal, útil para pruebas rápidas con pocos agentes.
• tmux: cada teammate ocupa un panel independiente dentro de una sesión multiplexada, ideal para seguir varios hilos de trabajo a la vez.
• Split panes: divide la ventana del editor o terminal en secciones, aunque no funciona igual en todos los emuladores de terminal.

Equipos de agentes frente a subagents: cuándo usar cada uno

La diferencia central no es de potencia sino de topología de comunicación. En un equipo de agentes, los teammates pueden hablar directamente entre sí a través del mailbox: uno puede avisar a otro que ha cambiado una interfaz antes de que rompa su trabajo. En un esquema de subagents, la comunicación es jerárquica y centralizada: cada subagente reporta al agente principal, y ese agente decide qué hacer con la información, sin conversación lateral entre subagentes.

Esa diferencia se traduce en costes. Cada teammate de un equipo es una sesión completa de Claude Code, con su propio consumo de tokens. Un subagente suele consumir menos porque opera dentro de un contexto más acotado y con menos overhead de coordinación.

• Usa equipos de agentes cuando las tareas son verdaderamente paralelas, cuando quieres contrastar hipótesis distintas sobre un mismo bug, o cuando necesitas una pre-revisión cruzada antes de que un PR llegue a revisión humana.
• Usa subagents para tareas secuenciales, dependientes entre sí, o cuando el presupuesto de tokens es una restricción real y no puedes justificar el coste de tres o cuatro sesiones simultáneas.

Mezclar ambos modelos en el mismo flujo casi nunca compensa: la complejidad de coordinar sube más rápido que el beneficio.

Cómo habilitar los equipos de agentes en tu entorno

Antes de lanzar tu primer equipo, verifica cuatro cosas en este orden:

1. Comprueba la versión instalada. Los equipos de agentes existen solo desde la versión v2.1.32 de Claude Code. Si tienes una versión anterior, actualiza antes de tocar nada más.
2. Activa el flag experimental. Añade CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 en tu settings.json o expórtalo como variable de entorno en la shell que uses para lanzar Claude Code. Está deshabilitado por defecto porque la función sigue en fase experimental.
3. Confirma tu tipo de acceso. Claude Code se incluye en los asientos de los planes Team y Enterprise; los asientos Premium dan más margen de uso para cargas intensivas, y la facturación en Enterprise puede variar según el tipo de asiento contratado.
4. Prepara el aislamiento de archivos. Antes de lanzar más de un teammate sobre el mismo repositorio, decide cómo vas a separar el trabajo físicamente.

Consejo profesional: usa git worktrees para correr entre 3 y 5 sesiones en paralelo, cada una en su propia carpeta de trabajo apuntando a la misma base de código. Es la recomendación de Anthropic para usuarios avanzados y evita que dos teammates pisen el mismo archivo sin darse cuenta.

Cómo lanzar tu primer equipo sin romper nada

El primer equipo debería ser pequeño y acotado a un objetivo con límites claros, no un experimento abierto sobre todo el repositorio.

1. Define el objetivo y pide el número de teammates. Un prompt como "crea un equipo de 3 teammates para migrar estos tres módulos a la nueva API" hace que el lead genere automáticamente la task list y abra el mailbox.
2. Asigna archivos o directorios por teammate. Reparte el trabajo de forma que cada sesión toque una carpeta distinta; es la forma más simple de evitar sobrescrituras cuando varias sesiones corren en paralelo.
3. Trabaja sobre ramas o worktrees separados. Cada teammate debe operar sobre su propia rama, nunca directamente sobre main.
4. Ejecuta tests y lint antes de aceptar cualquier cambio. No hay atajo aquí: cada rama que produzca un teammate pasa por la misma suite de verificación que pasaría un PR humano.

Antes de fusionar, exige una plantilla mínima de PR con un recibo de revisión que incluya:

• Qué archivos tocó cada teammate y por qué.
• Qué comandos se autorizaron a ejecutar (build, tests, migraciones).
• Qué pruebas se corrieron y con qué resultado.
• Quién dio la aprobación humana final.

Sin ese recibo, un equipo de agentes se convierte rápido en una caja negra que nadie quiere depurar seis meses después.

Buenas prácticas: CLAUDE.md, plantillas y controles de revisión

Un archivo CLAUDE.md en la raíz del repositorio es el punto de partida para que cualquier teammate entienda las convenciones del proyecto sin que tengas que repetirlas en cada prompt. Guías comunitarias como ClaudeCodeLab recomiendan incluir ahí las reglas de estilo, los comandos de build y test, y las rutas que están fuera de límites para la edición automática.

Además del CLAUDE.md, conviene fijar plantillas reutilizables para tres momentos críticos:

• Traspaso entre sesiones: qué contexto debe llevarse un teammate nuevo que retoma el trabajo de otro.
• Pre-revisión de PR: un resumen estructurado que el equipo genera antes de pedir revisión humana.
• Manejo de incidentes: qué información captura el equipo cuando algo falla en producción.

El recibo de revisión necesita campos mínimos no negociables: qué se revisó, qué comandos quedaron autorizados durante la sesión y qué pruebas se ejecutaron con su resultado exacto. Sin esos tres datos, cualquier auditoría posterior se vuelve adivinación.

Consejo profesional: diseña un checklist de incorporación de 30 minutos para quien se une al equipo: leer el CLAUDE.md, revisar la última task list cerrada, y lanzar un equipo de prueba de un solo teammate sobre una rama descartable. Es tiempo bien invertido antes de dejar que alguien coordine cinco sesiones a la vez.

Puedes apoyarte en agentes de revisión de código integrados en CI para automatizar parte de esa comprobación previa al merge.

Permisos, hooks y manejo de secretos: la parte que no puedes saltarte

El principio operativo debe ser negar por defecto y permitir lo mínimo imprescindible. En .claude/settings.json, define primero qué comandos y rutas están bloqueados, y solo después añade excepciones puntuales para lo que el equipo necesita ejecutar.

Los hooks del ciclo de vida ayudan a mantener control sin frenar el trabajo:

• TaskCreated: dispara una notificación cuando el lead abre una nueva tarea, útil para auditoría en tiempo real.
• TaskCompleted: permite ejecutar automáticamente los tests antes de marcar algo como terminado.
• TeammateIdle: avisa cuando un teammate queda sin trabajo asignado, evitando sesiones que consumen recursos sin producir nada.

Antes de pasar logs o mensajes de error a cualquier sesión, sanitízalos: elimina tokens de API, credenciales de base de datos y cualquier dato de cliente que pudiera aparecer en una traza de error. Y establece una política sin excepciones: ningún merge a producción ni cambio sobre infraestructura sensible se aprueba sin que un humano lo revise, sin importar cuántas capas de pre-revisión haya hecho el propio equipo de agentes.

Cuánto cuesta realmente y qué límites tiene hoy

Cada teammate es una sesión completa de Claude Code, no una llamada ligera. Si lanzas un equipo de cuatro teammates para una tarea de dos horas, el consumo de tokens se multiplica por cuatro respecto a una sesión individual, incluso cuando el trabajo total realizado no crece en la misma proporción.

Reportes de comunidad describen un punto óptimo operativo de entre 3 y 5 teammates con 5 o 6 tareas cada uno: suficiente para generar debate útil entre hipótesis sin disparar el gasto de forma desproporcionada.

La función sigue marcada como experimental, así que espera cambios en la API y comportamientos que se ajusten entre versiones sin previo aviso extenso.

Hay limitaciones conocidas que conviene asumir desde el principio:

• /resume no siempre restaura correctamente a los teammates de una sesión anterior.
• Los conflictos de archivo entre teammates que no tienen su trabajo bien delimitado son el fallo más común reportado.
• Split panes no funciona de forma consistente en todos los emuladores de terminal.

Si el presupuesto de tokens es ajustado, la alternativa razonable es reducir el número de teammates o volver a un esquema de subagents para las partes secuenciales del trabajo, como se explora en este análisis sobre densidad de agentes.

Artefacts como salida compartible del trabajo del equipo

Un artefact bien usado convierte una sesión efímera en un documento vivo que sobrevive a la conversación que lo generó. Los tres tipos más útiles en un flujo de desarrollo son un resumen de PR con los cambios y su justificación, un informe de incidente con la cronología de lo ocurrido, y un panel de progreso que muestra el estado de la task list en tiempo real.

El beneficio principal es la trazabilidad: cualquier persona del equipo puede abrir ese enlace vivo semanas después y entender qué se decidió sin reconstruir la conversación completa. La verificación humana se vuelve más rápida porque el artefact ya organiza la información en lugar de dejarla dispersa en el historial del chat.

• Enlaza el artefact directamente desde la descripción del PR, no solo desde el canal de chat del equipo.
• Trata el panel de progreso como parte de la documentación del repositorio, no como algo descartable al cerrar la tarea.

Qué hacer cuando algo falla: soluciones a los fallos más comunes

Cuando una sesión de teammate se cierra sin aviso, no reanudes a ciegas: revisa la task list para ver qué quedó a medio terminar y vuelve a lanzar ese teammate específico con instrucciones que referencien el trabajo ya hecho por sus compañeros. /resume no garantiza restaurar el estado completo del equipo, así que trata cada re-spawn como si fuera una incorporación nueva con contexto reducido.

Las sobrescrituras entre teammates casi siempre vienen de una asignación de archivos poco clara. La solución no es técnica sino de proceso: reparte carpetas completas, no archivos sueltos dentro de la misma carpeta, y usa git worktrees para que cada sesión tenga su propio directorio de trabajo físico.

Si split panes no responde bien en tu terminal, cambia a tmux o a un emulador como iTerm2, que gestionan mejor múltiples paneles activos simultáneamente; la wiki oficial de tmux documenta configuraciones probadas para este tipo de flujo.

• Deja evidencia de cada re-spawn en el PR: qué falló, qué teammate se relanzó y con qué contexto.
• Revisa el diff completo antes de aceptar, no solo el resumen que genera el propio equipo.

Consejo profesional: guarda una copia de la task list en el momento del fallo antes de relanzar nada. Es la única forma de reconstruir qué se perdió si el re-spawn no recupera el estado anterior.

Qué muestran los casos reales sobre el ahorro operativo

El caso de estudio de Capchase ilustra cómo un equipo de ingeniería estructuró la delegación de tareas recurrentes entre agentes especializados en lugar de repartirlas manualmente entre personas, liberando tiempo de revisión humana para las decisiones que realmente lo requerían.

El patrón que se repite en implementaciones exitosas no es "más agentes", sino menos llamadas a herramientas por tarea gracias a una asignación más precisa desde el inicio.

Integraciones con Slack, Linear y GitHub son las que más impacto tienen en la práctica: permiten que los traspasos entre teammates y humanos queden documentados donde el equipo ya trabaja, sin obligar a nadie a abrir una herramienta nueva solo para seguir el estado de una tarea.

Antes de escalar de un piloto a uso generalizado, comprueba:

• Que el recibo de revisión se está completando de forma consistente, no solo en las primeras semanas.
• Que el coste por sesión multiplicado por el número de teammates sigue siendo justificable frente al tiempo ahorrado.
• Que ningún merge sensible se ha aprobado sin revisión humana documentada.

Cuándo apostar por equipos de agentes y cuándo esperar

La conveniencia real depende de tres señales: frecuencia de cambios en el repositorio, tamaño del equipo humano disponible para revisar, y cobertura de tests. Sin una suite de pruebas decente, un equipo de agentes solo acelera la producción de errores.

La adopción sensata avanza en fases: primero un piloto acotado con un solo objetivo bien definido, después políticas escritas de permisos y revisión, y solo entonces un escalado controlado a más proyectos. Si notas que los recibos de revisión se están saltando, que los conflictos de archivo se repiten cada semana, o que nadie puede explicar qué autorizó un merge concreto, es señal de frenar y ajustar el proceso, no de añadir más teammates para compensar.

— Ez.-

agent-swarm.dev como capa de orquestación para equipos que ya usan Claude Code

Existen herramientas que resuelven lo que un equipo de agentes de Claude Code no cubre por sí solo: memoria compartida que se acumula entre sesiones y objetivos, en lugar de reiniciar contexto cada vez que lanzas un equipo nuevo. Un agente principal descompone objetivos complejos y delega subtareas a trabajadores especializados dentro de contenedores aislados, con integraciones hacia diversas plataformas.

El proyecto puede autohospedarse gratis para siempre bajo licencia MIT, con una versión Cloud de pago por suscripción que escala según el número de trabajadores activos, y modalidades enterprise con despliegue on-premise para equipos que lo necesitan. Si ya coordinas equipos de agentes dentro de Claude Code y buscas que ese trabajo persista, se documente y se conecte con las herramientas que tu organización ya usa, revisa los ejemplos de sesiones reales o consulta la comparativa de enfoques de orquestación para decidir si conviene sumar esta capa a tu flujo actual.

Fuentes

• Orquestar equipos de sesiones de Claude Code
• Usa Claude Code con tu plan de Team o Enterprise
• Consejos de usuario avanzado de Claude Code

Preguntas frecuentes

¿Cuánto cuesta usar Claude Code en equipos?

Claude Code se incluye dentro de cada asiento de los planes Team y Enterprise, sin coste adicional por activar equipos de agentes; el gasto real viene del consumo de tokens multiplicado por el número de teammates que lances en cada sesión.

¿Cómo controlar Claude Code desde el móvil?

Claude Code está pensado para operarse desde terminal o IDE en un ordenador; no existe un modo oficial de gestionar equipos de agentes completos desde una aplicación móvil, aunque puedes revisar notificaciones de integraciones como Slack desde el teléfono.

¿Cómo se usa Claude Code para programar en equipo?

Se activa el flag experimental de equipos de agentes, se define un objetivo claro para el lead, se asignan archivos o carpetas distintas a cada teammate y se exige un recibo de revisión antes de fusionar cualquier cambio a la rama principal.

¿Cómo instalo Claude Code en mi ordenador?

Se instala siguiendo la documentación oficial de Anthropic según tu sistema operativo; para usar equipos de agentes necesitas además la versión v2.1.32 y activar CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS en la configuración.

¿Cuántos teammates conviene lanzar a la vez?

La práctica recomendada por la comunidad es entre 3 y 5 teammates con 5 o 6 tareas cada uno, un rango que permite contraste de hipótesis sin disparar el coste por tokens de forma desproporcionada.

Recomendaciones

• Agentes de revisión de código para equipos de ingeniería: Comprobaciones PR multi-agente listas para CI
• Evaluaciones de agentes: Un marco práctico para ingenieros
• Tu flujo de trabajo de IA tiene demasiados agentes
• Los sistemas multi-agente reproducen todos los anti-patrones organizacionales que ya odias