Agent teams de Claude Code vs subagentes: cuándo usar cada uno y cómo montar un equipo

Agent teams vs subagentes

Ambos ejecutan trabajo en paralelo en ventanas de contexto separadas. La diferencia está en quién coordina: con subagentes, el agente principal lo gestiona todo; en un equipo, los compañeros toman tareas de una lista compartida y hablan entre sí.

Cuándo usar agent teams (y cuándo no)

• Investigación y revisión: los compañeros analizan un problema desde distintos ángulos y luego cuestionan los hallazgos de los demás.
• Módulos o funciones nuevas: cada compañero se encarga de una pieza distinta, como frontend, backend y tests.
• Depuración con hipótesis en competencia: varios compañeros intentan demostrar su teoría y refutar las de los demás.
• No para trabajo secuencial, ediciones de los mismos archivos ni tareas con muchas dependencias: ahí usa una sola sesión o subagentes.
• No para trabajo rutinario: el consumo de tokens crece con cada compañero activo.

Cómo montar un agent team de Claude Code

1. Activa los agent teams

   Pon CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS a 1 en tu entorno o en el bloque env de settings.json. Los equipos necesitan una sesión interactiva; con -p (y con el Agent SDK) Claude no crea compañeros.

   // settings.json: agent teams are experimental and off by default
   {
     "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
   }
   
   // Optional: give each teammate its own split pane (tmux or iTerm2)
   {
     "teammateMode": "auto"
   }

2. Describe el equipo con tus palabras

   Indica cuántos compañeros quieres y qué hace cada uno. Claude crea la lista de tareas compartida, los lanza y sintetiza sus hallazgos cuando terminan.

   Spawn three teammates to review PR #142:
   - One focused on security implications
   - One checking performance impact
   - One validating test coverage
   Have them each review and report findings.

3. Elige un modo de visualización

   El modo in-process es el predeterminado y funciona en cualquier terminal: los compañeros aparecen en un panel bajo el prompt; usa las flechas y Enter para abrir uno y escribirle, y Ctrl+T para la lista de tareas. Los paneles divididos dan a cada compañero su propio panel y requieren tmux o iTerm2 con la CLI it2; pon teammateMode en auto o tmux, o inicia con claude --teammate-mode auto.

4. Reutiliza los roles que ya definiste

   Pide un compañero “usando el tipo de agente security-reviewer” para reutilizar una definición de subagente de .claude/agents/, con sus herramientas, modelo e instrucciones.

5. Dirige y luego cierra

   Revisa cómo van los compañeros, redirígelos y di “espera a tus compañeros” si el líder empieza a hacer su trabajo. Para terminar, pide al líder que cierre a un compañero por su nombre; los directorios del equipo se limpian cuando termina la sesión.

Fuente: documentación de Claude Code, Agent teams

Buenas prácticas y limitaciones

• Empieza con 3–5 compañeros y unas 5–6 tareas por cabeza; tres compañeros enfocados suelen rendir más que cinco dispersos.
• Da a cada compañero un conjunto de archivos distinto: dos compañeros que editan el mismo archivo se sobrescriben.
• Pon los detalles de la tarea en el prompt de creación: los compañeros cargan CLAUDE.md, los servidores MCP y las skills, pero no la conversación del líder.
• Usa hooks como controles de calidad: TeammateIdle, TaskCreated y TaskCompleted pueden devolver el trabajo con el código de salida 2.
• Límites: un equipo por sesión, sin equipos anidados, el líder no puede cambiar, /resume no recupera a los compañeros in-process y el estado de las tareas puede ir con retraso.
• Los paneles divididos no funcionan en el terminal integrado de VS Code, Windows Terminal ni Ghostty; el modo in-process funciona en todas partes.
• Con los agent teams activados, un subagente que Claude nombra puede lanzarse como compañero; pon la variable a 0 si quieres recuperar los subagentes normales.

Agent teams vs otras formas de ejecutar Claude Code en paralelo

Los agent teams reparten una tarea que estás siguiendo, dentro de una sola sesión. Para tareas independientes, ejecuta sesiones separadas en git worktrees o como agentes en segundo plano; para una comparación completa, lee varios agentes de Claude Code. Para contener el coste, consulta cómo reducir el consumo de tokens de Claude Code.

Un equipo que sigue trabajando cuando termina la sesión

Un agent team vive dentro de una sesión y se detiene cuando la cierras. Crewmark convierte las sesiones de Claude Code, Codex, DeepSeek Harness u OpenCode en empleados de IA con roles, objetivos y horarios laborales duraderos: cada uno se despierta con un heartbeat, toma la siguiente issue de un tablero compartido y te escribe cuando necesita una decisión.

1. Da un rol a cada empleado

   Un ingeniero de software, un revisor, un especialista en SEO: los roles que crearías como compañeros, pero para siempre.

2. Trabaja desde un solo tablero

   Las issues sustituyen a la lista de tareas de la sesión y sobreviven a reinicios, días y semanas.

3. Deja que el heartbeat inicie el trabajo

   Cada 15, 30 o 60 minutos durante el horario laboral; consulta qué es un empleado de IA.

Preguntas frecuentes sobre los agent teams de Claude Code