Guía

Cómo usar subagentes en Claude Code

Las búsquedas largas y la salida ruidosa de las pruebas llenan muy deprisa tu conversación de Claude Code. Los subagentes se llevan ese trabajo a un contexto aparte y te devuelven un resumen. Esta guía explica qué son, cómo crear los tuyos y cuándo merecen la pena.

Actualizado 30 de octubre de 2026

Respuesta rápida: un subagente es un ayudante especializado al que Claude Code le pasa una tarea. Trabaja en su propia ventana de contexto, con sus propias instrucciones y acceso a herramientas, y solo devuelve un resultado. Para crear uno, guarda un archivo Markdown con name y description en su frontmatter en .claude/agents/ (un proyecto) o ~/.claude/agents/ (todos los proyectos); después pídele a Claude que lo use por su nombre o elígelo con @.

Los detalles de abajo proceden de la documentación de Claude Code de Anthropic en octubre de 2026. Claude Code cambia a menudo, así que ejecuta claude update si falta algo de lo que se describe aquí.

Qué son los subagentes

Cuando Claude se encuentra con una tarea que coincide con la descripción de un subagente, puede delegársela. El subagente empieza de cero: no ve tu conversación, solo las instrucciones que Claude le pasa. Hace su trabajo, como leer decenas de archivos o ejecutar una batería de pruebas, y devuelve un resumen. Tu conversación principal se mantiene corta.

Claude Code incluye subagentes integrados, entre ellos:

Explore: búsqueda y análisis rápidos de solo lectura en una base de código.
Plan: investigación de solo lectura mientras estás en modo plan.
General-purpose (uso general): tareas de varios pasos que necesitan tanto explorar como cambiar cosas.

No tienes que configurarlos; Claude los usa cuando encajan.

Crea tu propio subagente

Decide el ámbito. Para un subagente que pueda usar todo el equipo en un repositorio, crea la carpeta .claude/agents/ en el proyecto. Para uno que te acompañe en todos tus proyectos, usa ~/.claude/agents/.
Crea un archivo Markdown en esa carpeta, por ejemplo code-reviewer.md.
Empieza el archivo con un frontmatter entre dos líneas ---. La primera línea del archivo tiene que ser ---.
Añade los dos campos obligatorios: name (un identificador único, por ejemplo code-reviewer, sin dos puntos) y description (cuándo debe usarlo Claude, por ejemplo Reviews code for quality and best practices. Use after code changes.).
Si quieres, añade tools para limitar lo que puede usar, por ejemplo Read, Glob, Grep para un revisor de solo lectura, y model (un alias de modelo como sonnet o haiku, un ID de modelo completo o inherit).
Debajo del --- de cierre, escribe las instrucciones del subagente en lenguaje normal: su función, qué debe revisar y qué debe devolver.
Guarda el archivo. Claude Code detecta los cambios en una carpeta de agentes existente en pocos segundos; si creaste la carpeta durante la sesión, reinicia Claude Code.

También puedes simplemente pedirle a Claude en una sesión que cree un subagente por ti. En las versiones actuales, el comando /agents te remite justo a eso, o a editar las carpetas directamente.

Usa un subagente

Deja que Claude elija: Claude compara tu petición con la description de cada subagente. Palabras como «use proactively» en la descripción le animan a delegar.
Pídelo por su nombre: por ejemplo Usa el subagente code-reviewer para revisar mis últimos cambios.
Menciónalo: escribe @ y elige el subagente. Así te aseguras de que ese subagente se encarga de la tarea.
Para una sesión entera: ejecuta claude --agent code-reviewer.

Cuándo ayudan los subagentes y cuándo no

Las recomendaciones de Anthropic se resumen así:

Usa un subagente cuando	Quédate en la conversación principal cuando
La tarea produce mucha salida que no necesitas conservar, como registros o resultados de búsqueda	Necesitas un ida y vuelta frecuente
Quieres restringir qué herramientas se pueden usar	Varios pasos comparten mucho contexto
El trabajo es autónomo y puede terminar en un resumen	Es un cambio rápido y concreto
Quieres que investigaciones independientes se ejecuten en paralelo

Conviene saber

Si dos subagentes tienen el mismo nombre, gana la ubicación con más prioridad: la configuración gestionada, luego la opción --agents, luego la carpeta del proyecto, luego tu carpeta de usuario y por último los plugins.
Un subagente no ve tu historial de chat ni los archivos que Claude ya ha leído, así que depende de las instrucciones que Claude le da.
Por defecto pueden ejecutarse hasta 20 subagentes a la vez.
Los nombres de los campos van en camelCase (por ejemplo disallowedTools, maxTurns) y los campos no reconocidos se ignoran sin avisar, así que revisa la ortografía.
Puedes hacer commit de los archivos de subagentes del proyecto, para que todo el equipo tenga los mismos ayudantes.

Si no funciona

Claude no encuentra el nuevo subagente: si la carpeta de agentes no existía cuando empezó la sesión, reinicia Claude Code.
El archivo se omite sin avisar: las causas habituales son que falte name o description, un YAML no válido o que --- no esté en la primera línea. Ejecuta claude --debug y lee el registro de depuración, o ejecuta claude plugin validate .claude/agents para encontrar los archivos cuyo frontmatter no se puede analizar.
Claude informa de un error con herramientas sin resolver: cuando ninguna de las entradas de tools coincide con una herramienta real, Claude Code normalmente no inicia el subagente. Corrige cómo están escritos los nombres de las herramientas.
Modelo equivocado: ejecuta /tasks para ver qué modelo usa realmente cada subagente.

Guarda los resultados, no solo el resumen

El informe de un subagente acaba en tu sesión, que desaparece de la vista en cuanto la cierras. Con el plugin de Workbranch para Claude Code, decir «guarda esto en Workbranch» archiva en un proyecto las tareas, decisiones y preguntas abiertas de la sesión, y la siguiente sesión en esa carpeta empieza con lo que sigue pendiente. Consulta Workbranch para Claude. Si una sesión se quedó sin espacio, reanudar una sesión de Claude Code explica cómo volver a ella.

Fuentes

Use Claude Code with your Pro or Max plan (Centro de ayuda de Claude, consultado el 30 de octubre de 2026)
Create custom subagents (Claude Code Docs, consultado el 30 de octubre de 2026)

Preguntas frecuentes

¿Los subagentes consumen uso adicional?

Las peticiones de los subagentes cuentan para los mismos límites de uso que tu conversación principal. Enviar el trabajo sencillo a un modelo más barato, como Haiku, mediante el campo model puede ayudar a contener los costes.

¿Un subagente puede iniciar sus propios subagentes?

Sí, por defecto hasta tres niveles por debajo de la conversación principal. Para impedir que un subagente concreto lo haga, deja Agent fuera de su lista de herramientas.

¿Puedo ejecutar una sesión entera como subagente?

Sí. Inicia Claude Code con claude --agent seguido del nombre del subagente, y la sesión usará el prompt, las herramientas y el modelo de ese subagente.