Subagentes en Claude Code: Guía Completa para Sistemas Multi-Agente (2026)

Un subagente en Claude Code es un proceso hijo independiente que Claude lanza para manejar una subtarea específica. Tiene su propio contexto aislado, sus propias herramientas, y puede trabajar en paralelo o en secuencia — sin compartir la ventana de contexto del agente padre.

Construí una organización permanente de agentes y después la retiré por falta de uso real. Esa experiencia reforzó una regla: un subagente solo se justifica cuando el aislamiento, el paralelismo o la especialización compensan el costo de coordinación.

Este artículo explica qué son los subagentes, cómo funcionan por dentro, cuándo conviene usarlos, los patterns principales de arquitectura y los errores que aparecen cuando se delega sin contexto suficiente.

Qué es un subagente

Un subagente es un proceso hijo que Claude Code lanza para manejar una subtarea específica. Pensalo como delegar trabajo a un especialista que trabaja en paralelo o en secuencia, con su propio contexto, sus propias herramientas, y su propio espacio de trabajo.

Una forma conceptual de entender la delegación a un subagente es esta:

1. El agente padre define una tarea y sus límites.
2. El subagente recibe el contexto y los permisos necesarios.
3. Trabaja dentro de ese alcance.
4. Devuelve un resultado o artefacto.
5. El padre revisa e integra ese resultado.

La diferencia fundamental con hacer todo en una sola conversación es que no conviene asumir que el subagente comparte todo el contexto del padre. Esa separación puede ser una ventaja y una trampa al mismo tiempo — ya vamos a ver por qué.

Un modelo conceptual para entenderlo

La implementación concreta de Claude Code puede cambiar. Los nombres de campos, perfiles disponibles y mecanismos de aislamiento deben verificarse en la documentación vigente; lo siguiente no representa un schema de API.

Para delegar una tarea hacen falta, conceptualmente, cuatro decisiones:

• Brief: qué debe resolver, con qué evidencia y qué resultado se espera.
• Alcance: qué fuentes, archivos y herramientas puede consultar o modificar.
• Aislamiento: si comparte el checkout o necesita un espacio de trabajo separado.
• Ejecución: si el flujo espera su resultado o puede continuar con otra tarea independiente.

Este mapa sirve para diseñar la delegación. No debe copiarse como configuración exacta sin comprobar primero la interfaz disponible.

El ciclo de vida

Padre lanza subagente
    ↓
Subagente recibe prompt (contexto aislado)
    ↓
Subagente trabaja (lee archivos, busca, escribe código)
    ↓
Subagente devuelve resultado al padre
    ↓
Padre integra resultado y continúa

Lo que no pasa en ningún momento: el subagente NO puede asumir un ida y vuelta durante la ejecución. Le das las instrucciones, trabaja y devuelve el resultado dentro del mecanismo disponible.

Cuándo usar subagentes vs hacerlo directo

No todo necesita un subagente. De hecho, usarlos cuando no hacen falta agrega overhead innecesario — más contexto transferido, más coordinación y más superficie de error.

Esta es la tabla de decisión que uso:

Situación	Estrategia	Por qué
Tarea simple, alcance pequeño	Directo	El overhead del subagente no se justifica
Fix de un typo o bug puntual	Directo	La delegación agrega más pasos que el cambio
Investigación extensa y separable	Subagente	Evitás saturar el contexto principal con material intermedio
Tareas independientes	Subagentes en paralelo	Cada tarea puede trabajar con contexto limpio
Cambios con riesgo de conflicto	Subagente con worktree	Aislamiento de archivos y reversibilidad
Auditoría multi-dimensión	Fan-out con subagentes acotados	Cada especialista analiza un aspecto diferente
Pipeline con dependencias	Subagentes en secuencia	El output de una etapa alimenta la siguiente

La regla de oro: si la tarea cabe cómodamente en tu conversación actual sin saturar el contexto, hacela directo. Si necesitás paralelismo, aislamiento o contexto limpio, evaluá un subagente.

Los 4 patterns principales

Estos cuatro patterns cubren la mayoría de los casos de uso que vale la pena evaluar. Cada uno tiene un costo de coordinación distinto.

1. Fan-out / Gather

Lanzás subagentes en paralelo, cada uno analiza un aspecto diferente, y después consolidás los resultados.

              Padre (orquestador)
             /    |    |    \
            ↓     ↓    ↓     ↓
         SEO   Perf  A11y  Security
            \     |    |    /
             ↓    ↓    ↓   ↓
           Consolidar resultados

Ejemplo: una auditoría web. Cada subagente puede revisar una dimensión independiente:

• Core Web Vitals
• estructura de headings y metadatos
• schema markup
• sitemap e indexación
• internal links
• accesibilidad o seguridad

El padre consolida los reportes y elimina duplicaciones. El beneficio solo existe si las dimensiones son realmente independientes y la revisión final puede integrar criterios distintos.

Cuándo usarlo: cuando tenés análisis independientes y necesitás un resultado consolidado.

2. Pipeline (A luego B luego C)

Subagentes en secuencia donde el output de uno es el input del siguiente.

Research → Draft → Review → Aprobación
   ↓         ↓        ↓         ↓
 datos     borrador  feedback  decisión humana

Ejemplo: un pipeline editorial. La investigación reúne fuentes, el draft transforma la evidencia en un artículo y la revisión comprueba claims, estructura y enlaces.

Cada paso necesita el output del anterior. Pero eso no obliga a automatizar la publicación: la aprobación humana sigue siendo una frontera separada.

Cuándo usarlo: cuando las tareas tienen dependencias claras y el artefacto de una etapa puede verificarse antes de iniciar la siguiente.

3. Orchestrator-Worker

Un coordinador analiza la tarea, decide qué workers necesita, los lanza y consolida.

         Orchestrator
        ↙     ↓      ↓     ↘
  Worker A  Worker B  ...  Worker N

Este fue el pattern de la arquitectura permanente que construí y después eliminé.

# Resumen histórico de la configuración retirada
Orquestador:
  - Recibía el pedido
  - Identificaba el dominio responsable
  - Delegaba con un brief
  - Consolidaba el resultado

La configuración incluía reglas para evitar ciclos, acotar la profundidad y registrar handoffs. El repositorio prueba que ese contrato existió, pero no que haya tenido uso sostenido o resultados medibles.

La retrospectiva del orquestador retirado explica por qué el sistema no justificó su complejidad y qué mecanismos sobrevivieron.

Cuándo usarlo: cuando hay coordinación recurrente entre especialidades, dependencias estables y una reducción medible de fricción. No solo porque la tarea parezca compleja.

4. Background Monitor

Un subagente puede vigilar un proceso mientras el flujo principal continúa.

# Ejemplo conceptual de monitoreo periódico
/loop <intervalo> chequeá que el deploy responde correctamente

Un monitor post-deploy podría verificar rutas, revisar logs y reportar un resultado. Antes de usarlo, definí duración, permisos, condición de parada y qué puede hacer ante un error.

Cuándo usarlo: monitoreo acotado, vigilancia de métricas o polling que no necesita bloquear el flujo principal.

Context isolation: lo más importante que tenés que entender

Si te llevás una sola cosa de este artículo, que sea esta: los subagentes NO heredan automáticamente toda la conversación del padre.

Parece obvio cuando lo leés, pero es el error número uno que comete todo el mundo — incluido yo al principio.

Qué significa en la práctica

Cuando lanzás un subagente, no deberías asumir que sabe:

• Qué estuviste hablando con el padre
• Qué archivos leyó el padre antes
• Qué decisiones se tomaron en la conversación
• Cuál es el "contexto obvio" que vos tenés en la cabeza

El subagente solo puede actuar con el contexto que recibe o que está autorizado a leer.

Ejemplo de lo que sale mal

Imaginá que estás trabajando en tu web y tuviste esta conversación con Claude:

Vos: "Estoy migrando los estilos de CSS modules a Tailwind v4"
Claude: "Entendido, voy a..."
[... conversación sobre la migración ...]
Vos: "Ahora usá un subagente para migrar el componente Header"

El subagente puede no conocer las convenciones acordadas, los archivos ya migrados ni las restricciones del diseño.

Si el padre no le pasa esa información explícitamente o no indica dónde leerla, el subagente va a completar los huecos por su cuenta.

Cómo hacerlo bien

El prompt del subagente tiene que ser autosuficiente. Todo lo que necesita saber tiene que estar ahí o en una fuente indicada:

# Mal - asume contexto que no tiene
prompt: "Migrá el componente Header"

# Bien - contexto completo
prompt: |
  Migrá el componente Header de CSS Modules a Tailwind v4.

  Contexto:
  - Archivo: website/src/components/layout/Header.tsx
  - CSS actual: website/src/components/layout/Header.module.css
  - Convención: usar cn() para clases condicionales
  - Tokens visuales: leer la fuente canónica del proyecto
  - La clase .header-nav se mapea a "flex items-center gap-6"
  - Eliminar el archivo .module.css cuando termines

  Output esperado: el archivo Header.tsx migrado y el .module.css eliminado.

La regla: si te preguntarías "¿el subagente sabe esto?", la respuesta por defecto es no. Pasalo o indicá la fuente.

Worktrees para aislamiento de código

Cuando un subagente va a hacer cambios de código, tenés dos opciones:

1. Checkout compartido — el subagente trabaja sobre el mismo directorio de trabajo.
2. Worktree separado — el subagente trabaja sobre una copia de trabajo aislada del repositorio.

Cuándo usar worktrees

• Cuando dos o más subagentes van a editar código al mismo tiempo
• Cuando el subagente va a hacer una refactorización agresiva que podría romper cosas
• Cuando querés evaluar un approach sin comprometer tu branch

Cómo funciona

Conceptualmente, ese aislamiento puede apoyarse en un git worktree — una feature nativa de Git que permite tener múltiples copias de trabajo de un mismo repositorio sin clonarlo completo.

# Ejemplo conceptual; la ubicación depende de la política del proyecto
git worktree add "<ruta-del-worktree>" HEAD

El subagente trabaja en su copia aislada. Si todo sale bien, los cambios se incorporan mediante el flujo de Git aprobado. Si algo falla, se descartan sin modificar el checkout principal.

Lo que NO hay que hacer

No uses worktrees para todo. Crear uno tiene overhead, ocupa espacio y puede generar conflictos si los mismos archivos cambian en paralelo.

Mi regla: worktrees solo cuando hay riesgo real de conflicto o cuando necesito poder descartar los cambios completamente.

Ejemplo práctico: una tarea de contenido

Veamos cómo puede funcionar una delegación acotada sin convertirla en una organización permanente.

El pedido: "Escribí un post de LinkedIn sobre MCP (Model Context Protocol)".

Paso 1: definir el trabajo

Antes de lanzar subagentes, el padre decide qué partes requieren contexto separado:

• Investigación actualizada sobre MCP
• Un draft del post
• Revisión de contenido ya publicado

Paso 2: investigar

Subagente: research
Prompt: |
  Investigá el estado actual de MCP (Model Context Protocol).

  Usá fuentes primarias.
  Separá hechos, inferencias y puntos que requieren verificación.
  Output: brief conciso con enlaces y fecha de acceso.

El subagente devuelve un brief. No publica ni transforma una fuente secundaria en evidencia primaria.

Paso 3: escribir

Subagente: writing
Prompt: |
  Escribí un borrador de LinkedIn sobre MCP.

  Brief de investigación:
  [... output verificado del paso anterior ...]

  Voz: la definida por el contexto de marca
  Público: el definido por el brief
  Restricción: no publicar ni inventar métricas

El subagente recibe el brief procesado y escribe un borrador.

Paso 4: consolidación

El padre revisa evidencia, repeticiones, tono y límites. Una persona aprueba cualquier publicación.

La ganancia potencial no es una velocidad prometida. Es calidad de contexto cuando las etapas están bien separadas. Si la coordinación agrega más trabajo del que evita, conviene hacerlo directo.

Errores comunes (y cómo evitarlos)

Estos son los errores que más aparecen cuando se trabaja con subagentes.

1. Asumir que el subagente hereda contexto

Ya lo cubrimos, pero vale repetirlo: el subagente no sabe nada que no reciba o pueda leer. No conviene confiar en contexto implícito.

Solución: tratar el prompt del subagente como un brief para un especialista que no conoce la conversación. Todo lo necesario debe estar ahí o referenciado.

2. Lanzar demasiados subagentes en paralelo

Claude Code tiene límites de concurrencia y cada subagente agrega coordinación. Si lanzás más de los que podés observar y revisar, algunos pueden quedar en cola y el overhead puede superar el beneficio.

Solución: usá el conjunto mínimo que permita separar dimensiones realmente independientes. Agrupá tareas relacionadas y medí el costo de consolidación.

3. No especificar el output esperado

Si le decís al subagente "investigá sobre X" sin decirle qué formato querés, podés recibir desde un párrafo hasta un ensayo demasiado extenso.

Solución: siempre incluir en el prompt:

• Qué formato querés
• Qué información específica necesitás
• Qué límites y fuentes debe respetar

# Mal
prompt: "Investigá las tendencias de IA"

# Bien
prompt: |
  Investigá tendencias de IA relevantes para esta decisión.
  Output: lista priorizada con fuente primaria, fecha y limitación.
  Omití cualquier claim que no pueda verificarse.

4. Usar subagentes para tareas triviales

Cada subagente tiene overhead: inicialización, transferencia de contexto, consolidación y revisión. Para una tarea pequeña, puede tardar más que el trabajo directo.

Solución: si la tarea es simple, rápida y no necesita aislamiento ni paralelismo, hacela directo.

5. Usar background sin necesidad

El background sirve cuando la tarea es independiente. También puede ocultar errores o dejar procesos sin una condición clara de finalización.

Solución: usalo solo con una duración acotada, un resultado esperado y una forma de observar o cancelar la ejecución.

6. Prompts demasiado largos o demasiado cortos

Si el prompt es mínimo, falta contexto. Si copia toda la conversación, transfiere ruido y desperdicia atención.

Solución: el prompt debería contener:

• Contexto: lo necesario para entender la tarea
• Tarea: qué tiene que hacer
• Output: qué formato y evidencia entregar
• Restricciones: qué no debe hacer

7. No tener un sistema de comunicación cuando realmente hace falta

Cuando varios subagentes trabajan en el mismo proyecto, una tarea puede depender de información producida por otra.

Solución: usá un handoff explícito solo si aporta trazabilidad. En la arquitectura que retiré, esos handoffs vivían en archivos compartidos; no demostraron suficiente uso para sostener toda la organización.

Configuración de agentes con archivos de instrucciones

Los agentes pueden definirse mediante archivos .md con alcance, herramientas y restricciones. Una estructura útil incluye:

# Estructura de un archivo de agente
Rol: qué es y qué hace
Modelo: criterio de selección para la tarea
Herramientas: qué puede usar
Instrucciones: cómo debe trabajar
Inputs: qué necesita para empezar
Outputs: qué debe entregar
Restricciones: qué NO debe hacer

El CLAUDE.md principal puede definir reglas generales. Cada archivo específico debe agregar solo el contexto propio del rol.

Esto hace que una configuración sea mantenible, pero no demuestra que deba existir. Primero se verifica la fricción; después se decide si una instrucción, una skill, un subagente o un orquestador es la capa correcta.

Sobre Agent Teams

Las capacidades de equipos y delegación de Claude Code cambian con rapidez. Verificá la documentación oficial vigente antes de asumir nombres, disponibilidad o límites.

Los patterns de este artículo siguen siendo útiles como criterios: fan-out para análisis independientes, pipeline para dependencias y orquestación solo cuando la coordinación recurrente justifica su costo.

Si te interesa el contexto del producto, cubrí las novedades de Claude Code 2026 en este artículo.

Recursos relacionados

Si querés profundizar en temas específicos:

• Construí un Sistema Multiagente con Claude Code. Después lo Eliminé — retrospectiva del orquestador retirado, su evidencia y el criterio de simplificación
• Cómo Uso Claude Code para mi Consultoría — el punto de partida del uso de Claude Code
• Claude Code Novedades 2026 — cambios del producto que conviene verificar antes de implementar
• 7 Funciones Ocultas de Claude Code — worktrees, hooks, skills y otras funciones
• MCP: Guía Completa del Model Context Protocol — cómo conectar herramientas externas a Claude

Preguntas frecuentes sobre subagentes en Claude Code

¿Qué es un subagente en Claude Code? Un subagente es un proceso hijo independiente que el agente padre lanza para manejar una subtarea específica. Tiene contexto y herramientas acotados y devuelve un resultado al padre.

¿Los subagentes comparten contexto con el agente padre? No conviene asumirlo. El subagente trabaja con el contexto que recibe y con las fuentes que está autorizado a leer. Por eso el brief debe ser autosuficiente.

¿Cuántos subagentes se pueden correr en paralelo? Los límites dependen de la versión, el plan, el entorno y la herramienta. La decisión práctica es usar el mínimo que aporte paralelismo real y que pueda observarse y revisarse.

¿Los subagentes consumen más recursos? Sí. Cada subagente procesa su propio contexto y produce un resultado que luego debe integrarse. Se justifican cuando el aislamiento o el paralelismo aportan más valor que ese overhead.

¿Qué diferencia hay entre un subagente y abrir una nueva conversación? El subagente forma parte de un flujo de trabajo y devuelve su resultado al padre. Una conversación nueva es un flujo manual separado.

¿Se pueden usar subagentes sin saber programar? No siempre hace falta escribir código, pero sí entender el alcance, el contexto, los permisos y el criterio de aprobación. La interfaz no elimina el diseño del proceso.

Conclusión

Los subagentes pueden aportar aislamiento, especialización y paralelismo. No convierten automáticamente a Claude Code en un sistema operativo del negocio ni eliminan la coordinación humana.

Los fundamentales:

• Context isolation — pasale lo necesario al subagente, no asumas contexto
• Elegí el pattern correcto — fan-out para paralelo, pipeline para secuencial, orchestrator para coordinación justificada
• No abuses — si la tarea es simple, hacela directo
• Especificá el output — el subagente no adivina qué formato querés
• Usá background con límites — duración, observabilidad y condición de parada

Si querés decidir qué capa necesita un proceso concreto, hablemos de tu proceso.