Fan out de subagentes en Claude Code, y después comprobar lo que vuelve

La gente escribe «claude fan out subagents» en Google, y bastantes añaden «command» al final, como si hubiera un interruptor que activar. Hay un patrón, y también hay un comando. Comprobamos los dos en Claude Code 2.1.301 y en la documentación de Anthropic el 16 de octubre de 2026.

Luego está la parte de la que la documentación dice poco, y la razón por la que escribimos esto: qué hacer con los resultados. Hacemos un fan out cada noche. Seis subagentes traducen cada nuevo artículo de este blog a diecisiete idiomas, y la sesión principal fusiona su trabajo. Todos ellos informan de que han seguido las reglas. La comprobación que escribimos antes de lanzarlos sigue encontrando cosas.

La respuesta corta

Hacer un fan out significa que una sesión divide un trabajo en porciones que no dependen unas de otras, entrega cada porción a un subagente, los deja ejecutarse al mismo tiempo y fusiona lo que vuelve. En Claude Code puedes hacerlo de tres maneras.

El resto de esta página repasa cada una, y después las comprobaciones que hacemos en nuestro propio fan out.

Lo que un subagente ve y lo que no ve

Tres hechos de la documentación deciden cómo divides el trabajo.

Cada subagente empieza de cero. Se ejecuta en su propia ventana de contexto, con su propio system prompt, sus herramientas y sus permisos. No ve tu conversación, ni los skills que ya usaste, ni los archivos que Claude ya leyó. Todo lo que necesite saber tiene que estar en su brief.

Los resultados vuelven a la conversación principal. La parte detallada del trabajo de un subagente se queda en su propio contexto y solo vuelve su resultado. Pero muchos subagentes que devuelven informes largos pueden llenar igualmente tu contexto principal, y cada uno gasta sus propios tokens mientras se ejecuta.

Hay límites. Por defecto, 20 subagentes pueden ejecutarse al mismo tiempo en una sesión. El número 21 falla con Concurrent subagent limit reached, y el error le dice a Claude que no lo reintente. Puedes subirlo o bajarlo con CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Un subagente puede lanzar sus propios subagentes, hasta tres niveles por debajo de la conversación principal, y no hay límite para el total en una sesión.

Manera 1: pedirlo con palabras normales

El fan out más simple es una frase. El ejemplo de la documentación de Anthropic:

Research the authentication, database, and API modules in parallel using separate subagents

Cada subagente explora su zona y después Claude escribe una síntesis. La documentación añade la condición que importa: funciona mejor cuando las líneas de investigación no dependen unas de otras. Si la pregunta sobre la base de datos necesita la respuesta sobre auth, no tienes tres porciones, tienes una secuencia.

Con palabras normales, la decisión queda en manos de Claude. Si has definido un subagente personalizado en .claude/agents/, mencionarlo con @ garantiza que se ejecute para esa tarea. Nuestra página sobre los subagentes de Claude Code explica cómo funcionan esos archivos.

Manera 2: /batch, lo más parecido a un comando de fan out

/batch es un skill incluido en Claude Code. Le das una instrucción:

/batch migrate src/ from JavaScript to TypeScript

Investiga el código, divide el trabajo en 5 a 30 unidades independientes y te muestra un plan. Una vez que lo apruebas, lanza un subagente en segundo plano por unidad, cada uno en un worktree de git aislado. Cada subagente implementa su unidad, ejecuta los tests y publica su cambio. Necesita un repositorio git, o un hook WorktreeCreate que cree los worktrees para otro sistema de control de versiones.

El plan es el momento de ir despacio. Ahí se decide la división, y la división lo es todo: dos unidades que tocan el mismo archivo, o una unidad que necesita la salida de otra, no se fusionarán bien por muy bueno que sea cada subagente. Lee la lista de unidades como leerías un plan de migración de un compañero.

Manera 3: un bucle sobre claude -p

Cuando el trabajo es una lista de archivos y quieres control sobre cada llamada, las buenas prácticas de Anthropic describen un bucle. Primero, haz que Claude escriba la lista (list all 2,000 Python files that need migrating and save the list to files.txt). Después:

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --permission-mode dontAsk
done

Hay tres detalles de ese ejemplo que vale la pena copiar.

• La respuesta la puede leer una máquina. «Return OK or FAIL» significa que tu script puede contar los fallos sin leer prosa.
• Los permisos se deciden de antemano. --allowedTools aprueba exactamente lo que necesita la migración, y --permission-mode dontAsk deniega todo lo demás en lugar de esperar a alguien que no está.
• Empiezas con dos o tres archivos. La documentación lo dice claramente: ajusta el prompt según lo que falle con los primeros archivos y después ejecuta la lista completa.

Tal como está escrito, el bucle procesa un archivo tras otro. Lanzar varias llamadas al mismo tiempo es trabajo normal de shell, pero cada llamada es una sesión completa en tu máquina y en tu cuota. Medimos qué pasa cuando varios agentes lanzan el mismo comando pesado en el mismo minuto en este artículo, y aquí la historia es la misma: empieza con pocas llamadas en paralelo.

Para la CI, la documentación recomienda añadir --bare, que omite los hooks, los skills, los servidores MCP y CLAUDE.md para que cada máquina haga el mismo run. El modo bare no usa el inicio de sesión de tu suscripción: necesita ANTHROPIC_API_KEY.

Cómo hacemos un fan out cada noche

Este es el fan out que ejecutamos de verdad. Nuestro equipo SEO nocturno escribe a mano cada nuevo artículo en inglés y en francés. Después, un segundo agente lo traduce a otros diecisiete idiomas con subagentes de Claude Code, y genera el chino tradicional a partir del chino simplificado con un script en lugar de traducirlo. Once artículos han pasado por aquí desde el 13 de septiembre de 2026, y cada uno llega como veinte archivos.

Las porciones

Seis subagentes, tres idiomas cada uno (dos para el último): español, portugués e italiano; alemán, neerlandés y polaco; ruso, ucraniano y turco; japonés, coreano y chino; tailandés, vietnamita e indonesio; árabe e hindi. Ningún idioma depende de otro, y eso es lo que lo convierte en un fan out limpio.

Cada brief lleva las mismas cinco cosas, porque el subagente no ve nada más:

• la fuente en inglés, y la versión francesa como referencia de tono y de términos del producto;
• para cada idioma, frases ya publicadas en el sitio en ese idioma, para que el subagente reutilice las palabras que el sitio ya usa en lugar de inventar otras;
• las reglas estrictas: los nombres de marcas y productos se quedan como están, el código se queda idéntico byte a byte, sin raya;
• el script de comprobación, con la instrucción de ejecutarlo hasta que diga OK;
• la petición de informar de todo lo dudoso que haya visto, dentro o fuera de su porción.

La comprobación se escribe antes del lanzamiento

La comprobación es un script, no la opinión de un subagente. Para cada idioma compara el archivo con la fuente en inglés:

• mismo slug y misma fecha, título igual al H1;
• mismo número de secciones, subsecciones, imágenes, enlaces y filas de tabla, y tantas respuestas de FAQ en el cuerpo como preguntas en los metadatos;
• enlaces idénticos byte a byte, segmentos de código idénticos byte a byte;
• nombres de marca contados, nunca menos que en inglés;
• una longitud dentro de unos límites calibrados para cada idioma, porque el chino dice lo mismo en un 36 % de los caracteres que necesita el inglés, y el japonés en más o menos la mitad;
• acentos presentes donde el idioma los tiene (polaco, turco, vietnamita).

Todos los subagentes terminan con alguna versión de «hecho, todas las comprobaciones pasan». El único veredicto según el que actuamos es el mismo script, ejecutado de nuevo por la sesión principal, sobre todos los archivos a la vez.

Lo que la comprobación central encontró y los propios informes no

Código traducido dentro de una tabla. El 13 de septiembre, cerca de la mitad de los subagentes tradujeron las palabras que seguían a un comando dentro de los mismos backticks de una tabla. Cada uno había seguido su brief tal como lo entendió. La corrección fue al brief, no a los subagentes: un segmento de código contiene solo el comando, y las palabras que lo siguen van fuera de los backticks.

Nuestra propia comprobación estaba mal. El 6 de septiembre, una comprobación de longitud calibrada sobre la frase antigua que estábamos sustituyendo señaló a 11 subagentes de 17. Los 11 tenían razón: el texto nuevo tenía que ser más largo. Calibrada sobre el francés corregido, no señaló a ninguno. Una comprobación central también puede fallar, y la forma de verlo es ejecutarla primero sobre una entrega que ya sabes que está bien.

La coherencia entre porciones. El 15 de octubre, en una nueva página de funcionalidad traducida de la misma manera, la comprobación de fusión confirmó que solo habían cambiado las frases esperadas en 90 archivos. Pero los subagentes de japonés, coreano y chino habían elegido cada uno para «You may also like» un título distinto del que su idioma ya usaba en una página vecina. Cada elección era una traducción correcta. Ninguna era coherente con el sitio. Ningún subagente podía verlo desde dentro de su porción: solo lo ve una pasada sobre el resultado fusionado.

Una palabra equivocada pasa todas las comprobaciones de estructura. Un idioma del sitio llamó una vez a los agentes de IA concesionarios de coches, y se quedó publicado durante meses. Misma longitud, misma puntuación, marca presente: todos los recuentos estaban en verde. Lo único que lo detecta es una lista con nombre de palabras erróneas conocidas, que bloquea cada despliegue y crece una línea cada vez que encontramos una nueva.

Los avisos fuera de la porción. El 15 de octubre, el subagente que trabajaba en el turco informó de que el sitio escribía «ajans», agencia, para «agent» en 97 frases existentes. No las tocó, porque su brief le decía que no lo hiciera. Abrimos un ticket y la corrección salió al día siguiente. Preguntar a los subagentes qué han visto, y no solo qué han hecho, cuesta poco y compensa.

La fusión se hace en un solo sitio

Los subagentes no escriben directamente en el repositorio. Cada uno devuelve sus archivos, y un script los fusiona y después compara el resultado con la versión anterior frase por frase: solo pueden haber cambiado las frases que pedimos. Después, las comprobaciones del repositorio y el build del sitio se ejecutan una sola vez, sobre el resultado fusionado. Ejecutar el build una vez por subagente sería más lento y probaría estados a medio fusionar que nunca llegarán a publicarse.

Cuándo no hacer un fan out

• Las porciones dependen unas de otras. Si la porción B necesita la salida de la porción A, ejecútalas en orden.
• El trabajo es pequeño. Cada subagente empieza de cero y vuelve a leer lo que necesita. En una tarea de diez minutos, empezar de cero cuesta más de lo que ahorra.
• No sabes escribir la comprobación. Si no hay forma de distinguir una porción buena de una mala sin leerlo todo tú mismo, es en la fusión donde vas a pasar el tiempo.
• La cuota va justa. Cada subagente gasta sus propios tokens. El fan out te hace ganar tiempo y un contexto principal limpio, no una factura más pequeña.

Dónde encaja AgentsRoom

Los subagentes viven dentro de una sola sesión de Claude Code. Ves sus resultados, no su trabajo, y no puedes reconducir a uno de ellos a mitad de camino. Cuando quieres que cada porción sea un agente que puedas seguir, responder y revisar por separado, ejecuta mejor sesiones separadas: cada ticket en su propio worktree de git, y Agent Teams cuando las porciones se pasan trabajo entre ellas. Un paso de equipo puede llevar un comando de comprobación, y es su código de salida, no lo que dice el agente, lo que decide si el run avanza. Es la misma regla que arriba, aplicada por el runner. Funciona con Claude Code, Codex y las demás CLI de agentes que AgentsRoom admite.

Si todavía dudas entre subagentes y Agent Teams, esta comparación explica para qué sirve cada uno.