Aprende a delegar tareas complejas a instancias paralelas de Claude Code y multiplica tu capacidad sin aumentar el tiempo de espera.
Uno subagent es una instancia independiente de Claude Code que el agente principal (orquestador) inicia para ejecutar una tarea específica. Recibe un prompt bien delimitado, trabaja con sus propias herramientas y devuelve un resultado resumido.
El orquestador usa la herramienta interna Task para crear subagents. Cada Task está aislada: tiene su propio historial de conversación, contexto de archivos y permisos configurados.
El subagente no comparte memoria con el orquestador. Solo sabe lo que está en el prompt que recibió. Esto es una feature: el aislamiento garantiza que un subagent no contamine el contexto de otro.
Define el prompt con un alcance claro, el formato de salida esperado y los permisos necesarios
Se crea una nueva sesión aislada con el prompt como contexto inicial
Usa Bash, Read, WebSearch y otras herramientas según sea necesario
Texto comprimido con el resultado: no el registro completo, solo la respuesta
El criterio más rápido: ¿puedes describir la tarea en 1-2 frases con entradas y salidas claras? Si es así, es candidato a subagent. Si necesita párrafos de contexto, ejecútalo directamente en el orquestador.
Fan-out ocurre cuando un orquestador activa N subagentes simultáneamente, cada uno resuelve una parte del problema. El orquestador queda bloqueado esperando a que todos terminen y luego agrega los resultados.
Una investigación que visitaría 8 fuentes en serie (8 × 30s = 4 minutos) se convierte en 8 subagents en paralelo (~30 segundos). Velocidad 8× con el mismo costo total.
Tú eres quien coordina. Usa la herramienta Task para crear 4 subagents en PARALELO: Task 1: Busca la documentación oficial de Claude Code sobre hooks. Devuelve: lista de eventos disponibles con una descripción. Task 2: Lee los archivos .claude/settings.json del proyecto. Devuelve: estructura actual de la configuración. Task 3: Busca ejemplos de hooks en repositorios públicos. Devuelve: 3 ejemplos prácticos con código. Task 4: Analiza el código en src/ para identificar oportunidades de automatización con hooks. Devuelve: lista priorizada de mejoras. // Espera a que TODOS terminen y después integra los resultados.
La velocidad aumenta con N subagents, pero el costo también. Para tareas de 1-2 minutos, el fan-out con 4-8 agentes es el punto óptimo. Con más de 10 agentes, el costo de coordinación reduce el rendimiento.
Modo de lectura — acceso solo a herramientas de observación (Read, Bash de solo lectura, WebSearch). No puede crear ni modificar archivos.
Acceso completo a las herramientas — puede leer, escribir, ejecutar comandos e interactuar con API externas.
Usa siempre el tipo más restrictivo que permita la tarea. Un subagent de investigación con permiso de escritura es un riesgo innecesario: si el modelo «alucina» una instrucción, podría modificar archivos por error.
El resultado de un subagent llega al orquestador como texto puro — un resumen consolidado de lo que se encontró/hizo. El orquestador no recibe el registro de herramientas, solo la respuesta final.
Para garantizar que el resultado se pueda consumir, especifica el formato de salida en el prompt: Retorne: lista de bullets, Retorne: JSON com campos X e Y, etc.
Prompt do orquestrador: ~500 tokens ($0.003) Execução do subagent: ~2000 tokens ($0.012) Output para orquestrador: ~300 tokens ($0.002) ────────────────────── Total por subagent: ~$0.017 // Com prompt caching (se CLAUDE.md ou contexto fixo): Custo cache hit: ~$0.002 (10× mais barato) // ROI: 1h de trabalho humano = $50-100 // 100 subagents = $1.70 → 30× mais barato que humano
Compara: tiempo ahorrado × valor de tu tiempo vs costo de la API. Si ahorras 1h ($50) y la automatización cuesta $0.50, el ROI es de 100×. Esto aplica a cualquier tarea que haces más de una vez por semana.
4.2 — 🪝 Hooks: automatizar el harness con PreToolUse, PostToolUse, SessionStart y Stop