Cómo delegar una tarea grande en Claude Code usando subagentes anidados

¿Qué cambió en Claude Code v2.1.172?#

Si has leído algo sobre agentes de IA en Claude Code durante los últimos meses, te habrás encontrado con la misma frase. Está en la documentación oficial, en mi guía sobre subagentes y en el análisis de cada competidor. Dice así: «un subagente no puede crear otro subagente». Al 11 de junio de 2026, esa frase todavía aparece en tres lugares distintos de code.claude.com/docs/en/sub-agents. Anthropic simplemente aún no la ha actualizado.

El 10 de junio a las 20:44 UTC, Claude Code v2.1.172 apareció en GitHub Releases. El principal elemento del registro de cambios era una línea:

Esta misma versión también corrigió un error que solo podía ocurrir con el anidamiento: un subagente en segundo plano seguía resaltado como activo en el panel de agentes después de que se detuviera el subagente anidado que había lanzado.

Es un caso poco común en el que la documentación oficial sigue contradiciendo la versión publicada. A continuación explicaré en qué se diferencia el anidamiento de los subagentes paralelos, qué significa «profundidad 5» y en qué tres escenarios resulta realmente útil hoy.

¿En qué se diferencian los subagentes anidados, paralelos y secuenciales de Claude Code?#

Pasé mucho tiempo probando a mano estos tres enfoques, y así es como los entiendo: la delegación tiene tres dimensiones. Anchura, longitud y profundidad. Cada una resuelve un problema distinto.

Anchura: subagentes paralelos. El chat principal lanza N subagentes independientes en el mismo nivel. Cada uno recibe una tarea acotada, trabaja en su propia ventana aislada y devuelve solo el resultado. La anchura resuelve la velocidad: 5 subagentes trabajando en paralelo terminan en el tiempo que le toma a uno hacer el mismo trabajo secuencialmente. Este es el modelo que describí en mi guía sobre subagentes paralelos usando worktrees.

Longitud: una cadena de subagentes. A trabaja y le pasa el resultado a B; B trabaja y se lo pasa a C. Cada uno ve la entrada del anterior. La longitud establece el orden: B no puede empezar hasta recibir los datos de A. Un ejemplo clásico: primero un subagente de investigación reúne fuentes; luego uno de edición redacta un artículo a partir de esas fuentes; y después uno de verificación de datos revisa el artículo. Es una secuencia plana; el chat principal conserva toda la historia.

Profundidad: subagentes anidados. A lanza B, B lanza C y C lanza D. Cada hijo trabaja dentro de su padre, en su propia ventana aislada, y devuelve solo el resultado a su padre. El chat principal no ve nada de lo que ocurre en los hijos, nietos y bisnietos. Esto es lo nuevo de v2.1.172.

La principal confusión es que la gente piensa que profundidad 5 significa «puedes lanzar 5 subagentes simultáneamente». No es así. La profundidad es un nivel vertical del árbol, no el número de hijos simultáneos. Puede haber un subagente o cien en cada nivel. Profundidad 5 significa que la cadena de delegación puede bajar 5 pasos: chat principal → nieto-1 → nieto-2 → nieto-3 → nieto-4 → nieto-5. Y puede haber ramificaciones en cada nivel.

La versión 2.1.172 eliminó la regla que impedía a un subagente crear otro subagente.

Si buscas velocidad, necesitas anchura. Si tienes un orden de ejecución estricto, necesitas longitud. La profundidad es útil en un solo caso: cuando una de tus tareas contiene una subtarea ruidosa (15 solicitudes web, recorrer registros, leer una docena de archivos). Y no quieres que ese ruido inunde tu ventana principal.

¿Qué significa en la práctica «5 niveles de profundidad»?#

Aquí hay un punto importante de honestidad. Pasé medio día revisando documentación y análisis de la comunidad para descubrir que Anthropic no ha dado una definición precisa. Esto es lo que necesitas saber.

Es un límite, no un ajuste.

El límite está integrado en el servidor. La ingeniería inversa de la versión cliente v2.1.172 no encontró ninguna constante MAX_DEPTH. Eso significa que la comprobación ocurre en algún lugar de la API de Anthropic, no localmente en tu máquina. No puedes configurar --max-depth 7 para hacer más profundo el árbol. Tampoco puedes configurar --max-depth 2 para establecer un límite inferior y más seguro. El único control que tienes es la lista de permitidos Agent(agent_type) en el frontmatter, pero limita los tipos de agentes hijos, no la profundidad.

Anthropic no ha definido con precisión qué significa «5». Este es el segundo punto importante:

Anthropic no ha definido con precisión qué significa «5». Las fuentes oficiales no especifican si depth=5 significa cinco niveles por debajo de la raíz o cinco agentes en total, incluida la raíz.

Por ahora, las integraciones de terceros lo interpretan de distintas maneras. La ADR-147 del proyecto ruvnet/ruflo supone «5 niveles hijos por debajo de la raíz = 6 agentes en la cadena». Yo uso la misma convención en mis experimentos: el chat principal está en el nivel 0, sus hijos directos en el nivel 1, y así sucesivamente hasta el nivel 5. Pero esto no está recogido en la documentación pública.

El límite ya está habilitado, sin opciones. No necesitas activar nada. Después de actualizar Claude Code a v2.1.172, puedes añadir Agent a tools de un agente hijo, y este lanzará otro subagente. La clave es que el agente padre debe permitirlo (tools: Agent(...)).

¿Dónde ocurre hoy tu delegación: en anchura, longitud o profundidad?#

Repasa tus últimos 5 prompts. ¿Cuántas veces te ha pasado esto: empieza una tarea, Claude comienza a buscar archivos con grep, hace 10 solicitudes web, vuelca un muro entero de registros en el contexto y, 20 minutos después, te das cuenta de que la ventana está llena? La respuesta final ya se está generando con un presupuesto de tokens escaso porque el 70 por ciento del contexto se consumió con volcados intermedios.

Ese es un escenario en el que necesitas profundidad. No paralelismo ni una cadena: profundidad. El chat principal debería delegar la «investigación» a un subagente, que después lanza sus propios hijos desde dentro para búsquedas web, lecturas de archivos y búsquedas con grep específicas. Los hijos devuelven solo conclusiones resumidas. Un nieto le dice a su padre: «lo encontré, confirmado» o «no lo encontré, razón X». El padre reúne esa información en un único resumen y te lo devuelve. El chat principal se mantiene despejado.

Antes del 9 de junio, yo lo imitaba a mano. Abría una segunda instancia de Claude Code, copiaba el prompt «investiga esto», lo ejecutaba y luego transfería manualmente el resultado a la ventana principal. Describí esta configuración en detalle en mi guía sobre delegar tareas de programación a muchos agentes de IA. Con v2.1.172, puedes describirla directamente en el prompt del sistema del orquestador: Claude construirá el árbol por sí mismo.

¿Quieres entender los subagentes anidados y también crear una configuración que haga fiable a Claude? El anidamiento es solo una pieza. La configuración completa contiene los tres pilares: Clon de IA + Segundo Cerebro + Ingeniería de Contexto; eso es lo que convierte a Claude de «un asistente que alucina» en una herramienta fiable.

¿En qué 3 escenarios son realmente útiles los subagentes anidados?#

Escenario 1. Investigación profunda con verificación de datos

Supón que estás recopilando material para un artículo o una propuesta de ventas. Primero tienes que extraer 5–10 afirmaciones de fuentes públicas y luego verificar cada una: encontrar la fuente original, asegurarte de que la cita sea exacta y calcular las cifras reales.

Antes de v2.1.172, tenías dos opciones. O lo hacías todo con un solo subagente, que se las arreglaba con 30 solicitudes web y metía todo en su contexto. O lo dividías manualmente: un prompt para extraer las afirmaciones y luego un ciclo sobre ellas, lanzando un subagente distinto para cada una. El chat principal se llenaba de muros de listas intermedias.

En la receta siguiente, el chat principal delega a research-orchestrator (nivel 1). El orquestador extrae las afirmaciones por sí mismo, envía cada una a fact-verifier (nivel 2) y cada verificador delega búsquedas concretas a web-deep-search (nivel 3). El chat principal recibe solo una matriz de afirmaciones verificadas con sus fuentes. Todo lo demás permanece en las ventanas de los hijos y nunca entra en tu contexto.

Escenario 2. Analizar un repositorio grande

Te han dado un proyecto con 200 archivos. Necesitas entender la arquitectura, encontrar los módulos principales y evaluar la deuda técnica. Ejecuta Glob y una docena de llamadas a Read a mano y llenarás la ventana en 10 minutos.

La profundidad lo resuelve así: el chat principal lanza un subagente «arquitecto». El arquitecto crea internamente tres hijos: uno inspecciona la estructura de directorios (ejecuta Glob y resume), el segundo lee 5 archivos de configuración clave y el tercero busca patrones principales con grep. Cada uno devuelve un resumen conciso al arquitecto. El arquitecto reúne la información y entrega al chat principal un informe final de media pantalla. Obtienes un mapa del proyecto sin inundar el contexto con un muro de resultados de cat de todos los archivos.

Escenario 3. Analizar dependencias de extremo a extremo

Vas a cambiar un esquema de base de datos, un contrato de API o un archivo de configuración compartido. Necesitas entender dónde se manifestarán los efectos. Esta tarea acaba con el contexto más rápido porque hay muchas dependencias y cada una debe comprobarse en el código fuente.

Con profundidad, el chat principal lanza un impact-analyzer (nivel 1). Este lanza un dependency-tracer por cada archivo afectado (nivel 2). Cada trazador lanza internamente un consumer-finder (nivel 3), que busca con grep en la base de código los consumidores de esa dependencia. Luego cada uno devuelve solo lo esencial: «estos tres lugares dejarán de funcionar». El chat principal reúne una tabla de «archivos afectados → impacto» sin conocer los resultados de grep.

Cómo configurar subagentes anidados en 10 minutos#

Paso 1. Asegúrate de estar en v2.1.172 o superior.

claude --version

Si es inferior, actualiza. La función principal de la versión es una línea en el registro de cambios: «Los subagentes ahora pueden crear sus propios subagentes, hasta 5 niveles de profundidad» (texto completo).

Paso 2. Crea un agente padre que pueda crear hijos.

Archivo .claude/agents/research-orchestrator.md:

---
name: research-orchestrator
description: Delega la investigación con una verificación de datos profunda
tools: Agent(fact-verifier), Read, WebFetch
model: opus
---

Eres un orquestador de investigación. Al recibir un tema:
1. Lee el material suministrado o consulta sus URL públicas.
   Extrae por ti mismo hasta 5 afirmaciones concretas. Para cada una, registra
   texto, URL o archivo de origen y pasaje exacto que la respalda.
   Si no se aportó material, pídelo antes de delegar.
2. Para cada afirmación, llama a fact-verifier: este generará por su cuenta
   sus propios subagentes hijos para buscar y contrastar información en la web.
3. fact-verifier te devolverá solo los veredictos finales:
   no cargues volcados intermedios en tu contexto.

El informe final debe ser solo una matriz { claim, sources[], confidence }.

La línea tools permite solo el tipo hijo fact-verifier. El orquestador extrae las afirmaciones en su primer paso, por lo que no necesita un archivo claim-extractor sin definir. Una lista de tipos limita cuáles pueden llamarse, no cuántas veces. Acota la receta a un máximo de cinco afirmaciones extraídas.

Paso 3. Crea un agente hijo que pueda crear nietos por su cuenta.

Archivo .claude/agents/fact-verifier.md:

---
name: fact-verifier
description: Verifica una afirmación mediante búsquedas web de agentes hijos
tools: Agent(web-deep-search), Read
model: sonnet
---

Eres un verificador de datos. Al recibir una afirmación:
1. Formula 2-3 consultas de búsqueda.
2. Para cada una, ejecuta web-deep-search: este hará por su cuenta
   WebSearch y WebFetch y devolverá fragmentos verificados.
3. Resume todo en un veredicto: { claim, sources[], confidence }.

¿Ves la parte clave? tools vuelve a decir Agent(web-deep-search). Eso significa que el verificador de datos (nivel 2 en nuestro árbol) puede lanzar otro subagente por su cuenta (nivel 3). Antes, esta línea no tenía efecto; la documentación aún contiene la frase:

Con v2.1.172, esa línea está desactualizada. La sintaxis es la misma, pero ahora funciona a cualquier profundidad del árbol.

Paso 4. Crea un bisnieto.

Archivo .claude/agents/web-deep-search.md:

---
name: web-deep-search
description: Realiza búsquedas web y devuelve fragmentos
tools: WebSearch, WebFetch
model: haiku
---

Has recibido una consulta de búsqueda. Haz una búsqueda web, elige los 3 URL más pertinentes y usa WebFetch para extraer pruebas textuales que respalden la afirmación. Devuelve una matriz { url, snippet, supports_claim: yes|no }.

El bisnieto no tiene Agent en tools, así que no crea más agentes hacia abajo en el árbol.

Paso 5. Ejecuta el orquestador.

claude --agent research-orchestrator

Aporta después texto o URL públicas: «Extrae y verifica hasta 5 afirmaciones concretas de estas fuentes; devuelve afirmaciones, fuentes y confianza». Con --agent research-orchestrator, la propia sesión es el orquestador; sus verificadores y buscadores añaden dos niveles delegados por debajo. Si una sesión principal normal delega al orquestador, hay tres niveles por debajo de esa principal.

¿Qué 5 antipatrones desperdician tokens y destruyen la observabilidad?#

Antipatrón 1. La tarea cabe en una ventana.

Si un subagente puede encargarse sin generar ruido, no añadas niveles: el anidamiento solo añade coste y latencia.

Antipatrón 2. Buscas velocidad en vez de aislamiento.

Si quieres velocidad, necesitas paralelismo, no profundidad. Lanza 5 subagentes uno al lado del otro en el mismo nivel, en vez de crear una cadena. La profundidad sirve para trasladar el trabajo preparatorio ruidoso a la ventana de un hijo, no para acelerar las cosas.

Antipatrón 3. El trabajo es intrínsecamente superficial.

«Encuentra este archivo y muéstramelo» es una solicitud de dos pasos; no necesita una jerarquía de tres niveles. El anidamiento merece la pena cuando una tarea contiene una subtarea ruidosa. Si no hay ruido, no añadas subagentes.

Antipatrón 4. Prompts vagos en el primer nivel.

Este es el escenario más peligroso. Si das un prompt vago al orquestador de nivel 1, la vaguedad se multiplica. Un prompt vago en el nivel 1 se convierte en 4 prompts vagos en el nivel 2 y 16 en el nivel 3. Cuando los nietos empiezan a trabajar, ni siquiera saben qué están buscando.

Antipatrón 5. Crecimiento geométrico del coste.

El principal argumento económico: el anidamiento multiplica el uso de tokens, y la multiplicación se acumula con la profundidad.

Un cálculo aproximado: una cadena de profundidad 3 con una ramificación de 3 en cada nivel significa 27 subagentes. Eso supone al menos 27 veces más tokens que una solicitud simple. Con el plan Pro de Claude, ese cálculo agota el límite diario en un par de horas. Si tienes un plan Max, agotarás la cuota de una semana en un día.

Antipatrón extra (según mi experiencia): «50 agentes haciendo trabajo inútil».

Cuando miro los proyectos de otras personas, suelo ver esto: «Tengo 50 agentes trabajando». Pregunto qué hacen. Y esos 50 agentes están haciendo trabajo inútil. Generan montones de resultados innecesarios, toneladas de resúmenes sin procesar, duplicados y muros de registros. Cada uno hace algo «útil en general», y el resultado es un contexto inundado y una factura de tokens como la de una pequeña empresa. La profundidad 5 no resuelve este problema: lo empeora. Si ya no está claro en el nivel 1 quién hace qué, profundidad 5 significa cinco niveles de confusión.

Antes de lanzar cualquier subagente, compruébalo respondiendo estas 4 preguntas en medio minuto:

• ¿Qué hace exactamente (en una frase)?
• ¿Qué archivos modifica?
• ¿Qué devuelve a su padre?
• ¿Quién lo comprueba?

Si no puedes responder en 30 segundos, ese subagente no debería existir. Expliqué esta regla por separado en mi guía sobre subagentes paralelos.

¿Por qué anidar sin ingeniería de contexto significa 5 niveles de alucinaciones?#

Aquí es donde la gente suele preguntar: «Actualicé Claude Code, añadí Agent a tools y el árbol se está construyendo, pero la respuesta final sigue siendo incorrecta. ¿Por qué?»

La respuesta es sencilla. Cada subagente en Claude Code empieza desde cero. Según la documentación oficial:

En el nivel 1, esto es manejable: el orquestador pasa una descripción breve de la tarea a su hijo. Pero en el nivel 3, el bisnieto recibe un mensaje de delegación de su padre, que también recibió solo un mensaje de delegación. Cada uno transmitió un poco. En el nivel 5, tienes un subagente cuya ventana contiene la frase «comprueba la afirmación X» y nada más. No sabe en qué proyecto trabaja, qué tarea está resolviendo ni en qué debe centrarse.

Sin CLAUDE.md, un bisnieto de nivel cinco es como un empleado que llega a la oficina por primera vez en su vida sin recibir ninguna orientación. Hará algo porque recibió una tarea. Pero no será lo que necesita el proyecto.

Por eso la configuración es esencial. La profundidad 5 sin un CLAUDE.md bien configurado, business/ y un flujo de habilidades es un casino. Con ellos, es una herramienta. Esta configuración se describe como los «Tres pilares»: Clon de IA + Segundo Cerebro + Ingeniería de Contexto. Cada uno funciona mal por sí solo; juntos, los tres convierten el anidamiento en una herramienta realmente útil.

¿Qué más cambió en v2.1.172 además del anidamiento?#

Abre el registro de cambios completo de v2.1.172 y verás que toda la versión gira en torno a los subagentes.

Corrección 1. Un subagente en segundo plano ya no se queda «atascado» como activo en el panel de agentes después de que se detenga el subagente anidado que lanzó. Este error solo puede ocurrir con el anidamiento.

Corrección 2. Las restricciones de availableModels ahora también se aplican a los subagentes. Antes, si limitabas los modelos que podía usar el equipo (por ejemplo, prohibiendo opus para ahorrar dinero), los subagentes podían saltarse la regla mediante una sobrescritura en su propia configuración. Con v2.1.172, la regla se aplica en todas partes.

Corrección 3. La flecha hacia arriba del historial de prompts ahora muestra los prompts de la pestaña actual del subagente, no los del agente principal. Un retoque de observabilidad.

Corrección 4. Se reduce el uso de CPU en reposo: el indicador /goal ya no vuelve a dibujar el terminal a 5 Hz cuando está inactivo, y la interfaz se vuelve a dibujar con menos frecuencia mientras trabajan subagentes paralelos.

Señalaré que las cuatro correcciones se refieren a los subagentes. Eso significa que Anthropic publicó toda la infraestructura de anidamiento, no solo una línea en el registro de cambios. El anidamiento ya se utilizaba dentro de Anthropic desde hacía algún tiempo antes de su publicación.

Lista de comprobación: cuándo ayuda el anidamiento y cuándo perjudica#

Usa el anidamiento si:

• La tarea contiene una subtarea con muchas solicitudes web, búsquedas con grep o lecturas de archivos.
• Es aceptable perder esa subtarea (si el bisnieto responde «no encontré nada», el orquestador puede continuar).
• No necesitas los resultados intermedios en la ventana principal.
• Tienes un CLAUDE.md y un contexto del proyecto reunido en el que pueda apoyarse el subagente.
• Puedes describir claramente qué devolverá cada nivel (entrada, salida, formato).
• Tienes un plan Max o margen para ×27 tokens.

No uses el anidamiento si:

• Un subagente puede resolver la tarea sin ruido.
• Necesitas los resultados intermedios en la ventana principal (eso significa que quieres paralelismo).
• El proyecto no tiene CLAUDE.md o solo contiene escaso contexto empresarial.
• Los prompts del nivel 1 son vagos (la vaguedad se multiplicará exponencialmente por el árbol).
• Necesitas velocidad: el paralelismo es más rápido que la profundidad para un resultado comparable.
• Tienes el plan Pro y trabajas todo el día: agotarás el límite en un par de horas.

Flujo de trabajo de contexto completo: Clon de IA + Segundo Cerebro + Ingeniería de Contexto.

Hay más materiales disponibles en Ailoot.