Harness recursivo en Claude Code: subagentes anidados 2026

TL;DR

Un harness recursivo es un agente completo (con herramientas de ficheros, ejecución de código y planificación) que se invoca a sí mismo lanzando otros agentes, no una simple llamada al modelo dentro de otra llamada.
El paper Recursive Agent Harnesses (RAH, junio 2026) muestra que dejar al agente escribir código que lanza subagentes supera al esquema clásico de tool calling cuando la tarea es grande.
En Claude Code hoy puedes aprovechar el patrón, pero con un límite real: un subagente no puede crear sub-subagentes. El truco está en orquestar desde el agente principal con fan-out en paralelo y skills.

El problema: una tarea no cabe en una sola cabeza

Cuando le pides a un agente que procese un documento de 300 páginas, que refactorice 40 ficheros o que audite un monorepo entero, el cuello de botella no es el modelo. Es el contexto. Todo entra en la misma ventana, se mezcla, y a partir de cierto punto el agente empieza a olvidar lo que hizo hace diez pasos.

La respuesta intuitiva es delegar: que un agente principal reparta el trabajo en piezas y lance especialistas, cada uno con su propia ventana limpia. Eso es exactamente lo que hace Claude Code con los subagentes. Pero hay una pregunta más profunda que un paper reciente pone sobre la mesa: ¿y si esos especialistas también pudieran delegar? ¿Hasta dónde escala esa recursión sin que el coste y la complejidad se te vayan de las manos?

Esto importa porque el harness (el andamiaje alrededor del modelo) decide el resultado tanto o más que el modelo elegido. Si te interesa el porqué de fondo, ya escribí sobre por qué tu Claude Code necesita un agent harness. Aquí vamos un nivel más arriba: la recursión.

¿Qué es un harness recursivo?

Un harness recursivo (Recursive Agent Harness, RAH) convierte el agente entero en la unidad que se repite, no la llamada al modelo. En lugar de que un LLM se invoque a sí mismo sin herramientas, lo que se invoca de forma recursiva es un agente con acceso a ficheros, ejecución de código y planificación propia.

La diferencia con un agente normal es sutil pero cambia todo. Un agente clásico llama a herramientas predefinidas, una por turno. Un harness recursivo trata el código como acción: el agente padre lee la tarea, calcula cuánto trabajo hay y escribe un programa que lanza N subagentes, parametrizando concurrencia, rutas de salida e instrucciones en el mismo lenguaje con el que razona.

El paper RAH (arXiv 2606.13643) lo formaliza con un dato concreto: en el benchmark Oolong-Synthetic, el enfoque alcanza un 89,77% con Claude Sonnet 4.5, y la recursión del harness compone con la calidad del modelo en vez de sustituirla. Mejor modelo + recursión = mejor resultado, no uno u otro.

Las dos vías de spawn: por qué el código gana

El harness expone una sola primitiva (lanzar un subagente) de dos maneras. Aquí está el matiz que diferencia a RAH de la orquestación de toda la vida:

Vía	Cómo lanza subagentes	Límite	Cuándo gana
JSON tool calling	El agente emite una llamada estructurada y el harness ejecuta el subagente	Topado por el presupuesto de llamadas paralelas por turno	Pocas tareas (umbral de ~5 entradas)
Code-execution	El agente escribe un script (un `Task()`) que orquesta el spawn	Limitado por el coste y la profundidad que tú permitas	Cargas grandes: puede lanzar miles de subagentes

La clave: el tool calling clásico tiene un techo de paralelismo por turno. Si tienes que lanzar 200 subagentes, no caben. El camino de código no tiene ese techo porque el agente escribe un bucle. Esa es la razón por la que, en cargas grandes, RAH siempre acaba generando un script en vez de emitir llamadas sueltas.

En pseudocódigo, la idea del agente padre se parece a esto:

# El agente padre NO llama a una tool por trozo: escribe un programa que los lanza en lote
chunks = split_document(doc, by="section")   # divide el trabajo segun su tamano real
results = parallel_map(                        # spawn concurrente, sin tope de turno
    lambda c: Task(agent="summarizer", input=c, out=f"/tmp/{c.id}.md"),
    chunks,
    concurrency=8,                             # tu decides cuanto paralelismo aguanta tu presupuesto
)
final = Task(agent="reducer", input=results)   # un ultimo agente fusiona los parciales

La realidad en Claude Code: la recursión se queda en un nivel

Aquí viene el aviso honesto: en Claude Code, un subagente no puede crear sub-subagentes. Está reportado (issue #19077 del repo de Claude Code): aunque le des acceso a la herramienta Task, el subagente hijo no consigue lanzar nietos. La delegación se queda en un nivel de profundidad.

Esto no es un fallo cosmético, es una decisión de diseño razonable: la recursión sin frenos es la forma más fácil de quemar tu presupuesto de tokens y de perder el control de qué está pasando. Si quieres entender lo rápido que se dispara la factura cuando el contexto crece sin control, ya conté cómo cruzar los 200k tokens vacía tu presupuesto.

La consecuencia práctica: no montes árboles profundos esperando que cada hoja delegue. En su lugar, deja que el agente principal sea el único orquestador y haga el fan-out en rondas. Pierdes elegancia teórica, ganas previsibilidad de costes.

Cómo aplicar el patrón hoy, sin anidar

El objetivo es conseguir los beneficios de RAH (contexto aislado, paralelismo, especialización) con la restricción de un solo nivel. Tres piezas:

Subagentes especialistas definidos en .claude/agents/, cada uno con su contexto limpio y sus herramientas. Devuelven un resultado al principal y desaparecen.
Skills para el conocimiento que se repite, de modo que no tengas que reinyectar las mismas instrucciones en cada subagente. La skill se carga solo cuando la tarea encaja (progressive disclosure).
Fan-out explícito desde el principal: pide N tareas en paralelo, una por unidad de trabajo.

Un subagente especialista se define con muy poco:

---
name: section-summarizer
description: Resume una seccion de documento de forma aislada. Uno por seccion.
tools: Read, Write
model: claude-haiku-4-5-20251001   # modelo barato para trabajo repetitivo y acotado
---
Resume la seccion que recibes en 5 bullets. Devuelve solo el resumen, sin preambulo.

Y la orquestación es tan simple como ser explícito con el número. Claude Code usa subagentes de forma conservadora por defecto, así que el "cuántos" importa:

# Prompt al agente principal (el unico que orquesta)
Divide el informe en sus 8 secciones. Lanza 8 subagentes `section-summarizer`
en paralelo, uno por seccion. Cuando todos terminen, fusiona los 8 resumenes
en un resumen ejecutivo unico. No edites el informe original.

Si quieres ver cómo encaja todo esto con el ecosistema (subagents + skills frente a otros entornos), comparé el enfoque en Cursor vs Claude Code en 2026.

Harnesses empaquetados: la idea de omo

No tienes que inventar la orquestación desde cero. Proyectos como oh-my-openagent (omo) empaquetan un harness multi-agente: un orquestador central (lo llaman Sisyphus) que delega en especialistas con roles fijos, como planificación, consulta de arquitectura, búsqueda en el código y exploración rápida.

Lo interesante para tu propio setup es el patrón de routing por categoría de tarea: las tareas simples y repetitivas van a un modelo barato (o local), y el razonamiento pesado se reserva para el modelo caro. Es la misma lógica de separación de responsabilidades que aplicamos en arquitectura de software, llevada a la asignación de modelos: cada agente hace una cosa, con el recurso justo.

En Producción

El patrón funciona, pero la diferencia entre el tutorial y producción está en el coste y el control. Cuatro frentes a vigilar:

Coste real: cada subagente es una sesión con su propio consumo de tokens. Lanzar 8 en paralelo multiplica el gasto por 8 en ese instante. Para trabajo personal, un flujo de fan-out moderado entra en el rango de 10 a 50 € al mes en API; si te descuidas con árboles grandes, se dispara rápido.
Profundidad: con el límite de un nivel en Claude Code, planifica el reparto en el agente principal. Si una pieza necesita a su vez subdividirse, devuélvela al principal para una segunda ronda en lugar de buscar la anidación.
Routing de modelos: no uses Opus para resumir secciones triviales. Asigna modelos baratos (Haiku) al trabajo acotado y reserva los caros para planificación y fusión. Ahí está el ahorro de verdad.
Manejo de errores: un subagente puede fallar o devolver basura. El orquestador debe tratar cada resultado como potencialmente nulo y reintentar o descartar, no asumir que los 8 vuelven perfectos.

Una nota de honestidad: no he probado este patrón con repartos de más de unas pocas decenas de subagentes en un flujo propio. Los miles de subagentes del paper RAH son un entorno de benchmark, no tu día a día con una suscripción normal.

Errores comunes y depuración

Error: el subagente intenta lanzar otro subagente y no pasa nada. Causa: Claude Code no permite sub-subagentes (issue #19077), aunque le des la tool Task. Solución: mueve toda la orquestación al agente principal.
Error: pides "paraleliza esto" y Claude lo hace en serie. Causa: el agente es conservador con el paralelismo si no le das un número. Solución: sé explícito: "lanza 8 tareas en paralelo, una por fichero".
Error: la factura se dispara sin razón aparente. Causa: usas un modelo caro en subagentes que hacen trabajo trivial repetido. Solución: fija un modelo barato en el frontmatter del subagente.

Preguntas frecuentes

¿Un harness recursivo es lo mismo que un sistema multi-agente?

No exactamente. Un sistema multi-agente coordina agentes distintos; un harness recursivo hace que el mismo agente, con todas sus herramientas, sea la unidad que se repite. La diferencia es que el padre escribe el código que lanza a los hijos en lugar de seguir un esquema fijo de orquestación.

¿Puedo conseguir recursión real de varios niveles en Claude Code?

Hoy no de forma nativa: la delegación se limita a un nivel y los subagentes no crean sub-subagentes. El camino práctico es que el agente principal haga varias rondas de fan-out, asumiendo él el papel de orquestador en cada vuelta.

¿Cuándo merece la pena este patrón frente a un único agente?

Cuando la tarea se divide en piezas independientes y grandes: procesar muchos ficheros, resumir documentos largos, auditar módulos. Si la tarea es pequeña o las piezas dependen unas de otras, un solo agente con buen contexto suele ser más barato y más simple.

Cierre

Hemos visto que el harness recursivo lleva la delegación a su extremo lógico: agentes completos que lanzan agentes completos, escribiendo el código de orquestación en vez de seguir un guion fijo. El paper RAH demuestra que esa vía de código escala donde el tool calling clásico se topa, y que compone con la calidad del modelo. La lección transferible a tu trabajo diario es más humilde: en Claude Code, deja que el agente principal orqueste, reparte en paralelo con subagentes especialistas, apoya el conocimiento repetido en skills y vigila el coste con un routing de modelos sensato. La recursión bonita del paper se traduce, en producción, en disciplina de presupuesto.

¿Has montado un flujo de subagentes en paralelo en Claude Code? ¿Cuántos lanzas a la vez antes de que el coste te frene? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo quiero entrar en el routing de modelos por tarea: cuándo Haiku, cuándo Sonnet y cuándo de verdad necesitas Opus.