La primera vez que usé un subagente, lo usé mal. Lo puse en marcha para renombrar una variable. Una variable. Fue como contratar a un operario para cambiar una bombilla: más lento, más caro y un poco ridículo. Así que antes de mostrarte cómo configurar un subagente en Claude Code, quiero ser directo sobre cuándo no deberías hacerlo.
Un subagente es una instancia separada de Claude a la que tu sesión principal puede delegar una tarea. Obtiene su propia ventana de contexto —una pizarra en blanco—, hace el trabajo y devuelve un resumen. La palabra clave es separada. El trabajo del subagente no ensucia tu conversación principal. Explora, repasa diez archivos, y tu sesión principal solo ve la conclusión.
Ese es el único propósito de los subagentes, y por eso la mayoría de los principiantes los usa mal.
Cuándo los subagentes realmente ayudan
Ayudan cuando una tarea de otro modo llenaría tu contexto principal con cosas que no necesitas conservar.
Piensa en buscar en una base de código grande "¿dónde gestionamos la autenticación?" Sin un subagente, Claude lee quince archivos en tu conversación principal, y ahora esos quince archivos están en el contexto durante el resto de la sesión, consumiendo tokens en cada turno. Con un subagente, esa exploración ocurre en una ventana desechable. Recibes de vuelta "la autenticación está en src/auth/, así es como fluye" —tres frases en lugar de quince archivos.
Entonces: los subagentes se ganan su lugar cuando el trabajo es exploratorio (mucha lectura, conclusión pequeña) o paralelo (varias cosas independientes a la vez). Buscar, investigar, ejecutar una suite de pruebas grande y resumir los fallos, revisar un diff contra una lista de verificación: todo esto es perfecto.
Esta es la prueba que uso ahora. Pregúntate: ¿esta tarea leerá mucho pero producirá poco? Si es sí, subagente. Si la tarea es una edición directa que ya puedes ver cómo hacer, hazla de forma directa. Renombrar una variable no lee nada y produce un cambio preciso. Sin subagente.
Cuándo NO usarlos
No uses un subagente para una edición de un solo archivo que ya entiendes. No uses uno para trabajo secuencial donde cada paso depende de ver el anterior. Y no uses uno solo porque suena sofisticado. Cada subagente tiene una sobrecarga: se inicia, construye su propio contexto, devuelve el informe. Para trabajos pequeños, esa sobrecarga cuesta más de lo que ahorra.
Los modelos de Claude más recientes también son bastante conservadores a la hora de crear subagentes por su cuenta, lo cual suele ser lo correcto. Si quieres delegar, a menudo tienes que pedirlo o configurarlo explícitamente. Lo que nos lleva al cómo.
Configurar un subagente personalizado
Claude Code te permite definir subagentes con nombre como archivos. Coloca un archivo markdown en .claude/agents/ de tu proyecto (o en tu configuración de inicio para uno global). Aquí hay uno real que uso para revisión de código:
---
name: reviewer
description: Reviews a diff for bugs and missing edge cases. Use after writing code, before committing.
tools: Read, Grep, Bash
---
You are a focused code reviewer. Given a diff or a set of changed files:
1. Read the changed code and the files it touches.
2. Look for actual bugs — off-by-one, null handling, wrong async behavior.
3. Check for missing edge cases and untested paths.
4. Report findings as a short list, each with a severity (high/medium/low).
Don't rewrite the code. Don't nitpick style. Report what you find and stop.
Hay algunas cosas que vale la pena señalar. La línea description no es decorativa: es cómo Claude decide cuándo delegar a este agente. Escríbela como escribirías la descripción de una herramienta: di cuándo usarla, no solo qué hace. "Usar después de escribir código, antes de hacer commit" le da a Claude un disparador concreto.
La línea tools delimita lo que el subagente puede tocar. Mi revisor tiene Read, Grep y Bash —suficiente para inspeccionar y ejecutar pruebas, nada para editar. Eso es deliberado. Un revisor no debería estar cambiando tu código. Limitar la lista de herramientas mantiene al subagente centrado en su tarea y es una preocupación menos.
El cuerpo es el prompt del sistema del subagente, su personalidad y trabajo completo. Observa que es específico y acotado. "Informa lo que encuentres y detente" importa, porque si no, un subagente ansioso empieza a arreglar cosas, y entonces tienes cambios que no pediste.
Cómo usarlo
Una vez que el archivo existe, puedes invocarlo en una sesión:
Usa el subagente reviewer en mi último commit.
Claude lo lanza, el subagente hace su lectura e informe en su propio contexto, y recibes de vuelta una lista limpia de hallazgos, sin que quince archivos aterricen en tu conversación principal. Para exploración, ni siquiera necesitas un archivo personalizado; el subagente general incorporado gestiona perfectamente las tareas ad hoc de "ve a averiguar X".
El cambio mental
Esto es lo que finalmente hizo que los subagentes encajaran para mí. Deja de verlos como "un Claude más potente". No son más inteligentes. Son una forma de mantener limpio tu contexto principal enviando el trabajo desordenado a otro lugar.
Una vez que lo ves así, la pregunta de cuándo usarlos se responde sola. ¿Trabajo desordenado, con mucha lectura y desechable? Delégalo. ¿Trabajo preciso que ya puedes imaginar? Hazlo tú mismo. Un revisor que ejecuta tus pruebas y te entrega una lista de hallazgos: genial. Un operario para cambiar una bombilla: no tanto.
Escribe un subagente esta semana. Haz que sea el revisor de arriba. Ejecútalo en tu próximo commit. Entonces sentirás la diferencia, y sabrás exactamente cuándo recurrir al siguiente.