Configurar agent teams en Claude Code, varias sesiones que se ayudan entre sí

Los subagents quizá ya los conoces. Le das al agente principal una tarea, este genera un worker enfocado, ese worker trabaja en su propio contexto y al final devuelve un resultado. Funciona bien para encargos acotados. Los agent teams son otra cosa. Aquí corren a la vez varias sesiones completas de Claude Code, cada una con su propia ventana de contexto, y hablan entre ellas directamente en vez de solo informar al jefe. Una sesión es el team lead, coordina, reparte tareas y resume al final. Las demás son teammates y pueden contradecirse, probar hipótesis, intercambiar hallazgos. La funcionalidad es experimental y está desactivada por defecto. Este playbook enseña cómo la activo y cuándo compensa el consumo de tokens bastante mayor.

1. Entender cuándo un equipo es mejor que un subagent

El paso más importante ocurre antes del montaje, o sea decidir si necesitas un equipo siquiera. Regla práctica de la documentación: los agent teams brillan cuando la exploración en paralelo aporta valor real. Cuatro escenarios en los que merecen la pena: investigación y revisión donde varios teammates examinan aspectos distintos a la vez y después se cuestionan entre sí. Módulos nuevos donde cada uno construye su pieza sin pisar al otro. Depuración con hipótesis en competencia, cada uno prueba una teoría distinta. Y trabajo entre capas que toca frontend, backend y tests al mismo tiempo.

Para qué NO coges un equipo: tareas secuenciales, ediciones en el mismo fichero, trabajo con muchas dependencias. Ahí una sola sesión o un subagent es más eficaz y más barato. Los equipos cuestan sobrecarga de coordinación y bastantes más tokens, cada teammate es una instancia propia de Claude con su propio contexto.

2. Activar la funcionalidad

Los agent teams están desactivados por defecto. Los enciendes con la variable de entorno CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, o directamente en tu shell o en el settings.json:

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

Yo tiro por la vía del settings.json, así queda estable para todo el proyecto y no se me olvida en el siguiente terminal. Si solo lo quieres probar, pon la variable como export de shell y reinicia Claude Code. Como es experimental, el comportamiento puede cambiar entre versiones, así que no te extrañes si una actualización mueve algo.

3. Arrancar el primer equipo

Después de activarlo le das a Claude la tarea en lenguaje normal y describes la estructura del equipo. Sin comando especial, solo un prompt. Un ejemplo de la documentación que funciona bien porque los tres papeles son independientes:

Estoy disenando una herramienta CLI que rastrea comentarios TODO en el codigo.
Crea un agent team que lo mire desde angulos distintos,
uno en UX, uno en arquitectura tecnica, uno como abogado del diablo.

Claude construye entonces un equipo con lista de tareas compartida, genera un teammate por perspectiva, les deja explorar el problema, resume los hallazgos y al final desmonta el equipo. Importante: Claude nunca crea un equipo sin que se lo pidan. O lo pides tú, o Claude lo propone y tú confirmas.

4. Controlar la visualización, in-process o paneles divididos

Hay dos modos de visualización. In-process significa que todos los teammates corren en tu terminal principal, pasas por ellos con Shift+Down y escribes directamente para mandarle un mensaje a uno. Funciona en cualquier terminal sin montaje extra. Los paneles divididos le dan a cada teammate su propio panel, ves todas las salidas a la vez y haces clic en un panel para interactuar directamente. Pero eso necesita tmux o iTerm2.

El valor por defecto es auto, que coge paneles divididos si ya estás dentro de una sesión de tmux, y si no, in-process. Si quieres fijar un modo, pon teammateMode en ~/.claude/settings.json:

{
  "teammateMode": "in-process"
}

Para una sesión suelta también vale el flag claude --teammate-mode in-process. Para paneles divididos necesitas tmux o iTerm2 con la CLI it2 instalada, y con iTerm2 además tienes que activar la API de Python en Settings, General, Magic. Yo casi siempre voy in-process, así me ahorro el lío de tmux y da de sobra para tres o cuatro teammates.

5. Fijar el número y el modelo de los teammates

Claude decide por su cuenta cuántos teammates genera, según la tarea. Pero se lo puedes indicar con precisión:

Crea un equipo con 4 teammates que refactoricen estos modulos en paralelo.
Usa Sonnet para cada teammate.

Un detalle que se pasa por alto a menudo: los teammates NO heredan por defecto la elección de /model del lead. Si quieres que todos sigan el modelo del lead, pon en /config la opción "Default teammate model" en Default, es decir el modelo del líder. Si no, puede que los teammates corran con otro modelo del que creías, y con cuatro teammates de Opus en paralelo eso lo notas como muy tarde en la factura.

6. Exigir aprobación del plan en tareas arriesgadas

En cambios delicados puedes exigir que un teammate planifique antes de tocar nada. Entonces trabaja en modo plan de solo lectura hasta que el lead dé el visto bueno a su enfoque:

Genera un teammate architect que refactorice el modulo de auth.
Exige aprobacion del plan antes de que haga ningun cambio.

Cuando el teammate ha terminado de planificar, manda una petición de aprobación al lead. Este la revisa y la aprueba, o la rechaza con feedback. Si la rechaza, el teammate se queda en modo plan, la rehace y la vuelve a presentar. El lead decide de forma autónoma, tú lo influyes mediante criterios en el prompt, del estilo "aprueba solo planes con cobertura de tests" o "rechaza todo lo que toque el esquema de la base de datos". Quien todavía no tenga controlado el modo plan debería pasarse antes por el playbook del modo plan, el principio es el mismo, solo que aquí aplicado a un teammate.

7. Hablar directamente con teammates concretos

Cada teammate es una sesión de Claude Code completa e independiente. Puedes escribirle a cada uno directamente para darle instrucciones extra, preguntarle o cambiarle el rumbo. En modo in-process pasas por los teammates con Shift+Down y después escribes el mensaje. Enter muestra la sesión de un teammate, escape interrumpe su turno actual, Ctrl+T activa y desactiva la lista de tareas. Después del último teammate, Shift+Down vuelve al lead. En modo de paneles divididos basta con hacer clic en el panel correspondiente.

Esa es la diferencia real con los subagents. En un subagent no puedes intervenir mientras trabaja, corre hasta el final e informa. A un teammate le puedes hablar en mitad de la sesión en marcha.

8. Repartir tareas y dejar que el equipo se comunique

La lista de tareas compartida coordina el trabajo. Las tareas tienen tres estados: pendiente, en curso, completada. Pueden depender unas de otras, una tarea pendiente con dependencias abiertas solo se puede reclamar cuando las anteriores están hechas. El lead puede asignar tareas de forma explícita ("dale la tarea X al teammate Y"), o los teammates las reclaman por su cuenta, al terminar uno coge por sí solo la siguiente tarea libre y no bloqueada. Para que dos no cojan la misma tarea a la vez, el sistema usa bloqueo de ficheros.

La comunicación va por un buzón. Los mensajes se entregan automáticamente, el lead no tiene que consultar. Cuando un teammate termina y se para, se lo comunica al lead automáticamente. Entre ellos los teammates se dirigen por el nombre que el lead asigna al generarlos. Consejo: dile al lead en el prompt cómo llamar a los teammates, así en prompts posteriores puedes dirigirte a ellos con precisión en vez de adivinar.

9. Imponer controles de calidad con hooks de equipo

Los agent teams traen sus propios eventos de hook, con los que impones reglas cuando los teammates terminan trabajo o se crean tareas. TeammateIdle se dispara justo antes de que un teammate quede inactivo, con código de salida 2 le mandas feedback y lo mantienes trabajando. TaskCreated se dispara al crear una tarea, el código 2 impide la creación y da feedback. TaskCompleted se dispara al completarla, el código 2 bloquea el cierre.

En la práctica eso significa que puedes, por ejemplo, impedir que un teammate quede inactivo mientras los tests estén en rojo, o que una tarea se marque como terminada sin que haya pasado un lint. Quien todavía no haya montado hooks, que empiece por el playbook de depuración de hooks, el patrón del código de salida 2 ya está explicado ahí y vale igual aquí.

10. Recoger y reutilizar papeles

Dos cosas para acabar. Primero recoger: cuando termines, dile al lead que haga cleanup. Eso quita los recursos compartidos del equipo. Ojo, el cleanup falla si todavía hay teammates activos, así que apaga antes los teammates uno a uno ("apaga por favor el teammate researcher"). La configuración del equipo está en ~/.claude/teams/{nombre-equipo}/config.json, la lista de tareas en ~/.claude/tasks/{nombre-equipo}/. No edites la configuración a mano, Claude la sobrescribe en la siguiente actualización de estado.

Segundo, papeles reutilizables. Al generar puedes referenciar una definición de subagent existente ("genera un teammate con el agent type security-reviewer"). Entonces el teammate hereda su lista de herramientas permitidas y su modelo, y la definición se añade a su system prompt como instrucción adicional. Así defines un papel una vez y lo usas tanto como subagent delegado como de teammate en un equipo. Las herramientas de coordinación como SendMessage y la gestión de tareas se le mantienen siempre al teammate, aunque la definición restrinja otras herramientas.

Qué sigue

Si ahora no tienes claro si para una tarea concreta necesitas un equipo, un subagent o solo una skill, lee Subagent o skill o herramienta MCP, ahí tienes la matriz de decisión. Y si quieres profundizar en la orquestación clásica de subagents, o sea workers que informan en vez de hablar entre ellos, Estructurar un equipo de subagents es el paso siguiente. Por contenido todo esto encaja en el nivel 5, mira en paralelo la lección Research, critic, analyst, el patrón adversarial del paso 1 está descrito ahí como concepto.

Source

Todos los detalles de este playbook vienen de la documentación oficial de Claude Code, a 8 de junio de 2026: https://code.claude.com/docs/en/agent-teams