Subagentes Claude Code: Cuándo y Cómo Ejecutar Equipos de Agentes

Última actualización: June 28, 2026

Un subagente de Claude Code es una sesión separada de Claude que el agente principal activa para un trabajo enfocado, y luego devuelve el resultado a tu trabajo. La semana pasada despaché tres en paralelo para dividir un refactor en esquema, API y pruebas, y terminaron antes de que una sola sesión larga hubiera terminado de planificar. Esta publicación cubre cómo definir y despachar subagentes, los patrones de orquestación que utilizo para imitar un equipo pequeño, y la línea honesta donde los subagentes cuestan más de lo que ahorran.

Respuesta rápida: ¿qué es un subagente de Claude Code?

Un subagente es una instancia de Claude con su propia ventana de contexto, su propio prompt del sistema y un conjunto de herramientas limitado. La sesión principal no pierde el contexto cuando ejecuta uno, porque el subagente trabaja en aislamiento y solo devuelve un resumen. Piénsalo como delegar una tarea a un compañero de equipo que nunca interrumpe tu pantalla.

El mecanismo oficial es simple. Colocas un archivo markdown en .claude/agents/ con frontmatter YAML, y Claude Code puede llamarlo a través de la herramienta Task cuando una tarea coincide con su descripción. La documentación de subagentes es la fuente de verdad para los campos, y el repo de Claude Code rastrea los cambios en el formato.

Una definición mínima de subagente se ve así:

---
name: migration-writer
description: Writes and runs database migrations for this repo. Use for schema changes.
tools: Read, Edit, Bash
model: inherit
---
You are a migration specialist. Always check existing migrations first, never drop columns without a confirmation step, and run the migration against the local DB before reporting done.

Una vez que existe ese archivo, le pido al agente principal "usa el subagente migration-writer para añadir la tabla orders" y este despacha un trabajador acotado en lugar de tropezar con él en línea. La línea model: inherit mantiene el costo y la calidad a la par de la sesión principal; fijar un modelo más económico como haiku en un subagente con muchas lecturas es una palanca real cuando ejecutas muchos de ellos.

¿Cuándo deberías recurrir a subagentes en lugar de una sesión?

Recurre a un subagente cuando una tarea sea de larga duración, con mucho contexto o necesite un conjunto de herramientas que no quieras en la sesión principal. Mantenlo en una sola sesión cuando el trabajo sea corto, estrechamente acoplado a lo que ya estás haciendo, o necesite un ida y vuelta ajustado contigo.

Utilizo subagentes para trabajos que de otro modo contaminarían mi contexto principal con registros, grandes lecturas o prueba y error. Una auditoría en todo el código base que usa grep en 200 archivos es un candidato perfecto, porque el subagente lee todo y devuelve un resumen de dos párrafos mientras mi sesión principal permanece limpia.

Si eres nuevo en el propio agente, la guía definitiva de Claude Code cubre los fundamentos antes de que añadas subagentes encima.

¿Cómo despachar subagentes en Claude Code?

El despacho ocurre de dos maneras. El agente principal puede invocar la herramienta Task por sí mismo cuando una tarea encaja con la descripción de un subagente, o puedes nombrarlo explícitamente en tu prompt. Prefiero nombrarlo, porque el despacho implícito a veces omite un agente que quería.

Algunos patrones que ejecuto regularmente:

• "Usa el subagente code-reviewer en el diff de esta rama, y luego aplica sus sugerencias."
• "Despacha migration-writer para añadir una columna users.email_verified, y despacha test-writer para cubrirla. Ejecuta ambos."
• "Activa el subagente api-docs contra src/routes/ y devuelve solo el esqueleto OpenAPI."

El subagente se ejecuta en su propio contexto, por lo que no puede ver tu conversación en curso a menos que pases el detalle en el prompt. Ese aislamiento es la clave. Cuando termina, obtienes un resultado, no un flujo de ruido intermedio.

Patrones que utilizo para flujos de trabajo tipo equipo

El truco es copiar cómo un equipo real divide el trabajo, y luego mapear cada rol a un subagente. Aquí están los patrones a los que sigo volviendo.

Investigar y expandir. Despacho un subagente para recopilar contexto, leo su resumen, y luego despacho varios subagentes de implementación contra una interfaz compartida. Esto refleja cómo un líder técnico acota el trabajo antes de asignar tickets.

Construir detrás de un contrato. Define primero la API o las propiedades del componente, y luego ejecuta un subagente backend y un subagente frontend en paralelo contra ese contrato. Ninguno bloquea al otro, y los conflictos son raros porque tocan archivos diferentes.

Revisar como un rol separado. Mantengo un subagente code-reviewer con solo herramientas de lectura. Después de cualquier cambio no trivial, lo ejecuto contra el diff. Restringir sus herramientas significa que literalmente no puede editar, lo que mantiene la revisión honesta.

Para flujos de trabajo repetibles como este, empareja los subagentes con habilidades de Claude Code: una habilidad codifica los pasos, y los subagentes hacen el trabajo aislado. Y si un subagente necesita datos externos, conéctalo a un servidor MCP de la manera que describe la guía de integración MCP de Claude Code.

Un ejemplo práctico: pedidos y pagos

El mes pasado dividí una funcionalidad de pedidos más pagos en tres subagentes contra un contrato tipado. El contrato era una única interfaz TypeScript para un Order con status, totalCents y paymentId. Despaché: un subagente backend para implementar la creación del pedido y las transiciones de estado; un subagente payments para conectar la llamada a Stripe y almacenar el paymentId; y un subagente test para cubrir la ruta feliz y el caso límite de reembolso. Los tres tocaron archivos diferentes, por lo que la fusión fue tres operaciones limpias de copiar-pegar en lugar de una sesión de resolución de conflictos. Todo el proceso tomó 14 minutos; el mismo trabajo en una sola sesión serial tomó 41 la semana anterior, porque el contexto único siguió recargando la documentación de Stripe.

¿Cómo se orquesta un trabajo paralelo sin perder contexto?

La sesión principal es tu coordinador. Su trabajo es dividir el trabajo, entregar prompts acotados y volver a unir los resultados. Mantén al coordinador ligero y deja que los subagentes lleven las lecturas pesadas.

Una ejecución paralela típica para mí se ve así:

1. Escribir el contrato y los límites de archivo en la sesión principal.
2. Despachar entre dos y cuatro subagentes, cada uno con una porción clara y una condición de éxito definida.
3. Leer cada resumen a medida que regresa, no a mitad del proceso.
4. Fusionar en la sesión principal, resolviendo las costuras tú mismo.
5. Ejecutar el subagente test al final contra el resultado integrado.

El paralelismo solo vale cuando las porciones son genuinamente independientes. Si dos subagentes editan schema.prisma, no has dividido el trabajo, has creado un problema de fusión. Dibuja límites en archivos y contratos, y luego impórtalos en el prompt.

¿Cuándo los subagentes añaden más sobrecarga de la que ahorran?

Los subagentes añaden latencia, tokens y costo de coordinación. El traspaso del resumen pierde detalles, por lo que cualquier cosa que necesite continuidad profunda es una mala opción. Sé honesto sobre el compromiso antes de recurrir a ellos.

Ejecuté un benchmark en una rama de funcionalidad: un subagente por microservicio versus una sola sesión recorriéndolos en orden. Para cinco servicios débilmente acoplados, el paralelo ganó aproximadamente un 40 % en tiempo de reloj. Para tres servicios que compartían un modelo de datos, la sesión única fue más rápida, porque la fusión y la reexplicación consumieron las ganancias paralelas.

La lección: el paralelismo recompensa la independencia y castiga el acoplamiento. Si tus porciones comparten estado, no las paralelices.

¿Cuáles son los errores comunes?

• Demasiados subagentes. Limito una ejecución a tres a cinco. Más allá de eso, el costo de coordinación supera la ganancia paralela.
• Prompts vagos. "Arregla la autenticación" falla. "Añade un endpoint de refresco JWT en /auth/refresh, devolviendo { token }, con una prueba" tiene éxito.
• Sin criterios de éxito. Indica lo que significa estar hecho. "Migración aplicada localmente y rollback probado" supera a "manejar el esquema".
• Conjunto de herramientas incorrecto. Dale a un revisor solo herramientas de lectura. Dale a un agente de despliegue los comandos exactos que necesita, nada más amplio.
• Ignorar fallos. Si un subagente devuelve un error, léelo. Reintentar ciegamente consume tokens y oculta un problema real.
• Saltarse la fusión. Los subagentes devuelven resultados; tú sigues siendo dueño de la integración. Asigna tiempo real para ello.

El error más costoso es tratar a los subagentes como paralelismo gratuito para cualquier cosa. Son trabajadores acotados detrás de un límite de resumen, y ese límite tiene un costo.

Resumen

Los subagentes convierten Claude Code en algo que se siente como un equipo pequeño: un coordinador ligero despachando trabajadores acotados que cada uno lleva su propio contexto y reporta un resultado. Defínelos en .claude/agents/, dispáchalos con la herramienta Task, y mantén tu sesión principal limpia al pasar las lecturas pesadas y los roles repetitivos a subagentes.

Úsalos cuando el trabajo sea largo, con mucho contexto o necesite un conjunto de herramientas restringido. Omítelos para tareas cortas, acopladas e interactivas donde la transferencia del resumen pierde demasiado. Dibuja límites en archivos y contratos, limita una ejecución a un puñado de agentes, y siempre presupuesta tiempo para fusionar los resultados tú mismo.

Una advertencia real: los subagentes multiplican el rendimiento, no el juicio. Construirán felizmente lo incorrecto en paralelo a través de cuatro contextos aislados. El trabajo de coordinación, la definición del contrato y la revisión final siguen recayendo sobre ti, por lo que la ventaja solo aparece cuando las porciones son verdaderamente independientes y los criterios de éxito son exactos. Si quieres el fondo más profundo sobre el protocolo que impulsa gran parte de este cableado de herramientas, el explicador MCP es una buena lectura siguiente, y la documentación de Claude Code cubre configuraciones que no repetí aquí.

Créditos de imágenes

• Un equipo de desarrolladores trabajando juntos en computadoras en una oficina tecnológica moderna — foto por Rebrand Cities en Pexels
• Código de programación colorido en un monitor de computadora — foto por inna mykytas en Pexels
• Un desarrollador escribiendo código en una laptop frente a múltiples monitores — foto por Christina Morillo en Pexels
• Dos programadores enfocados en codificar lado a lado en una oficina moderna — foto por Rebrand Cities en Pexels