Una nota de campo sobre usar los subagentes de Claude Code como obreros y dejar el hilo principal como director: cuándo abrir en abanico, cuándo encadenar, cómo las salidas estructuradas frenan la deriva y los modos de falla de los que nadie te avisa.
En resumen
- El hilo principal es un director, no un sexto obrero: reparte el trabajo, escribe los briefs, une resultados y no mete mano en los archivos.
- Abre en abanico el trabajo independiente; encadena cuando el paso N necesita el paso N-1. La prueba es la dependencia, no el tamaño.
- Obliga a cada subagente a devolver un esquema, no prosa. El merge debe ser código, no intuición.
- Siempre agrega un rol verificador aparte. Un agente calificándose a sí mismo es puro teatro.
- Los subagentes hacen a Claude Code ordenado, no más inteligente. Si no puedes definir 'listo' como una forma, no estás listo para delegar.
Casi todo el mundo descubre los subagentes de Claude Code y enseguida comete el mismo error: lanza cinco, le da a cada uno un párrafo vago y reza para que el hilo principal pegue los resultados. Vuelven inconsistentes, la ventana de contexto se llena de ruido y la sesión termina más lenta que si un solo agente hubiera hecho todo en orden. Este texto es el manual que me habría gustado tener: cuándo delegar, cómo repartir, qué contrato exigir y los puntos exactos donde la cosa se tuerce. Al final vas a tener un modelo mental que convierte una corrida frenética de cinco agentes en una bien pensada.
El arreglo es una metáfora vieja y aburrida: el hilo principal es el director y los subagentes son los músicos. Un director no toca el violín. Decide quién toca y cuándo, y lee la partitura para que las partes encajen. Si mantienes esa frontera limpia, los subagentes se vuelven útiles de verdad. Si la difuminas, terminas con un solo agente, peor que antes, usando cinco sombreros a la vez.
01 · Qué es realmente un subagente
Un subagente es una ventana de contexto nueva, con sus propias instrucciones, su propio presupuesto de tokens y cero memoria de tu conversación principal salvo lo que tú le pases explícitamente. En esa última parte está todo el truco. El subagente no ve tu historial. Ve el prompt que le diste y los archivos que lee. Así que un prompt vago da un resultado vago, siempre.
Ese aislamiento es una ventaja, no una limitación. Un subagente puede tragarse una tarea ruidosa (leer cuarenta archivos, correr una suite de tests inestable, escanear un árbol de dependencias) y devolverte solo la conclusión. La basura se queda en su ventana y muere ahí. Tu hilo principal sigue limpio y con espacio para las decisiones que importan.
Pero el costo es real. Levantar un subagente implica releer contexto, no puede hacerte una pregunta a mitad de la tarea y, si lanzas varios, pagas por cada uno. Así que la pregunta nunca es "¿puedo delegar esto?". Es "¿la limpieza vale lo que cuesta arrancarlo?".
Nota
Que el subagente sea ciego a tu historial es a la vez su mayor fortaleza y su mayor dolor de cabeza. No lo contamina tu enredo previo, pero tampoco adivina lo obvio que se te olvidó decirle. Escribe el brief como si estuvieras poniendo al día a un contratista capaz en su primer día.
02 · Abre en abanico y después verifica
El patrón al que más recurro es abanico / verificación. Reparte el trabajo independiente entre subagentes en paralelo y después corre un agente más cuyo único trabajo es cotejar esas salidas con un estándar común.
Concretamente, en el código de Agent Orchestra lo hice para una auditoría de dependencias. El trabajo era paralelo por naturaleza, porque cada directorio de paquete es independiente, así que el hilo principal abrió en abanico:
// Pseudocódigo del director: una Task por unidad de trabajo independiente
const targets = ["packages/core", "packages/ui", "packages/adapters"]
const reports = await Promise.all(
targets.map((dir) =>
runSubagent({
role: "dependency-auditor",
brief: "Audita " + dir + " buscando deps sin uso, peers faltantes y CVEs. " +
"Devuelve SOLO la forma JSON de abajo. Sin prosa.",
schema: AuditReport,
})
)
)
// Después un verificador aparte: ojos frescos, no el mismo agente calificándose
const verdict = await runSubagent({
role: "audit-verifier",
brief: "Con estos tres AuditReport, encuentra desacuerdos, duplicados " +
"y cualquier cosa que un auditor marcó y otro pasó por alto.",
input: reports,
schema: VerifierVerdict,
})
Dos cosas hacen que funcione. Primero, los auditores nunca se hablan entre sí, así que no pueden contaminarse el razonamiento. Segundo, el verificador es un rol distinto, no el mismo prompt corrido de nuevo.
Por qué el verificador no puede ser el mismo agente
Un agente calificando su propia tarea es puro teatro. Va a justificar lo que ya produjo porque esa salida ya es su punto de partida. Un agente fresco, con el mandato acotado de "encuentra los desacuerdos", sí pesca cosas: un peer marcado en un paquete y olvidado en otro, un CVE contado dos veces, una dependencia que en un reporte aparece "sin uso" y en el siguiente sostiene medio módulo. La verificación es donde casi todos recortan, y es justo el paso que te devuelve la inversión del paralelismo. Saltarlo significa que gastaste tokens en tres opiniones y les creíste a ciegas.
03 · Paralelizar o encadenar
La decisión real no es "¿uso subagentes?", sino "¿en paralelo o en secuencia?". La prueba es la dependencia, no el tamaño.
Paraleliza cuando las unidades de trabajo no necesitan la salida de las demás. Auditar tres paquetes. Redactar la versión EN y la ES de un documento. Buscar el mismo bug en tres partes distintas del código. Cada subagente arranca con todo lo que necesita; nadie espera a nadie.
Encadena cuando el paso N necesita la salida del paso N-1. Investigar, planear, implementar, revisar. No puedes implementar sin un plan, ni revisar lo que todavía no existe. Forzar eso a correr en paralelo solo logra que los agentes de más abajo se inventen la salida de los de más arriba, y eso es peor que esperar.
La concesión que nadie menciona
Las cadenas están limitadas por la latencia; los abanicos están limitados por el merge. Una cadena larga se siente lenta porque ves terminar cada etapa antes de que arranque la siguiente; el tiempo real es la suma de las etapas. Un abanico ancho se siente rápido justo hasta que el hilo principal tiene que reconciliar cinco resultados con formas distintas, y reconciliar es trabajo real. Si no restringiste las salidas desde el principio, esa reconciliación es el trabajo que te come la noche. Así que no es velocidad gratis: estás cambiando un cuello de botella por otro, y el esquema es lo que mantiene barato el caso limitado por el merge.
Hay un híbrido que vale la pena nombrar: abrir en abanico dentro de una etapa de la cadena. La investigación puede ser tres búsquedas en paralelo que convergen en un solo brief; ese brief alimenta luego una única etapa de planeación. No tienes que elegir una sola forma para todo el trabajo: elige la forma correcta para cada etapa.
Consejo
Ante la duda, dibuja el grafo de dependencias en papel antes de escribir un solo brief. Los nodos sin aristas de entrada pueden correr en paralelo. Todo lo que va después espera. El grafo te dice la forma; no tienes que adivinarla.
04 · Las salidas estructuradas son el contrato
Esta es la parte que la gente se salta y luego se pregunta por qué la orquestación se siente caótica. Si un subagente devuelve prosa, el hilo principal tiene que parsear prosa, y parsear prosa es donde vive la deriva.
Dale un esquema a cada subagente. Dile que devuelva eso y nada más. Cuando tres agentes devuelven la misma forma, el director los une con código, no con intuición:
type AuditReport = {
scope: string
unusedDeps: string[]
missingPeers: string[]
cves: { pkg: string; id: string; severity: "low" | "med" | "high" }[]
}
Ahora el merge es un reduce, no una reinterpretación. El director nunca tiene que "entender" cada reporte en lenguaje natural; filtra, deduplica y ordena. Es la misma disciplina en la que me apoyo en ThinkTank AI, donde varios agentes deliberan y un coordinador combina sus posiciones. Si cada posición vuelve como texto libre, el coordinador se vuelve cuello de botella y fuente de errores. Restringe la forma y el coordinador se vuelve un join.
Una regla de escalado sin rodeos
Mientras más agentes corras, más estricto debe ser el esquema. Con un solo subagente te las arreglas con prosa. Cinco devolviéndola son un proyecto de parsing al que nunca te apuntaste. Y sé específico en el esquema: "severity: string" invita a tres vocabularios distintos; "severity: low | med | high" obliga a alinear desde el origen para que nunca tengas que normalizar después.
Atención
No dejes que "devuelve JSON" sea toda la instrucción. A los modelos les encanta envolver el JSON en un bloque de código, agregar un preámbulo amable o inventar llaves de más. Detalla la forma exacta, di "nada de prosa, nada de markdown, sin llaves extra" y valida el resultado antes de confiar en él. El lugar más barato para atrapar una respuesta mal formada es el instante en que llega, no tres merges después.
05 · Mantén al director delgado
El modo de falla que más veo es que el hilo principal se convierte sin avisar en un sexto obrero. Empieza delegando, luego "rápido" edita un archivo él mismo, después lee diez más, y ya su contexto está tan contaminado como el de los agentes que debía coordinar. El aislamiento que pagaste se esfumó.
No cedas. El trabajo del director es exactamente seis cosas:
- Decidir el reparto: qué es independiente y qué es dependiente.
- Escribir los briefs: claros, autocontenidos, con la forma de salida.
- Abrir en abanico o encadenar, según el grafo de dependencias.
- Recoger resultados estructurados, y validarlos al llegar.
- Reconciliar: unir, deduplicar, resolver desacuerdos con el verificador.
- Reportar a ti, en el hilo principal, en una sola pasada limpia.
En el momento en que empieza a hacer el trabajo, perdiste el aislamiento que hacía que delegar valiera la pena. Si una tarea es tan pequeña que delegarla se siente ridículo, hazla ahí mismo y no pretendas que es orquestación. No hay nada de malo en una sesión de un solo agente; lo malo es llamarla algo que no es.
06 · Cuándo no molestarse
Los subagentes no son gratis, así que sáltalos cuando:
- La tarea es pequeña y lineal. Un agente, en secuencia, en tu ventana actual. Levantar obreros para renombrar una función es pura sobrecarga.
- Los pasos están muy acoplados y son habladores. Si cada paso necesita preguntarle algo al anterior, el aislamiento juega en tu contra. Déjalo en un solo hilo donde el ida y vuelta es barato.
- No puedes definir la forma de la salida. Si no sabes describir qué significa "listo" como esquema, no estás listo para delegarlo. Define el contrato primero y después decide si abres en abanico.
- El trabajo es de verdad exploratorio. Si todavía no conoces las preguntas, un abanico rígido te dará respuestas seguras a las preguntas equivocadas. Explora en un solo hilo y orquesta una vez que la forma esté clara.
Los subagentes no hacen a Claude Code más inteligente: lo hacen ordenado. Abre en abanico el trabajo independiente, encadena el dependiente, obliga a cada obrero a devolver una forma conocida y mantén el hilo principal delgado para que de verdad pueda dirigir. Haz eso y una corrida de cinco agentes se siente deliberada en vez de frenética. Sáltatelo y solo habrás construido una versión más ruidosa del agente con el que empezaste.
Puntos clave
- Trata al hilo principal como director: reparte, da briefs, une y reporta, y mantenlo fuera de los archivos.
- Ajusta la forma al grafo de dependencias: paralelo para trabajo independiente, cadena para el dependiente, abanico dentro de una etapa cuando ayude.
- Haz que la salida estructurada sea el contrato; un esquema estricto vuelve el merge un reduce y mata la deriva en el origen.
- Verifica siempre con un rol aparte: calificarse a sí mismo es teatro, y el paso de verificación es lo que te devuelve el paralelismo.
- Los subagentes ordenan, no vuelven más listo a nadie. Si no puedes definir 'listo' como una forma, quédate en un solo hilo hasta que puedas.
Preguntas frecuentes
¿Cuántos subagentes son demasiados?
No hay un número mágico, pero el límite es la reconciliación, no el costo de arrancar. Cada resultado paralelo que el director tiene que unir suma trabajo. Si pasas de tres o cuatro y las salidas no tienen una forma estricta de esquema, convertiste el merge en un proyecto de parsing. Aprieta el esquema antes de ampliar el abanico.
¿No puede el mismo agente verificar su propia salida para ahorrarse un arranque?
No, y ese es el atajo que te sale caro. Un agente trata su salida previa como algo que defender, así que justifica en vez de auditar. Un agente fresco con un brief acotado de 'encuentra los desacuerdos' no tiene nada que defender en el resultado y sí pesca los duplicados, las marcas olvidadas y las contradicciones. El arranque es el precio de una segunda opinión honesta.
¿Cuándo conviene quedarse en un solo hilo?
Cuando la tarea es pequeña y lineal, cuando los pasos son habladores y muy acoplados, o cuando todavía no puedes definir 'listo' como un esquema. El trabajo exploratorio, sobre todo, va en un solo hilo: un abanico rígido da respuestas seguras a las preguntas equivocadas. Orquesta cuando la forma esté clara, no antes.
¿Por qué mi orquestación se siente caótica aun cuando el trabajo es paralelizable?
Casi siempre porque las salidas no están restringidas. Si los subagentes devuelven prosa, el director tiene que interpretar prosa, y la interpretación es donde se cuela la deriva. Dale a cada obrero un esquema explícito, di 'nada de prosa, nada de markdown, sin llaves extra' y valida al llegar. El merge se vuelve un reduce en vez de una reinterpretación.
¿Una cadena siempre es más lenta que un abanico?
En tiempo total el costo de una cadena es la suma de sus etapas, así que sí, se siente más lenta. Pero esa es la comparación equivocada: solo encadenas cuando los pasos dependen entre sí, y ahí un abanico solo lograría que los agentes de más abajo se inventen la salida de los de más arriba. Donde las etapas son independientes dentro de un flujo mayor, abre en abanico dentro de la etapa. Ajusta la forma al grafo de dependencias, no a la que se sienta más rápida.
¿Prefieres que lo hagamos por ti?
Esto mismo lo construimos para negocios como el tuyo. La primera conversación es gratis y sin compromiso.
Escríbenos por WhatsAppPrimera conversación gratis. Te responde el fundador.
Recursos relacionados
Cómo agregar un flujo con subagentes en Claude Code (paso a paso)
Una guía práctica para definir un subagente enfocado en Claude Code (su archivo, su prompt, su lista de herramientas permitidas) y conectarlo a un flujo de trabajo real para que tu hilo principal se mantenga limpio y el trabajo delegado regrese como un resumen que de verdad puedas usar.
Temporal: workflows durables que retoman justo donde se cayeron
Temporal es un motor de ejecución durable: tu código de workflow se reproduce desde un historial de eventos que queda persistido, así que un trabajo largo que se muere en el minuto 38 retoma desde el minuto 38 en vez de rehacer 38 minutos de llamadas al modelo que ya pagaste. Aquí te explico qué es, por qué el trabajo de agentes en particular lo pide a gritos, un quickstart listo para pegar, y las concesiones honestas, incluida la regla de determinismo que, si la rompes, te deja fallas raras que nadie logra reproducir.
Agentes de IA: cómo delegar trabajo sin soltar el control
Un chatbot responde una pregunta. Un agente recibe un objetivo, usa herramientas, avanza por pasos y vuelve con un resultado. Esta guía explica el salto de pedir texto a delegar trabajo útil, con un encargo simple que puedes copiar hoy.