Generación de subagentes paralelos para tareas de investigación aisladas
Cuando una tarea de investigación se divide claramente en partes independientes, lanzar un subagente por pieza y ejecutarlos al mismo tiempo es más rápido y limpio que investigar cada pieza una tras otra en la sesión principal.
Este es el patrón de distribución (fan-out): varios subagentes se lanzan juntos, cada uno con su propia tarea limitada, cada uno informando un resumen corto una vez que termina.
Resumen
Un solo subagente ya mantiene el trabajo exploratorio fuera del contexto de la sesión principal.
La distribución extiende eso al lanzar varios subagentes a la vez en lugar de uno a la vez, por lo que la investigación independiente ocurre de forma concurrente en lugar de secuencial.
Dado que cada subagente obtiene su propio contexto aislado, ejecutar tres o cinco de ellos en paralelo no corre el riesgo de que los hallazgos de un subagente se filtren o contaminen a los de otro.
El rol de la sesión principal cambia de realizar la investigación en sí a escribir descripciones de tareas claras e independientes y luego sintetizar los resúmenes que regresan.
Esto solo funciona bien cuando las piezas son realmente independientes; una tarea en la que el segundo subagente necesita la respuesta del primero antes de poder comenzar no es un candidato para la distribución.
Receta
Lanza tres subagentes en paralelo, uno para el código de autenticación, otro para
el código de facturación y otro para el código de notificaciones. Cada subagente
debe informar: el archivo de punto de entrada, el flujo de datos general y cualquier
patrón de manejo de errores que encuentre. Mantén cada informe por debajo de 150
palabras.Cuándo usar esto:
- Auditar un patrón (manejo de errores, registro, una convención de nomenclatura) en varios subsistemas no relacionados a la vez.
- Responder "¿cómo funciona X" para varias características independientes antes de comenzar un cambio más grande.
- Comparar cómo se resuelve el mismo problema en diferentes partes de una base de código.
- Recopilar contexto para una gran refactorización donde las áreas afectadas no dependen unas de otras.
Ejemplo de trabajo
Voy a añadir limitación de velocidad a esta API. Antes de hacerlo, lanza tres
subagentes en paralelo:
1. Investiga cómo está estructurado el middleware de autenticación existente, para
que la limitación de velocidad pueda conectarse al mismo pipeline de solicitud.
2. Investiga cómo se formatean y devuelven actualmente los errores a los clientes
de la API, para que una respuesta 429 coincida con las convenciones existentes.
3. Investiga si algún sistema de configuración existente (variables de entorno, un
archivo de configuración) debería contener los umbrales de limitación de velocidad,
en lugar de codificarlos de forma fija.
Cada subagente debe informar rutas de archivo y un resumen de dos o tres frases,
no el contenido completo del archivo. Una vez que los tres hayan terminado,
propón dónde debería residir la lógica de limitación de velocidad basándose en
lo que encontraron.Lo que esto demuestra:
- Tres preguntas de investigación genuinamente independientes, ninguna de las cuales depende de la respuesta de otra, es lo que hace que la distribución paralela sea segura aquí.
- A cada subagente se le da un entregable concreto y limitado (hallazgos específicos, no "echa un vistazo"), lo que produce un resumen utilizable en lugar de uno vago.
- La instrucción de informar "rutas de archivo y un resumen, no el contenido completo del archivo" mantiene los informes lo suficientemente cortos como para que la sesión principal pueda sintetizarlos.
- El paso final de síntesis ocurre después de que los tres subagentes informan, en la sesión principal, que es donde las piezas se combinan realmente en una decisión.
Inmersión profunda
Cómo funciona
- La sesión principal escribe una descripción de tarea por subagente, cada una limitada a una parte única e independiente de la pregunta general.
- Los subagentes se ejecutan de forma concurrente, cada uno en su propio contexto aislado, por lo que su exploración intermedia nunca aparece en la sesión principal ni en los contextos de los demás.
- Cada subagente termina e informa un resumen a la sesión principal; la sesión principal recibe N resúmenes, no la transcripción completa del trabajo de ningún subagente.
- La sesión principal luego sintetiza los resúmenes, sacando conclusiones o tomando decisiones que ningún subagente individual tenía suficiente contexto para tomar por sí solo.
Reconocer un candidato genuino para la distribución
| Señal | La distribución encaja | La distribución no encaja |
|---|---|---|
| Dependencia entre tareas | Ninguna; cada tarea puede comenzar con cero información de las otras | Una tarea necesita los hallazgos de otra antes de poder comenzar |
| Alcance de cada tarea | Limitado y específico (un subsistema, una pregunta) | Vago ("echa un vistazo a toda la base de código") |
| Lo que significa "hecho" | Un resumen corto y concreto responde a la pregunta | La respuesta solo tiene sentido entrelazada en una narrativa larga |
Escribir descripciones de tareas que se distribuyen bien
Malo: "Investiga cómo maneja la aplicación los errores."
Mejor: "Solo en el módulo de pagos, encuentra dónde se capturan y formatean los errores para el cliente. Informa la ruta del archivo y el formato utilizado, en menos de 100 palabras."- Una tarea vaga produce un resumen vago y difícil de sintetizar; una tarea específica y limitada produce uno específico y utilizable.
- Nombrar el entregable exacto ("ruta del archivo y formato utilizado") le dice al subagente en qué debe enfocar su esfuerzo de verificación, en lugar de explorar ampliamente y adivinar qué es importante.
Trampas
- Dividir una tarea que en realidad tiene dependencias - lanzar el subagente B para basarse en los hallazgos del subagente A, en paralelo, significa que B comienza sin la información que realmente necesitaba. Solución: ejecuta la investigación dependiente secuencialmente y reserva la distribución paralela para piezas genuinamente independientes.
- Descripciones de tareas vagas y superpuestas - dos subagentes con instrucciones casi idénticas ("echa un vistazo al backend" y "echa un vistazo a la API") a menudo duplican el trabajo o producen resúmenes redundantes y difíciles de comparar. Solución: limita cada subagente a una parte distinta y no superpuesta de la pregunta.
- Pedir el contenido completo de los archivos en lugar de un resumen - un subagente que devuelve archivos completos anula el propósito de la distribución, ya que el contexto de la sesión principal se llena de todos modos, solo que con retraso. Solución: solicita explícitamente a cada subagente un resumen corto y hallazgos específicos, no contenido de archivo en bruto.
- Lanzar demasiados subagentes para una tarea pequeña - distribuir cinco subagentes para responder algo que un solo subagente (o la sesión principal directamente) podría responder en un minuto agrega latencia y sobrecarga de coordinación sin ningún beneficio. Solución: reserva la distribución para tareas que realmente se dividen en varias piezas sustanciales e independientes.
- Olvidar especificar un formato de informe - sin orientación sobre la forma que debe tomar el resumen, diferentes subagentes pueden informar en formatos inconsistentes que son más difíciles de comparar y sintetizar. Solución: solicita una estructura consistente (por ejemplo, "ruta del archivo, luego un resumen de dos frases") en todos los subagentes del lote.
- No tener en cuenta el tiempo de síntesis - la sesión principal todavía tiene que leer y combinar N resúmenes después de que todos regresan, lo que requiere un esfuerzo real proporcional a cuántos subagentes se lanzaron. Solución: mantén el ancho de la distribución (el número de subagentes) igual a cuánto puede sintetizar significativamente la sesión principal después.
Alternativas
| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
| Un solo subagente | La pregunta de investigación es una tarea coherente, incluso si toca varios archivos. | La tarea se divide genuinamente en varias subpreguntas no relacionadas que diluirían el enfoque de un solo subagente. |
| Subagentes secuenciales, uno tras otro | La investigación posterior depende de lo que encontró un subagente anterior. | Las piezas son independientes y ejecutarlas una a la vez solo agregaría latencia innecesaria. |
| Investigar directamente en la sesión principal | La búsqueda es rápida y lo suficientemente pequeña como para que lanzar un subagente en absoluto cueste más de lo que ahorra. | La investigación es lo suficientemente amplia como para que sus pasos intermedios inflen significativamente el contexto de la sesión principal. |
Preguntas frecuentes
¿Cuántos subagentes se pueden lanzar razonablemente en paralelo para una distribución?
No hay un límite fijo establecido por el producto, pero en la práctica el número debe coincidir con cuántas piezas genuinamente independientes tiene la tarea, y cuánto esfuerzo de síntesis puede hacer razonablemente la sesión principal después, generalmente un puñado en lugar de docenas.
¿Los subagentes paralelos comparten algún contexto entre sí mientras se ejecutan?
No. Cada subagente obtiene su propio contexto aislado, por lo que ninguno de ellos puede ver lo que los demás están haciendo o han encontrado mientras todos aún están en progreso.
¿Qué sucede si un subagente en un lote de distribución tarda mucho más que los demás?
La sesión principal generalmente espera a que todos los subagentes lanzados completen antes de sintetizar sus informes, por lo que el subagente más lento del lote determina cuándo puede comenzar la síntesis.
¿Debo pedir a cada subagente que informe en el mismo formato?
Sí. Solicitar una estructura consistente, como una ruta de archivo seguida de un resumen corto, facilita mucho la comparación y combinación de los informes una vez que todos regresan.
¿Es el patrón de distribución adecuado para una tarea con tres pasos que dependen unos de otros?
No. La distribución es para piezas independientes que pueden comenzar sin información de las otras; una tarea secuencial dependiente debe ejecutarse como subagentes (o pasos) secuenciales en su lugar.
¿Cuál es la mayor señal de que una tarea no debería distribuirse?
Si describir la tarea para un subagente requiere naturalmente hacer referencia a "lo que encontró el subagente B", la tarea tiene una dependencia y no es un candidato genuino para la distribución.
¿La generación de subagentes en paralelo ahorra contexto en comparación con ejecutarlos uno a la vez?
El ahorro de contexto proviene del aislamiento en sí (la exploración de cada subagente nunca llega a la sesión principal), lo que se mantiene tanto si los subagentes se ejecutan en paralelo como secuencialmente; la generación paralela principalmente ahorra tiempo de reloj, no contexto adicional.
¿Quién realiza la síntesis real después de que varios subagentes informan?
La sesión principal que los lanzó. Recibe el resumen de cada subagente y es responsable de sacar conclusiones o tomar decisiones que combinen información de todos ellos.
¿Se puede activar un lote de distribución desde un comando de barra diagonal personalizado?
Sí. El cuerpo del prompt de un comando puede instruir a Claude para que genere varios subagentes en paralelo, convirtiendo una auditoría de distribución recurrente en una sola invocación de /nombre-comando repetible.
¿Cuál es un ejemplo realista de una tarea que no debería distribuirse?
Depurar una única prueba fallida específica, donde la investigación es un hilo continuo de razonamiento en lugar de varias subpreguntas independientes y paralelas.
¿Cada subagente en un lote de distribución necesita su propio ámbito de herramientas distinto?
No necesariamente; los subagentes de investigación en un lote comúnmente comparten la misma lista de herramientas limitada, a menudo de solo lectura, ya que sus trabajos (leer y buscar, no editar) suelen ser similares aunque sus objetivos difieran.
Relacionado
- Conceptos básicos de comandos personalizados y subagentes - un primer ejemplo de subagente único antes de escalar a la distribución.
- Cómo los subagentes obtienen su propio contexto y herramientas - por qué ejecutar varios subagentes a la vez es seguro.
- Subagentes frente al SDK de Agent: cómo se construye Claude Code - los primitivos subyacentes que hacen posible el aislamiento y la distribución.
- Mejores prácticas para comandos personalizados, hooks y subagentes - convenciones para delegar el trabajo a los subagentes de manera efectiva.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifique las especificaciones actuales en platform.claude.com/docs antes de confiar en ellas.