Tutorial de Agent Teams de Claude Code: 15 pasos desde la configuración hasta el cierre
Agent Teams da a cada compañero su propia sesión de Claude Code, una lista de tareas compartida y chat directo entre ellos. Este tutorial con capturas cubre el flag de settings.json, tu primer equipo, la dirección del equipo, el cierre — y los límites que nadie te cuenta.
La versión corta
- Agent Teams es experimental y está desactivado por defecto: añade "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" al bloque env de settings.json y ejecuta Claude Code v2.1.32 o superior.
- Tienes que pedirlo con palabras — pide a Claude que "cree un agent team" y nombra a los compañeros o el modelo, o silenciosamente generará subagents normales.
- Los compañeros nunca heredan tu historial de conversación — entrégales un archivo de contexto y mantén cada tarea lo bastante pequeña para producir un único entregable claro.
- Cada compañero es una instancia aparte de Claude Code con su propia ventana de contexto, así que los tokens se multiplican — baja a los compañeros a Sonnet o Haiku cuando la tarea lo permita y revisa /cost tras cada ejecución.
Claude Code Agent Teams (Full Tutorial): The BEST FEATURE of Claude Code is HERE!
Vídeo:AICodeKing13:58
Agent teams — Orchestrate teams of Claude Code sessions
Documentación:code.claude.comDocs
Agent Teams es experimental: espera asperezas en la reanudación de sesiones, el estado de tareas y los tiempos de cierre. Cada comando, clave de configuración y atajo de esta página se ha verificado contra la documentación oficial antes de publicar.
Las capturas provienen de la grabación de pantalla de AICodeKing; los tutoriales de Bart Slodyczka y Simon Scrapes aportaron hechos prácticos adicionales. Todas las fuentes están acreditadas y enlazadas, y cada paso enlaza con el momento exacto del vídeo.
De una terminal fría a un equipo desmovilizado
1. Activa Agent Teams y verifica tu entorno
- 1
Encuentra la documentación de agent teams y lee la advertencia experimental
Agent Teams vive en la sección Build with Claude Code de la documentación oficial. La página abre con un banner naranja: la función es experimental, está desactivada por defecto y tiene limitaciones conocidas en reanudación de sesiones, coordinación de tareas y cierre. Lee ese banner antes de tocar cualquier flag.
La página oficial de agent teams y su banner de función experimental.Ver en el minuto 0:20 - 2
Decide entre subagents y agent teams
La documentación incluye una tabla comparativa. Los subagents corren dentro de una sola sesión, devuelven resultados al llamador y cuestan menos tokens. Los compañeros son instancias independientes de Claude Code que se escriben entre sí directamente y comparten una lista de tareas — la colaboración real cuesta más tokens. Usa subagents cuando solo importe el resultado; un equipo, cuando los trabajadores deban desafiarse entre sí.
Subagents frente a agent teams, directamente de la tabla oficial.Ver en el minuto 1:00 - 3
Activa el flag en settings.json
Abre (o crea) ~/.claude/settings.json y añade un bloque env con "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1". Los archivos de ajustes de proyecto y locales también pueden activarlo, y una exportación de shell funciona — pero un "0" en los ajustes de usuario anula la exportación. El cambio se aplica a la sesión en curso sin reiniciar.
El bloque env que enciende agent teams.Ver en el minuto 2:00 - 4
Actualiza Claude Code, arranca y pide el equipo en lenguaje llano
Ejecuta primero claude update — los equipos necesitan una compilación reciente (2.1.32 o superior); las versiones antiguas ignoran el flag en silencio. Inicia Claude, revisa el selector de modelo (el vídeo usa Opus 4.6 con Claude Max) y escribe un prompt con las palabras mágicas: "Use the agent teams feature." Sin esa frase, Claude generará subagents normales.
Claude Code v2.1.34 recibiendo el prompt de agent teams.Ver en el minuto 3:30
2. Lanza tu primer equipo
- 5
Mira cómo el lead divide el trabajo en una lista de tareas compartida
El lead convierte tu prompt en tareas y luego genera a los compañeros. La entrada de cada compañero muestra su tarea y "shift+↑ to manage". Fíjate en el marcador de dependencia: "Build UI, styling, and user interaction > blocked by #1" — el compañero de UI no puede tomar su tarea hasta que el de engine termine; así evita el trabajo duplicado la lista compartida.
Dos compañeros lanzados, con la tarea #2 bloqueada por la #1.Ver en el minuto 4:30 - 6
Déjalos trabajar y lee el progreso en vivo
Los compañeros trabajan en paralelo en sus propias sesiones. El lead narra el estado — "Both agents are working" — mientras cada línea de tarea lleva el nombre del compañero, el tiempo transcurrido y el gasto en tokens. Pulsa ctrl+o para expandir una entrada y ctrl+t para mostrar u ocultar el panel de compañeros.
Trabajo en paralelo con contabilidad de tokens y tiempo por tarea.Ver en el minuto 5:00 - 7
Opcional: fija el número de compañeros y su modelo
Puedes especificar exactamente lo que quieres: "Create a team with 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate." Asignar un modelo más barato por compañero es la palanca de coste más efectiva — el trabajo rutinario no necesita Opus. Para tareas arriesgadas, exige también la aprobación del plan para que el plan de un compañero espere tu visto bueno.
El ejemplo de la documentación para especificar compañeros y modelos.Ver en el minuto 6:30
3. Dirige, verifica e itera
- 8
Sigue el relevo de dependencias y la revisión del lead
Cuando el compañero de engine termina, la tarea #2 se desbloquea y el dev de UI la toma. Después el lead mismo lee los archivos modificados — "Let me shut down the teammates and do a final review of the code to make sure everything integrates properly." Solo intervienes si algo luce mal.
Tarea #1 completa, #2 desbloqueada, comienza la revisión final.Ver en el minuto 7:30 - 9
Abre el entregable y verifícalo tú mismo
El resultado del equipo aterriza como archivos normales en tu proyecto — aquí un Buscaminas con tres niveles de dificultad, revelado por flood-fill y primer clic seguro. Ábrelo en el navegador y úsalo de verdad antes de licenciar al equipo: los agentes verifican su propio código, pero la aceptación es tuya.
El entregable del equipo: un clon de Buscaminas funcional.Ver en el minuto 9:00 - 10
Itera dándole otro prompt al mismo equipo
La lista de características cumple, así que el vídeo repite: "Add more themes to it. Use team." En tareas de código el lead suele dejar a los compañeros en espera en lugar de desmovilizarlos, y tu seguimiento llega con todo el contexto de lo ya construido. Fíjate en la barra de estado: accept edits on (shift+tab para alternar).
La lista de funciones entregada y el prompt de la segunda ronda.Ver en el minuto 10:00 - 11
Dirige a individuos desde el panel de compañeros
En un equipo más grande (la segunda demo del vídeo corre seis compañeros), el panel muestra el nombre de cada uno, una palabra de estado en vivo y su recuento de tokens. shift+↑ / shift+↓ selecciona, Enter abre su conversación, y el cuadro de mensaje acepta menciones @ como "Message @infra-dev…" para llegar a un compañero sin pasar por el lead.
Seis compañeros, recuentos de tokens en vivo y un cuadro de mención @.Ver en el minuto 13:30 - 12
Desactiva a los compañeros con elegancia
Pídeselo al lead por su nombre — "Ask the ui-dev teammate to shut down" — y el compañero aprueba, terminando primero su llamada de herramientas en curso. Un compañero que considere su trabajo crítico puede rechazar la petición con una explicación. Cuando todo esté listo, "clean up the team" cierra las sesiones compartidas y los paneles vuelven a uno.
Ambos compañeros se apagan con elegancia durante la limpieza.Ver en el minuto 8:00
4. Conoce los límites antes de escalar
- 13
Conoce la regla del contexto antes de escalar
Los compañeros cargan CLAUDE.md, servidores MCP y skills automáticamente, pero nunca heredan el historial de conversación del lead. Entrega el contexto de forma explícita — el ejemplo de la documentación genera un revisor de seguridad con los archivos exactos, los focos y el formato de informe en el prompt. Y dimensiona las tareas con honestidad: demasiado pequeña desperdicia coordinación, demasiado grande arriesga esfuerzo, y en su punto es un único entregable autocontenido.
La regla de herencia de contexto y la lista de dimensionado de tareas.Ver en el minuto 10:15 - 14
Acepta que los equipos no se reanudan
La limitación que más sorprende: /resume y /rewind no restauran a los compañeros in-process. Tras reanudar una sesión, el lead puede intentar escribir a compañeros que ya no existen — cuando pase, dile al lead que genere compañeros nuevos. También espera retrasos en el estado de tareas: si una tarea parece atascada, comprueba si el trabajo está realmente hecho y actualízala a mano.
Sin reanudación de sesión, más el aviso sobre el estado de tareas.Ver en el minuto 10:30 - 15
Revisa las limitaciones restantes y elige trabajo de verdad
Tres reglas más de la documentación: el lead es fijo (no puedes ascender a un compañero), los permisos fijados al generarse se propagan — --dangerously-skip-permissions fluye a cada compañero, así que cambia el modo de un revisor después si no debe editar — y los paneles divididos requieren tmux o iTerm2, porque el terminal integrado de VS Code, Windows Terminal y Ghostty no están soportados. Luego empieza con 3-5 compañeros en trabajo que de verdad requiera colaboración.
Lead fijo, permisos que se propagan, paneles divididos con tmux.Ver en el minuto 11:30