$ man how-to/subagents-vs-agent-teams

Claude Code ofrece dos formas de ejecutar multiples instancias de AI en tu codebase. Los subagentes son trabajadores ligeros creados desde tu sesion actual. Los equipos de agentes son instancias completas de Claude Code que se coordinan entre si. La diferencia es comunicacion y autonomia. Los subagentes reportan al padre. No pueden hablar entre ellos. Ejecutan una tarea enfocada y devuelven resultados. Piensa en ellos como funciones que llamas en paralelo. Los equipos de agentes se comunican entre si. Reclaman tareas de una lista compartida. Pueden enviar mensajes a compañeros de equipo, compartir descubrimientos y coordinarse sin un orquestador central. Piensa en ellos como un equipo real trabajando en el mismo proyecto.

PATTERN

Los subagentes se crean usando la herramienta Agent dentro de una sesion de Claude Code. Especificas la tarea, el tipo de agente (Explore, Plan, proposito general) y opcionalmente un modo de aislamiento (worktree para ramas de git separadas). Cada subagente obtiene su propia ventana de contexto. Puede leer archivos, ejecutar comandos, buscar codigo y devolver resultados. Cuando termina, el resultado regresa a la sesion padre. Caracteristicas clave: Comunicacion unidireccional. El padre envia una tarea, el subagente devuelve un resultado. Sin negociacion de ida y vuelta. Sistema de archivos compartido. Los subagentes ven el mismo repositorio (a menos que usen aislamiento con worktree). Los cambios de un subagente son visibles para otros. Orquestacion del padre. La sesion principal decide que delegar, cuando crear subagentes y como combinar resultados. Costo: cada subagente consume tokens proporcionales a su tarea. Una busqueda rapida de archivos podria usar 5K tokens. Una exploracion profunda podria usar 50K. La sesion padre asume el costo. Mejor para: investigacion paralela, busquedas independientes de archivos, generacion de contenido en paralelo, cualquier tarea donde necesites velocidad a traves de paralelismo pero las tareas son independientes.

PATTERN

Los equipos de agentes son una funcion experimental (activar via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). Una sesion actua como lider de equipo. Crea tareas en una lista de tareas compartida. Los compañeros reclaman tareas, trabajan en ellas y comunican resultados entre si. Caracteristicas clave: Comunicacion entre pares. Los compañeros de equipo se envian mensajes directamente. El lider del equipo no necesita transmitir cada pieza de informacion. Sistema de tareas compartido. Las tareas se publican en una lista compartida. Los compañeros reclaman tareas segun disponibilidad y capacidad. No se requiere asignacion central. Ventanas de contexto independientes. Cada compañero tiene su propio contexto completo. Pueden mantener diferentes modelos mentales del codebase y compartir descubrimientos a traves de mensajes. Mayor autonomia. Los compañeros pueden descubrir problemas, crear nuevas tareas y coordinar soluciones sin que el lider del equipo dirija cada paso. Costo: cada compañero es una instancia completa de Claude. Un equipo de 3 personas usa aproximadamente 3x los tokens. Un equipo de 5 personas usa 5x. Esto se acumula rapido. Mejor para: funcionalidades complejas multi-modulo, revisiones de codigo paralelas con diferentes areas de enfoque, depuracion con hipotesis competidoras y cualquier tarea donde los agentes necesiten reaccionar a los hallazgos de los demas.

FORMULA

Usa subagentes cuando: - Las tareas son independientes (ninguna tarea depende del resultado de otra) - La comunicacion es unidireccional (enviar tarea, obtener resultado) - Quieres que la sesion padre mantenga control total - El presupuesto es una preocupacion (los subagentes son mas baratos) - Las tareas estan bien definidas con criterios claros de finalizacion Usa equipos de agentes cuando: - Las tareas interactuan (cambios en frontend afectan backend, interfaces compartidas) - Los agentes necesitan reaccionar a los descubrimientos de los demas - El espacio del problema es ambiguo y requiere exploracion - Quieres que los agentes desafien los enfoques de los demas - El trabajo tomaria demasiado tiempo para una sola sesion y se beneficia del paralelismo verdadero Usa una sola sesion cuando: - La tarea es secuencial (cada paso depende del anterior) - El codebase es lo suficientemente pequeño para una ventana de contexto - Necesitas control estricto sobre cada decision - El costo importa mas que la velocidad Ejemplo real de mi flujo de trabajo: uso subagentes diariamente para investigacion paralela - "explora el modulo de auth," "encuentra todos los endpoints de API," "revisa la cobertura de tests." Estas son consultas independientes. Uso equipos de agentes para funcionalidades de varios dias - "construye el nuevo dashboard" donde un agente maneja la capa de API, otro maneja los componentes de UI y un tercero escribe tests. Necesitan coordinarse en el contrato de interfaz entre capas.

PRO TIP

Los subagentes son baratos. Un subagente explore tipico usa 10-50K tokens. A precios actuales, eso son centavos. Puedes crear 5-10 subagentes en paralelo sin pensar en el costo. Los equipos de agentes son caros. Cada compañero mantiene una ventana de contexto completa que crece con cada mensaje y lectura de archivo. Un equipo de 3 personas trabajando durante una hora puede consumir 500K-1M tokens. Con precios de API, eso son dolares. Con suscripcion Max, cuenta contra tus limites de uso. La regla: empieza con subagentes. Escala a equipos de agentes solo cuando encuentres un problema real de coordinacion que los subagentes no puedan resolver. La mayoria de las tareas no necesitan equipos de agentes. El patron de sesion-unica-con-subagentes maneja el 90% del trabajo paralelo. Otra opcion: multiples pestañas de terminal, cada una ejecutando una sesion independiente de Claude Code en diferentes partes del codebase. Esto te da paralelismo sin el overhead de equipos de agentes. La compensacion es que las sesiones no pueden comunicarse - tu eres el orquestador.