Claude Code: reparte el trabajo en subagentes (contexto aparte)

Un subagente es un ayudante dentro de Claude Code con su propia conversación aparte. Tú le mandas una tarea (por ejemplo, «explora este proyecto y dime cómo está montado») y él la hace en su contexto, sin ensuciar la conversación principal.

Cuando termina, vuelve y te da solo el resultado. Todo lo que leyó y probó por el camino no te ocupa sitio en el hilo de arriba.

Claude Code ya trae tres de serie: Explore (para mirar y buscar por el proyecto), Plan (para planificar) y general-purpose (para tareas variadas). Además, tú puedes crear los tuyos con sus propias normas y herramientas. Cada subagente es un fichero de texto en la carpeta .claude/agents/.

• No llenar la conversación principal. Las tareas pesadas (explorar un proyecto entero, revisar muchos ficheros) consumen mucho contexto. Un subagente se lo come él y a ti solo te devuelve la conclusión.
• Tener ayudantes especializados. Uno para revisar código, otro para escribir pruebas, otro para documentar. Cada uno con sus normas fijas.
• Repartir el trabajo. Puedes lanzar varios a la vez, cada uno en lo suyo.

Es la diferencia entre preguntar todo en una sola charla infinita o tener un equipo al que mandas encargos sueltos.

• Decide qué subagente quieres. Empieza por uno que ya trae Claude (Explore, Plan, general-purpose) para probar cómo funciona.

• Crea el subagente. Hoy se hace de una de estas dos maneras:
• Pídeselo a Claude en lenguaje normal: «créame un subagente que revise el estilo del código». Él escribe el fichero por ti.
• Escríbelo tú a mano: crea un fichero de texto en .claude/agents/ (dentro del proyecto) o en ~/.claude/agents/ (para todos tus proyectos). El fichero lleva arriba unos datos (nombre, descripción y qué herramientas puede usar) y debajo las instrucciones.

• Dale un encargo. Pídele a Claude que use ese subagente para la tarea. Trabajará en su contexto y te devolverá el resultado limpio.

• Ajusta lo que haga falta. Si el subagente no hace lo que esperabas, cambia sus instrucciones (el texto del fichero) y vuelve a probar.

Matiz importante (lo que el truco original no cuenta): el paso que dice «usa /agents para ver y crear subagentes» ya no es correcto. Desde la versión 2.1.198 de Claude Code, el comando /agents ya no abre el asistente de creación: solo imprime un recordatorio. La forma correcta hoy es crear o editar el fichero a mano en .claude/agents/ (o ~/.claude/agents/) o pedírselo a Claude para que lo escriba.

Lo demás sí es correcto y está en la documentación oficial: los subagentes tienen contexto aparte, los integrados Explore, Plan y general-purpose existen y se definen como ficheros markdown.

Otros avisos:

• Claude Code es de pago (plan Pro o clave de API). No entra en el plan gratuito de Claude.
• Demasiados subagentes a la vez se pueden pisar entre ellos si tocan los mismos ficheros. Para trabajo que edita lo mismo, mejor de uno en uno.

Comprobado el 06/10/2026 en la documentación oficial de Claude Code (code.claude.com/docs/en/sub-agents).

1. Escribo /agents y no se abre un asistente. Es lo esperado desde la versión 2.1.198: ese comando ya no crea subagentes. Crea el fichero a mano en .claude/agents/ o pídele a Claude que te lo cree.

2. Mi subagente no aparece. Revisa que el fichero esté en la carpeta correcta (.claude/agents/ dentro del proyecto, o ~/.claude/agents/ para todos) y que los datos de arriba (nombre y descripción) estén bien escritos.

3. El subagente no hace lo que quiero. Es cuestión de las instrucciones que tiene dentro: cuéntale con más detalle qué debe hacer y qué no. Cuanto más concretas, mejor.

4. La conversación principal sigue llenándose. Comprueba que la tarea la está haciendo el subagente y no Claude directamente. Pídeselo de forma explícita: «usa un subagente para esto».