El pequeño ayudante

Qué es y por qué importa

Un subagente es un ayudante que Claude lanza para un trabajo concreto. Tiene un contexto propio: abre archivos, busca, lee, y al final solo te devuelve el resumen. Todo el material que ha leído para llegar ahí se queda allí y no acaba en tu conversación.

Por qué importa: la conversación principal tiene un espacio limitado. Si Claude abre cincuenta archivos para entender dónde está el login, todo ese texto ocupa el chat y al cabo de un rato a Claude le cuesta más seguir el hilo. Con un subagente la búsqueda la hace el ayudante, y a ti te llega una respuesta de pocas líneas.

«Pequeño» aquí quiere decir que hace una sola tarea, no que sea menos capaz: normalmente un subagente usa el mismo modelo que la conversación principal. En las sesiones normales suele trabajar en segundo plano, y mientras tanto tú sigues hablando con Claude.

Claude Code ya trae algunos listos. El que más uso es Explore: sirve para buscar y entender el código y es de solo lectura, es decir, no puede escribir ni modificar archivos. Luego están los que creas tú, que vemos más abajo.

1. Buscar sin llenar el chat

Es el caso más sencillo. Tengo que entender dónde está algo en el proyecto y no me interesa ver todos los archivos que Claude abre para encontrarlo.

Usa un subagente Explore para encontrar dónde se gestiona el login. Dime solo los archivos y las líneas.

La segunda frase cuenta tanto como la primera. «Dime solo los archivos y las líneas» le dice al ayudante qué tiene que traer. Si no lo dices, te vuelve un resumen largo que llena el chat igualmente.

Recuerda que Explore no ve vuestra conversación y además arranca sin el archivo CLAUDE.md del proyecto, para ser rápido. Así que pon en la frase lo que necesita: qué buscas, en qué parte de la app y qué quieres que te devuelva.

2. Tres trabajos a la vez

Cuando tengo varios trabajos que no dependen unos de otros, los lanzo en paralelo. Cada ayudante tiene su contexto y su tarea, y al final Claude junta los resultados.

Lanza tres subagentes en paralelo: uno busca dónde se gestiona el login, otro lee los logs del último error y me dice la causa, y otro escribe los tests de la página de precios. Cuando terminen, hazme un resumen de los tres.

Funciona porque los tres trabajos no se cruzan: buscar el login no hace falta para leer los logs, y ninguno de los dos toca los tests de precios. Si el segundo trabajo necesita el resultado del primero, no es un trabajo en paralelo: hazlo después.

3. Ctrl+B y /tasks

Si un trabajo está tardando y te bloquea, por ejemplo un comando que lleva minutos ejecutándose, pulsa Ctrl+B: pasa a segundo plano y tú sigues escribiendo. Ctrl+B funciona tanto con los comandos como con los ayudantes. Si usas tmux, púlsalo dos veces.

Para ver quién está trabajando, escribe:

/tasks

Te muestra el trabajo en segundo plano de la sesión: los comandos que se están ejecutando y los subagentes, también los que acaban de terminar. Desde ahí puedes abrir el trabajo de un ayudante y leer lo que ha hecho, o pararlo si ha tirado por el camino equivocado.

4. Un ayudante fijo

Si repites un trabajo a menudo, te conviene un ayudante fijo. Es un archivo en la carpeta .claude/agents del proyecto: arriba están el nombre, una descripción de cuándo usarlo y las herramientas que puede usar, y debajo las instrucciones escritas con palabras normales. No hace falta escribirlo a mano: se lo pides a Claude.

Créame un subagente en .claude/agents que revise el código sin modificar nada, y llámalo code-reviewer.

El resultado se parece a esto:

---
name: code-reviewer
description: Revisa el código y señala los problemas. No modifica ningún archivo.
tools: Read, Grep, Glob
---

Eres un revisor de código. Lee los cambios que te indico y busca bugs, casos no gestionados y partes poco claras. Para cada problema dime el archivo, la línea y cómo lo arreglarías. No modifiques nada.

La línea que importa es tools: son las herramientas que puede usar el ayudante. A un revisor le bastan las de leer y buscar, es decir, Read, Grep y Glob. No deben estar Write ni Edit, y tampoco Bash, porque desde la terminal también se pueden modificar archivos. Si no estás seguro, pregúntalo:

Abre el archivo del subagente code-reviewer y dime qué herramientas puede usar. Si hay algo que le permita modificar archivos, quítalo.

Luego lo usas así, cuando has terminado una parte del trabajo:

Haz que el subagente code-reviewer revise los últimos cambios.

En el archivo también puedes añadir una línea model para elegir el modelo: haiku para trabajos sencillos y rápidos, sonnet u opus para los más exigentes, inherit para usar el mismo que la conversación.

El archivo en .claude/agents vale para ese proyecto. Si lo pones en ~/.claude/agents, lo tienes en todos tus proyectos. También existe el comando /agents, pero lo más sencillo sigue siendo pedírselo a Claude o abrir el archivo.

5. Cuándo no los lanzo

• Trabajos pequeños: cambiar un texto, un color, una línea. Un ayudante empieza de cero y primero tiene que entender el proyecto: tarda más que hacerlo directamente.
• Trabajos que tocan los mismos archivos: dos ayudantes en el mismo archivo se pisan. Hazlos uno detrás de otro, o cada uno en su copia del proyecto, los worktrees. Para un ayudante fijo basta con añadir en su archivo la línea isolation: worktree.
• Cuando quiero seguir cada paso: el ayudante te trae el resultado al final. Si tengo que corregirlo a cada paso, me quedo en la conversación principal.
• Cuando hace falta todo lo que nos hemos dicho: un ayudante como Explore empieza con un contexto limpio y no ve nuestro chat. Hay que explicárselo desde cero, así que explícalo bien en la frase.

Una regla

Cada ayudante consume tokens propios, y cuentan para los mismos límites de uso que la conversación principal. Tres ayudantes con una tarea clara cada uno, sí. Diez lanzados «porque sí», no.

Errores comunes

• Lanzar un ayudante para un cambio de una línea: hazlo directamente, es más rápido.
• Escribir una frase vaga tipo «mira el login»: di qué buscar, dónde y qué quieres que te devuelva.
• Dar por hecho que el ayudante sabe lo que habéis hablado: no ve el chat, así que ponle el contexto en la frase.
• Poner a dos ayudantes en los mismos archivos a la vez: haz que trabajen uno detrás de otro, o cada uno en su worktree.
• Fiarse de un revisor «de solo lectura» sin mirar la línea tools: abre el archivo y comprueba que no estén Write, Edit ni Bash.
• Lanzar muchos «porque sí»: cada uno consume tokens propios, así que lanza solo los que tengan una tarea clara.

Lista de comprobación

• El trabajo es lo bastante grande como para merecer un ayudante
• La frase dice qué buscar y qué traer
• El contexto que necesita está escrito en la frase
• Los trabajos en paralelo no tocan los mismos archivos
• Sé que con /tasks veo quién está trabajando
• El revisor fijo solo tiene herramientas para leer

Preguntas frecuentes