Si usás Claude Code para algo más que preguntas sueltas, en algún momento vas a necesitar subagentes. Es la feature que transforma a Claude de asistente a sistema.

Yo corro un sistema de 20 agentes organizados en 8 áreas de negocio — producto, contenido, crecimiento, operaciones, inteligencia, ventas, finanzas y legal. Cada área tiene un jefe que coordina subagentes especializados. Todo funciona sobre Claude Code.

Este artículo es la guía técnica que me hubiera gustado tener cuando empecé. Qué son los subagentes, cómo funcionan por dentro, cuándo conviene usarlos, los 4 patterns principales de arquitectura, y los errores que vas a cometer si no los entendés bien.

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.

Cuando le pedís a Claude Code que use un subagente, lo que pasa internamente es esto:

Claude crea una nueva instancia con instrucciones específicas
Esa instancia recibe un prompt con la tarea a realizar
El subagente trabaja de forma independiente (no ve tu conversación principal)
Cuando termina, devuelve un resultado al agente padre
El padre integra ese resultado en su flujo

La diferencia fundamental con hacer todo en una sola conversación: el subagente tiene su propio contexto aislado. No comparte la ventana de contexto del padre. Esto es una ventaja y una trampa al mismo tiempo — ya vamos a ver por qué.

Cómo funciona internamente

Detrás de escena, los subagentes se manejan con el Agent tool — una herramienta interna de Claude Code que permite lanzar instancias hijas.

Los parámetros clave

Agent tool:
  prompt: "La tarea específica que debe hacer el subagente"
  subagent_type: "research" | "code" | "general"
  isolation: "none" | "worktree"
  run_in_background: true | false

prompt — Lo más importante. Es TODO lo que el subagente va a saber. Si no se lo decís acá, no lo sabe. No hay magia, no hay herencia de contexto.

subagent_type — Define el perfil del subagente:

research: optimizado para buscar información, leer archivos, analizar código. No hace cambios.
code: puede leer Y escribir código, ejecutar comandos, hacer commits.
general: perfil balanceado para tareas mixtas.

isolation — Cómo se aísla el subagente del sistema de archivos:

none: comparte el mismo directorio de trabajo que el padre. Más rápido, pero si dos subagentes editan el mismo archivo hay conflicto.
worktree: crea un git worktree temporal. El subagente trabaja en una copia aislada del repositorio. Ideal para cambios de código que podrían conflictuar.

run_in_background — Si es true, el subagente corre en background y el padre puede seguir trabajando sin esperarlo. Fundamental para tareas paralelas.

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 hablar con el padre durante la ejecución. No hay ida y vuelta. Le das las instrucciones, trabaja, y devuelve el resultado. Es fire-and-forget con resultado.

Cuándo usar subagentes vs hacerlo directo

No todo necesita un subagente. De hecho, usarlos cuando no hacen falta agrega overhead innecesario — más tokens, más tiempo, más complejidad.

Esta es la tabla de decisión que uso:

Situación	Estrategia	Por qué
Tarea simple, 1-2 archivos	Directo	El overhead del subagente no se justifica
Fix de un typo o bug puntual	Directo	Crear un subagente para esto es como matar moscas a cañonazos
Investigar un tema que puede ser extenso	Subagente	Evitás saturar el contexto principal con información que quizás no necesitás toda
3+ tareas independientes entre sí	Subagentes en paralelo	Termina más rápido y cada tarea tiene contexto limpio
Tarea que involucra muchos archivos	Subagente con worktree	Aislamiento de cambios para evitar conflictos
Auditoría o análisis multi-dimensión	Fan-out con N subagentes	Cada especialista analiza un aspecto diferente
Pipeline con dependencias	Subagentes en secuencia	Output de A es input de B

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 la tarea es lo suficientemente grande como para beneficiarse de contexto limpio — subagente.

Los 4 patterns principales

Después de un año trabajando con subagentes, identifiqué 4 patterns que cubren el 95% de los casos de uso. Cada uno tiene su momento ideal.

1. Fan-out / Gather

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

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

Caso real: mi auditoría SEO. Cuando corro /seo-audit, el growth-lead lanza 6 subagentes especializados en paralelo:

Uno analiza los Core Web Vitals
Otro revisa la estructura de headings y meta tags
Otro evalúa el schema markup
Otro analiza el sitemap y la indexación
Otro revisa los internal links
Otro hace análisis de competencia

Cada subagente trabaja con run_in_background: true. Cuando todos terminan, el growth-lead consolida los 6 reportes en un score general con prioridades ordenadas.

Tiempo sin fan-out: 15-20 minutos en secuencia. Tiempo con fan-out: 4-5 minutos en paralelo.

Cuándo usarlo: cuando tenés múltiples análisis independientes que no dependen entre sí y querés el 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 → Publish
   ↓         ↓        ↓        ↓
 datos     borrador  feedback  versión final

Caso real: mi pipeline de contenido. Cuando pido "escribí un artículo de blog sobre X":

intel-lead investiga el tema (busca en la web, revisa mis fuentes, analiza competencia)
Su output va al copywriter que escribe el draft completo en MDX
Ese draft va al seo-specialist que optimiza titles, descriptions, headings, internal links
El resultado final vuelve al content-lead que lo entrega

Cada paso necesita el output del anterior, por eso es secuencial. Pero cada paso se ejecuta en un subagente con contexto limpio — el copywriter no necesita cargar toda la investigación bruta, solo recibe el brief procesado.

Cuándo usarlo: cuando las tareas tienen dependencias claras (B necesita el resultado de A).

3. Orchestrator-Worker

Un jefe inteligente que analiza la tarea, decide qué workers necesita, los lanza, y consolida.

         Orchestrator (Opus)
        ↙     ↓      ↓     ↘
  Worker A  Worker B  ...  Worker N
  (Sonnet)  (Sonnet)       (Sonnet)

Este es el pattern de mi sistema completo. El orquestador nunca implementa — solo analiza, descompone, delega y consolida.

Caso real: mi sistema de 8 áreas.

# Estructura real de mi sistema
Orquestador (Opus):
  - Recibe cualquier pedido
  - Identifica qué área(s) le corresponde
  - Delega al jefe de área correspondiente
  - El jefe de área delega a sub-agentes si hace falta

Ejemplo: "Necesito lanzar una campaña nueva"
  → content-lead: briefing + copy + assets
  → growth-lead: SEO + analytics tracking
  → ops-lead: workflows en n8n + CRM setup

Cada jefe de área es un subagente Opus que coordina sub-agentes Sonnet. El orquestador solo habla con los jefes, nunca con los workers directamente. Esto mantiene la cadena de mando limpia.

Reglas del orchestrator-worker que aprendí a las malas:

No-callback rule: si el área A llama al área B, B no puede llamar de vuelta a A. Evita loops infinitos.
Max depth 3: cadenas de delegación nunca superan 3 niveles. Más que eso es señal de que la tarea está mal descompuesta.
Handoffs explícitos: la comunicación entre áreas se documenta en archivos de handoff (intel→content.md), no en la conversación.

Cuándo usarlo: cuando tenés un sistema complejo con múltiples especialidades y necesitás coordinación inteligente.

4. Background Monitor

Un subagente que corre en background vigilando algo mientras vos seguís trabajando.

# Combinación de /loop + subagente
/loop 5m chequeá que el deploy responde 200 en todas las rutas

O más sofisticado: un subagente en background que monitorea cambios en archivos, logs de error, o métricas.

Caso real: después de cada deploy, lanzo un subagente en background con run_in_background: true que:

Espera 2 minutos para que el deploy se estabilice
Hace health checks en las rutas principales
Verifica que no hay errores nuevos en los logs de Vercel
Me reporta el resultado

Mientras tanto, yo sigo trabajando en la siguiente tarea.

Cuándo usarlo: monitoreo post-deploy, vigilancia de métricas, cualquier tarea que necesite polling periódico sin interrumpir tu flujo.

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 el contexto 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, este NO 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 sabe lo que le pasás en el prompt. Nada más.

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..."
[... 20 mensajes de ida y vuelta sobre la migración ...]
Vos: "Ahora usá un subagente para migrar el componente Header"

El subagente que se lanza no sabe nada de la migración. No sabe que estás pasando de CSS modules a Tailwind v4. No sabe las convenciones que acordaste con el padre. No sabe qué archivos ya migraste.

Si el padre no le pasa toda esa información explícitamente en el prompt, el subagente va a hacer cualquier cosa.

Cómo hacerlo bien

El prompt del subagente tiene que ser autosuficiente. Todo lo que necesita saber tiene que estar ahí:

# 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
  - Colores custom: bg-background (#08080A), text-emerald (#34D399)
  - 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 es no. Ponelo en el prompt.

Worktrees para aislamiento de código

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

Sin aislamiento (isolation: "none") — el subagente trabaja en tu directorio de trabajo actual
Con worktree (isolation: "worktree") — el subagente trabaja en una copia temporal del repositorio

Cuándo usar worktrees

Cuando dos o más subagentes van a editar código al mismo tiempo (fan-out con cambios de código)
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

Internamente, Claude Code crea un git worktree — una feature nativa de git que permite tener múltiples copias de trabajo de un mismo repositorio sin clonar todo de nuevo.

# Lo que Claude Code hace por vos:
git worktree add /tmp/claude-worktree-abc123 HEAD
# El subagente trabaja en ese directorio
# Al terminar, los cambios se pueden mergear o descartar

El subagente trabaja en su copia aislada. Si todo sale bien, los cambios se incorporan al directorio principal. Si algo falla, se descarta sin impacto.

Lo que NO hay que hacer

No uses worktrees para todo. Crear un worktree tiene overhead — tarda más en inicializarse, usa más disco, y mergear los cambios de vuelta puede generar conflictos si modificaste los mismos archivos en paralelo.

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

Ejemplo práctico: mi sistema de contenido

Veamos cómo funciona todo junto con un ejemplo real de mi día a día.

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

Lo que pasa internamente:

Paso 1: content-lead recibe la tarea

El content-lead (jefe de área de contenido, modelo Opus) analiza el pedido y decide que necesita:

Investigación actualizada sobre MCP
Un draft del post en formato LinkedIn
Revisión de que no se repita contenido ya publicado

Paso 2: lanza intel-lead para investigar

Subagente: intel-lead
Tipo: research
Prompt: |
  Investigá el estado actual de MCP (Model Context Protocol) de Anthropic.

  Buscá:
  - Últimas actualizaciones y versiones
  - Casos de uso más populares
  - Números de adopción si existen
  - Herramientas/servers MCP más usados

  Output: brief de 300-500 palabras con datos concretos y fuentes.

El intel-lead trabaja: busca en la web, revisa mis fuentes en NotebookLM, consulta documentación actualizada. Devuelve un brief con los datos clave.

Paso 3: lanza copywriter para escribir

Subagente: copywriter
Tipo: general
Prompt: |
  Escribí un post de LinkedIn sobre MCP (Model Context Protocol).

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

  Formato: post LinkedIn, max 1300 caracteres
  Voz: argentino/rioplatense, directo, técnico pero accesible
  Público: emprendedores y devs que usan IA
  Hook: dato concreto o pregunta provocadora
  CTA: comentario o link al blog

  Revisar content-log.md para no repetir temas ya publicados.

El copywriter recibe el brief procesado (no la investigación bruta) y escribe el post.

Paso 4: consolidación

El content-lead recibe el post, hace ajustes finales si hace falta, y lo entrega listo para publicar.

Tiempo total: 3-4 minutos. Sin subagentes: 15-20 minutos (investigar + escribir + revisar, todo en la misma conversación, con contexto saturado).

La ganancia no es solo velocidad — es calidad de contexto. Cada subagente trabaja con contexto limpio y enfocado en su tarea específica, en vez de una conversación gigante donde Claude tiene que hacer malabares con toda la información a la vez.

Errores comunes (y cómo evitarlos)

Después de meses trabajando con subagentes, estos son los errores que más veo — en mi propio sistema y en el de otros.

1. Asumir que el subagente hereda contexto

Ya lo cubrimos, pero vale repetirlo: el subagente no sabe nada que no le digas. No ve tu conversación. No sabe lo que acordaste con el padre. No tiene "contexto implícito".

Solución: tratar el prompt del subagente como si fuera un brief para un freelancer que no sabe nada de tu proyecto. Todo lo que necesita tiene que estar ahí.

2. Lanzar demasiados subagentes en paralelo

Claude Code tiene límites de concurrencia. Si lanzás 10 subagentes al mismo tiempo, no van a correr los 10 en paralelo — algunos van a quedar en cola, y el overhead de gestión puede superar el beneficio del paralelismo.

Solución: para la mayoría de las tareas, 3-5 subagentes en paralelo es el sweet spot. Si necesitás más, agrupá tareas relacionadas en un solo subagente.

3. No especificar el output esperado

Si le decís al subagente "investigá sobre X" sin decirle qué formato querés el resultado, vas a recibir cualquier cosa — desde un párrafo hasta un ensayo de 3000 palabras.

Solución: siempre incluir en el prompt:

Qué formato querés (lista, párrafo, JSON, archivo)
Qué longitud aproximada
Qué información específica necesitás en el output

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

# Bien
prompt: |
  Investigá las 5 tendencias principales de IA en 2026.
  Output: lista numerada, cada tendencia con título (1 línea)
  y descripción (2-3 líneas). Total: max 500 palabras.

4. Usar subagentes para tareas triviales

Cada subagente tiene overhead: inicialización, transferencia de contexto, consolidación de resultados. Para una tarea que tarda 30 segundos hacerla directo, el subagente va a tardar más.

Solución: si la tarea es simple, rápida, y no necesita contexto limpio ni paralelismo — hacela directo. No todo necesita delegación.

Mi regla de 2 minutos: si estimo que la tarea tarda menos de 2 minutos hacerla directo, no uso subagente.

5. No usar run_in_background cuando podrías

Si lanzás un subagente sin run_in_background, el padre se queda esperando a que termine. Si la tarea tarda 5 minutos, son 5 minutos que perdiste pudiendo hacer otra cosa.

Solución: siempre que la tarea del subagente sea independiente del flujo inmediato, usá run_in_background: true. El padre sigue trabajando y recibe el resultado cuando está listo.

6. Prompts demasiado largos o demasiado cortos

Si el prompt tiene 3 palabras, el subagente no tiene suficiente contexto. Si tiene 5000 palabras, estás desperdiciando tokens y probablemente incluyendo información irrelevante que distrae.

Solución: el prompt ideal tiene:

Contexto: lo mínimo necesario para entender la tarea (5-10 líneas)
Tarea: qué tiene que hacer, concreto (2-3 líneas)
Output: qué formato y qué incluir en el resultado (2-3 líneas)
Restricciones: qué NO hacer si es relevante (1-2 líneas)

7. No tener un sistema de comunicación entre áreas

Cuando tenés múltiples subagentes que trabajan en el mismo proyecto, inevitablemente un área necesita información de otra. Sin un sistema de comunicación, esto se convierte en caos.

Solución: yo uso archivos de handoff en .claude/shared/handoffs/. Cuando intel-lead tiene información relevante para content-lead, la deja en intel→content.md. El content-lead sabe que tiene que leer ese archivo antes de empezar.

Configuración del sistema de agentes con CLAUDE.md

Todo el sistema de subagentes se configura a través de archivos .md en la carpeta .claude/agents/. Cada agente tiene su propio archivo con:

# Estructura de un archivo de agente
Rol: qué es y qué hace
Modelo: Opus (jefes) o Sonnet (workers)
Herramientas: qué MCPs y tools 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 del proyecto define la arquitectura general — qué agentes existen, cómo se organizan, y las reglas de comunicación. Cada agente hereda ese contexto base al inicializarse.

Esto es lo que hace que el sistema sea mantenible. Si necesito cambiar cómo trabaja el seo-specialist, edito un solo archivo. Si necesito agregar un nuevo agente, creo un archivo nuevo y lo registro en la arquitectura.

Lo que viene: Agent Teams

Anthropic está trabajando en Agent Teams — la evolución nativa de lo que muchos estamos construyendo manualmente con subagentes.

La idea: en lugar de configurar toda la orquestación vos mismo, Claude Code va a tener primitivas nativas para definir equipos de agentes con roles, permisos, y flujos de comunicación predefinidos.

Esto no reemplaza el conocimiento de cómo funcionan los subagentes — lo hace más accesible. Entender los patterns de este artículo te va a dar ventaja para aprovechar Agent Teams cuando esté disponible.

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

Recursos relacionados

Si querés profundizar en temas específicos:

Cómo Construí un Sistema de 20 Agentes con Claude Code — la arquitectura completa de mi sistema, con diagramas y decisiones de diseño
Cómo Uso Claude Code para mi Consultoría — el caso de uso real completo, con métricas de antes/después
Claude Code Novedades 2026 — Agent Teams, /loop, y todo lo que viene
7 Funciones Ocultas de Claude Code — worktrees, hooks, skills, y más features que casi nadie usa
MCP: Guía Completa del Model Context Protocol — cómo conectar herramientas externas a tus agentes

Conclusión

Los subagentes son la feature que transforma a Claude Code de "asistente inteligente" a "sistema operativo de tu negocio". Pero como toda herramienta poderosa, necesitás entender cómo funciona para usarla bien.

Los fundamentales:

Context isolation es lo más importante — pasale todo al subagente, no asumas nada
Elegí el pattern correcto — fan-out para paralelo, pipeline para secuencial, orchestrator para coordinación
No abuses — si la tarea es simple, hacela directo
Especificá el output — el subagente no adivina qué formato querés
Usá background cuando podés — no te quedes esperando si no es necesario

Si querés diseñar un sistema multi-agente para tu proyecto o tu negocio, agendá una llamada introductoria. En 15 minutos evaluamos si tiene sentido para tu caso y cómo arrancar.

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