Cuando se habla de colaboración multi-agente en Claude Code, los dos conceptos más fáciles de mezclar son Subagents y Agent Teams. Ambos suenan como “levantar varios agentes para trabajar juntos”, pero están pensados para tipos de trabajo distintos. En corto: los primeros son mejores para separar tareas independientes, mientras los segundos encajan mejor cuando varios agentes necesitan colaborar alrededor del mismo problema y revisar sus conclusiones con el tiempo.

Si ya has usado Skills, este marco también ayuda:

• Una Skill define el flujo y las reglas
• Un Subagent o compañero de Agent Team ejecuta el trabajo real

Así que la pregunta real no es cuál es más avanzado, sino qué problema de colaboración estás resolviendo.

Subagents: separar tareas laterales

Subagents se parecen más a copias temporales de trabajador lanzadas desde la sesión actual. Cada uno tiene su propia ventana de contexto y, al terminar, devuelve solo un resumen del resultado. La conversación principal se mantiene más limpia porque no absorbe todos los logs y salidas intermedias.

Eso da a Subagents varias fortalezas prácticas:

• El hilo principal se mantiene limpio en lugar de llenarse de logs de tests, resultados de búsqueda o salida larga
• Tareas independientes de investigación o ejecución pueden correr en paralelo
• Funcionan bien cuando basta con “tráeme el resultado”

El artículo original señala que Claude Code trae tres tipos integrados de Subagents:

• Explore: solo lectura, útil para buscar rápidamente en una codebase
• Plan: solo lectura, útil para reunir información en segundo plano durante plan mode
• General-purpose: puede leer y escribir, adecuado para tareas que mezclan exploración y edición

Subagents personalizados

Si las opciones integradas no bastan, puedes definir tu propio Subagent. El mecanismo es simple: escribir un archivo Markdown en una de estas ubicaciones:

• .claude/agents/: activo solo en el proyecto actual
• ~/.claude/agents/: activo en todos tus proyectos

El formato se ve así:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:

1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:

- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:

- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

El campo clave es description. Claude lo usa para decidir cuándo debe llamarse ese Subagent, así que cuanto más precisa sea la descripción, más fiable suele ser el disparo.

También conviene conocer algunos campos comunes:

• tools: limita qué herramientas puede usar el Subagent
• model: elige entre sonnet, opus, haiku o inherit
• permissionMode: controla permisos de edición y prompts de autorización
• memory: da al Subagent un directorio de memoria entre conversaciones

Si solo necesitas un Subagent temporal, también puedes definirlo mediante CLI:

1
2
3
4
5
6
7
8

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Cuándo encajan mejor los Subagents

Subagents suelen encajar mejor en tareas como:

• Ejecutar tests y devolver solo el resumen de fallos en lugar de llenar el hilo principal con miles de líneas de logs
• Investigar varios módulos no relacionados en paralelo
• Dividir “encontrar el problema” y “corregir el problema” en una pipeline simple

Por ejemplo:

1

Research the authentication, database, and API modules in parallel using separate subagents

1

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

Pero si una tarea necesita ajustes constantes de ida y vuelta, comparte mucho contexto entre etapas o concentra cambios en uno o dos archivos, manejarla directamente en la conversación principal suele ser más simple que levantar un Subagent.

Agent Teams: múltiples sesiones independientes trabajando juntas

Agent Teams operan en otro nivel. En vez de lanzar copias de trabajadores dentro de una sesión, inician varias instancias independientes de Claude Code que colaboran alrededor de una lista de tareas compartida y también pueden enviarse mensajes directamente.

Eso hace que un Agent Team se sienta más como un pequeño equipo real que como un simple sistema de tareas laterales.

El artículo señala que actualmente es una función experimental y debe activarse primero:

1
2
3
4
5

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

Una vez añadido a settings.json, puedes pedir a Claude que organice un equipo alrededor de un objetivo. Por ejemplo:

1
2
3

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

De qué se compone un Agent Team

Un Agent Team incluye principalmente tres partes:

• Team lead: la sesión principal que usas, responsable de organizar, asignar y resumir
• Teammates: varias instancias independientes de Claude Code
• Task list y Mailbox: lista compartida de tareas y canal de comunicación

La mayor diferencia con Subagents es que los teammates pueden comunicarse directamente entre sí en lugar de pasar todo por el lead. Las tareas suelen moverse por estados como pending, in progress y completed; cuando un teammate termina una tarea, puede tomar la siguiente.

Cuándo encajan mejor los Agent Teams

Cuando una tarea necesita varias perspectivas, discusión activa, hipótesis en conflicto o trabajo paralelo en módulos, Agent Teams encajan mejor.

El artículo da varios ejemplos representativos:

• Varios revisores inspeccionan el mismo PR en paralelo, cada uno centrado en una dimensión
• Varios agentes investigan el mismo bug con explicaciones competidoras y desafían las conclusiones de los otros
• Frontend, backend y testing avanzan en paralelo en distintas partes del proyecto

Por ejemplo, revisión de código en paralelo:

1
2
3
4
5

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

Y depuración estilo debate:

1
2
3
4

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

El patrón común es que no quieres una sola respuesta. Quieres varios agentes intercambiando juicios, desafiando supuestos y convergiendo gradualmente en una conclusión más sólida.

Cómo elegir entre ellos

Si quieres una regla rápida:

• Si solo necesitas el resultado, usa Subagents
• Si el trabajo requiere discusión y validación cruzada, usa Agent Teams

Ampliando un poco:

• Estilo de comunicación: Subagents principalmente reportan resultados a la sesión principal; miembros de Agent Teams pueden hablar directamente entre sí
• Modelo de coordinación: Subagents dependen más de la conversación principal para orquestación; Agent Teams trabajan desde una lista de tareas compartida que los miembros pueden reclamar
• Coste de tokens: Subagents son más baratos; Agent Teams cuestan más porque cada teammate es una instancia independiente
• Mejor ajuste: Subagents para trabajo independiente y orientado a resultados; Agent Teams para trabajo con mucha discusión y revisión cruzada

Precauciones prácticas

Agent Teams son más potentes, pero eso no significa que cada tarea merezca un equipo completo. El artículo destaca varias preocupaciones prácticas:

• el uso de tokens sube de forma notable
• si varios teammates editan el mismo archivo a la vez, los conflictos de sobrescritura son muy probables
• añadir demasiados teammates aumenta el coste de coordinación sin garantizar mejores resultados

Un valor predeterminado más seguro suele ser:

• empezar con 3 a 5 teammates
• dividir tareas por módulo o archivo para evitar conflictos de edición
• si el lead empieza a hacer el trabajo de los teammates demasiado pronto, pedirle explícitamente que espere primero a los demás

La versión experimental actual también tiene limitaciones:

• sin soporte de /resume y /rewind para teammates en proceso
• el estado de tareas puede retrasarse y a veces necesita corrección manual
• un lead solo puede gestionar un equipo a la vez
• los teammates no pueden crear child teams propios

Conclusión breve

Estas dos funciones no se sustituyen entre sí. Resuelven dos problemas de colaboración distintos.

Si tu objetivo es paralelizar tareas laterales y mantener limpio el contexto principal, empieza con Subagents. Si tu objetivo es dejar que varios agentes trabajen como un pequeño equipo, discutan y se revisen entre sí, Agent Teams son la mejor herramienta.

Probar ambas en una tarea real suele aclarar la diferencia rápidamente: una está optimizada para aislamiento de contexto y recolección de resultados; la otra para colaboración multiperspectiva e interacción continua.

Enlaces relacionados

• Artículo original: https://cloud.tencent.com/developer/article/2652960