Subagentes: Delega, no te lo eches todo a la espalda
📚 Navegación de la serie: El artículo anterior 22 MCP: Expandiendo herramientas nos enseñó a conectar a Claude con el mundo exterior para que pudiera hacer más cosas. Pero cuando puede hacer más cosas y los proyectos son más grandes, surge un nuevo problema: si le pides que lo haga todo él solo en la misma sesión, se vuelve lento, su contexto se ensucia y no puedes hablar con él mientras trabaja. Este artículo te enseña a pasar de "hacerlo tú todo" a "liderar un equipo" usando Subagentes.
Al principio de usar Claude Code, solía quedarme mirando la pantalla esperando.
Le pedía algo como "busca en todos los archivos dónde se usa esta función y arréglalo", y él empezaba a usar Grep, View, Grep, View, un montón de veces seguidas. La pantalla se llenaba de la salida de los comandos, y durante todo ese rato yo no podía hacer nada más. Si a mitad de camino me daba cuenta de que la función se llamaba distinto, no podía decírselo hasta que él terminara (o me tocaba usar Ctrl+C para abortar bruscamente y empezar de cero). Peor aún, después de leer docenas de archivos, la ventana de contexto se llenaba de basura de búsqueda, y cuando luego le pedía que escribiera el código, se notaba que había perdido agilidad mental (lo que hablamos en el artículo de la ventana de contexto).
La documentación oficial dice claramente que, ante esto, la solución es la función de Subagentes: no dejes que el "hilo principal" haga el trabajo sucio.
La idea de los subagentes es maravillosa: es literalmente "invocar a un becario clonado" para que haga el trabajo repetitivo, mientras tú y el Claude principal seguís charlando de cosas importantes.
Al terminar este artículo, sabrás:
- El concepto de "agente supervisor y subagente" en una sola frase, y por qué ahorra contexto del hilo principal.
- Las dos formas de invocar a un subagente: mediante herramientas integradas (Automático) o usando un Subagent Skill (Definido).
- Cuándo tiene sentido usar un subagente (tareas repetitivas o de exploración profunda) y cuándo es mejor no usarlos (tareas rápidas o simples).
- La forma de configurar subagentes usando Skills, los permisos heredados y las limitaciones actuales.
01 El Hilo Principal y los Subagentes: Un jefe y sus becarios
Primero, la conclusión: Los Subagentes (subagents) son instancias independientes de Claude Code que se ejecutan en segundo plano con su propia ventana de contexto, liberando al hilo principal para otras tareas.
Analogía: El arquitecto y el becario. Estás (el usuario) diseñando un edificio con el arquitecto jefe (el hilo principal de Claude). De repente necesitas saber cuántas tuberías hay en los planos antiguos. En lugar de que el arquitecto deje de hablar contigo, se ponga a buscar en cajas polvorientas (llenando su memoria de datos inútiles) y te haga esperar una hora; llama a un becario (el subagente), le dice "búscame las tuberías", y el arquitecto sigue diseñando contigo. Al rato, el becario vuelve, no te trae las cajas polvorientas, sino solo un post-it que dice "hay 45 tuberías, y aquí están los planos relevantes".
Esta analogía cubre los tres grandes beneficios oficiales:
- Ahorro brutal de contexto (Tokens): El subagente puede leer 100 archivos y gastar 50.000 tokens en su "mesa", pero al volver al hilo principal, solo entrega un resumen de 500 tokens. El contexto principal se mantiene inmaculado.
- Ejecución en segundo plano (Asíncrona): Mientras el subagente hace
Grepo compila código, tú puedes seguir hablando con el hilo principal sobre otra parte de la arquitectura. - Resistencia a fallos: Si el subagente se pierde o entra en un bucle infinito intentando resolver un error de dependencias, no contamina la sesión principal.
💡 Resumen en una frase: Un subagente es un "becario" que hace el trabajo sucio en su propia ventana de contexto en segundo plano; salva la memoria de tu hilo principal y te permite seguir trabajando en paralelo.
02 Dos formas de invocar subagentes: La automática y la definida
En Claude Code, los subagentes no son algo que tengas que encender manualmente con un flag especial al inicio. Claude los invoca cuando los necesita a través de una de sus herramientas. Hay dos vías principales:
Vía 1: Automática (Herramienta Agent)
Claude Code incluye una herramienta predeterminada llamada Agent. El modelo del hilo principal, cuando se enfrenta a una tarea que él mismo juzga como "pesada" o "distinta del hilo actual", decide por sí mismo llamar a esta herramienta para invocar un subagente.
Por ejemplo, le dices: "Tengo que refactorizar el sistema de login. Pero antes, búscame todos los sitios oscuros donde se está llamando a la vieja API de contraseñas y hazme un informe; yo iré preparando los tests."
El Claude principal pensará: "Búsqueda extensiva. Mejor lo delego". E invocará la herramienta Agent con un prompt detallado para el subagente, algo como: "Investiga el repositorio usando grep y read, busca llamadas a la API vieja y devuelve un resumen detallado de las ubicaciones."
Esta vía es totalmente automática. Tú solo le pides algo, y si él ve que es una buena oportunidad, lo hace.
Vía 2: Definida (Skills de Subagentes)
La vía automática está bien, pero a veces quieres un becario especializado. Aquí entran las Agent Skills (que veremos a fondo en capítulos posteriores). Puedes definir un subagente con un nombre, una descripción y unas herramientas específicas en un archivo YAML/JSON, y luego el hilo principal puede invocarlo por su nombre.
Es como decir: "No quiero un becario cualquiera. Quiero invocar al QA_Tester que solo tiene acceso a las herramientas de testing".
(Nota: En la versión actual de Claude Code, la vía más robusta y documentada es la automática o pedir explícitamente "usa un subagente para esto". La definición estricta de subagentes como entidades separadas a través de Skills es una característica avanzada que se integra con MCP y scripts).
💡 Resumen en una frase: Puedes dejar que Claude decida automáticamente invocar a un becario usando su herramienta integrada, o en usos avanzados, forzarlo a usar un subagente especializado. Lo normal al principio es simplemente decirle "delega esto a un subagente" en tu prompt.
03 ¿Cuándo usar subagentes (y cuándo NO)?
La tentación es decir "pues que todo lo hagan subagentes para ahorrar tokens". Error. Iniciar un subagente tiene un coste: requiere enviarle instrucciones, que entienda el proyecto desde cero, y luego recoger su respuesta.
Aquí tienes la guía definitiva de cuándo pulsar el botón de delegar:
SÍ: Casos ideales para un Subagente
- Investigación profunda (El buscador de agujas): "Revisa todos los archivos
.tsde la carpetasrc, busca funciones no utilizadas y hazme una lista." (MuchoGrepyView= mucha basura en el contexto). - Tareas repetitivas o largas (El albañil): "Migra estos 20 archivos de pruebas de Jest a Vitest, uno por uno."
- Depuración de errores en bucle (El sufridor): "Ejecuta
npm run build, y si da errores de TypeScript, intenta arreglarlos y vuelve a compilar hasta que pase." (Los errores de compilación largos destrozan el contexto principal). - Tareas totalmente desconectadas (El paralelo): "Mientras me ayudas a escribir este componente, lanza un subagente que lea la documentación de esta nueva librería y me haga un resumen."
NO: Cuándo es mejor el Hilo Principal
- Cambios de una sola línea o rápidos: "Cambia el color de este botón en
Header.tsx." (Tarda más en explicarle la tarea al subagente que en hacerlo directamente). - Decisiones de arquitectura: "¿Qué patrón de diseño deberíamos usar aquí?" (El hilo principal tiene TODO el contexto de la charla que habéis tenido hasta ahora, el subagente empieza de cero).
- Cuando la tarea depende de algo que acabas de hacer: Si acabas de escribir una función y no la has guardado, o depende íntimamente de la charla anterior, el subagente no sabrá nada a menos que el hilo principal se lo explique perfectamente.
💡 Resumen en una frase: Delega las búsquedas pesadas, las migraciones aburridas y las depuraciones largas; mantén en el hilo principal los cambios rápidos y las decisiones de diseño.
04 Permisos y detalles técnicos importantes
Si vas a empezar a enviar subagentes a trabajar, tienes que tener claro cómo manejan la seguridad y el entorno.
1. Los Subagentes heredan tus permisos: Si tu hilo principal está en modo default (te pregunta todo), el subagente también se detendrá y te preguntará antes de ejecutar un comando Bash. Si estás en modo acceptEdits, el subagente podrá editar código libremente pero preguntará para comandos peligrosos. No puedes tener un hilo principal estricto y un subagente con modo bypassPermissions. La seguridad de la sesión manda.
2. Son ciegos a tu charla previa: El subagente nace en el momento de la invocación. No sabe de qué llevas hablando con Claude la última hora. Toda la información que necesita debe dársela el hilo principal en el "prompt de delegación". Si le pides a Claude "dile a un subagente que arregle ese bug", Claude tendrá que redactar un prompt explicando de qué bug se trata, dónde está y qué se ha intentado.
3. Límite de anidamiento: Aunque teóricamente un subagente podría llamar a otro subagente (un becario llamando a otro becario), en la práctica, Claude Code limita la profundidad para evitar explosiones exponenciales de costes y bucles infinitos. Normalmente, el hilo principal invoca a un subagente de nivel 1, y este hace el trabajo. Evita pedirle que cree jerarquías complejas.
4. Aislamiento de red (Sandbox): Si el sandbox está activado, afecta a los subagentes igual que al hilo principal. Cualquier script o lectura indirecta que hagan estará contenida por el sistema operativo.
💡 Resumen en una frase: Los subagentes no son entidades mágicas independientes; tienen los mismos permisos que tu sesión principal y nacen sin memoria de la charla anterior, dependiendo totalmente de las instrucciones que se les pasen al nacer.
05 Manos a la obra: Prueba a delegar una búsqueda pesada
Vamos a forzar al hilo principal a invocar un subagente para que veas cómo se comporta la interfaz y cómo el contexto se mantiene limpio.
Paso 1: Entra en un proyecto mediano o grande (donde haya muchos archivos).
Paso 2: Pídele explícitamente que delegue una investigación
En la terminal de Claude Code, escribe:
Por favor, utiliza un subagente (herramienta Agent) para investigar en todo el proyecto cuántas veces se usa la palabra "TODO" o "FIXME" en los comentarios. Que el subagente haga la búsqueda y luego me des un resumen con los archivos que más tareas pendientes tienen.Paso 3: Observa el comportamiento
Deberías ver que Claude invoca la herramienta (algo como Agent o Delegate). Durante unos momentos, el hilo principal te avisará de que el agente secundario está trabajando. Tú podrías seguir escribiendo en el chat principal si quisieras.
Paso 4: El retorno triunfal
Cuando el subagente termina, el hilo principal recibe la respuesta y te la formatea. Si ejecutas /context, verás que el consumo de tokens no se ha disparado con miles de líneas de salidas de Grep (que es lo que habría pasado si lo hubiera hecho el hilo principal), sino solo con el pequeño resumen que devolvió el subagente.
💡 Resumen en una frase: Pide explícitamente "usa un subagente para..." en búsquedas de texto largas y comprueba con
/contextque tu sesión principal sigue fresca y limpia.
06 Resumen
Los subagentes son el paso de "asistente personal" a "equipo de desarrollo". En lugar de tener un único hilo de ejecución que se atasca, puedes paralelizar el trabajo.
| Concepto | Qué significa | Beneficio principal |
|---|---|---|
| Hilo principal | Tu conversación con Claude (el Jefe) | Mantiene el contexto limpio para decisiones |
| Subagente | Una instancia de fondo aislada (el Becario) | Hace el trabajo sucio sin ensuciarte la pantalla |
| Vía Automática | Claude decide invocarlo por sí mismo | Sin fricción, tú solo pides resultados |
| Casos Ideales | Búsquedas largas, tests en bucle, migraciones | Ahorra decenas de miles de tokens de contexto |
| Permisos | Hereda el nivel de seguridad actual | No crea agujeros de seguridad inesperados |
A partir de ahora podrás: Reconocer cuándo una tarea va a ser "un pozo de tokens" (como rastrear logs inmensos) y decirle a Claude proactivamente: "Delega esto a un subagente". Dejarás de mirar pantallas atascadas y empezarás a gestionar el trabajo de forma inteligente.
En el próximo artículo, 24 "Plugins (Complementos): Empaquetando conocimiento", veremos cómo llevar estas herramientas un paso más allá. Ya sabes de permisos, de MCP y de subagentes. Pero, ¿y si quieres compartir una "receta" perfecta que incluye configuraciones, herramientas MCP específicas y prompts de subagentes con todo tu equipo? Ahí es donde entran los Plugins, la forma de empaquetar habilidades y distribuirlas.