Claude Code Subagents: qué son, cómo crearlos y usarlos
Los Claude Code Subagents son agentes especializados que trabajan con su propio contexto, instrucciones, modelo, herramientas y permisos. Permiten delegar búsquedas, revisión de código, debugging, testing y otras tareas sin llenar la conversación principal con cientos de archivos, logs o resultados intermedios.
¿Qué son los subagentes de Claude Code?
Los subagentes son asistentes especializados
que Claude Code puede utilizar para delegar tareas.
Cada uno dispone de una ventana de contexto propia
y puede tener instrucciones, herramientas,
modelo, permisos, Skills, memoria
e incluso servidores MCP específicos.
Los subagentes de proyecto se definen normalmente
mediante archivos Markdown dentro de
.claude/agents/,
mientras que los personales se guardan en
~/.claude/agents/.
El subagente realiza el trabajo por separado
y devuelve sus conclusiones a la conversación principal.
Para qué sirven los subagentes
Su principal ventaja es separar trabajo especializado del contexto principal.
Ahorrar contexto
Logs, búsquedas y archivos explorados permanecen fuera de la conversación principal.
Especializar tareas
Puedes crear agentes expertos en seguridad, tests, bases de datos o APIs.
Limitar herramientas
Un agente puede disponer únicamente de las herramientas que realmente necesita.
Elegir modelo
Puedes asignar diferentes modelos según complejidad y coste.
Trabajar en paralelo
Varias investigaciones independientes pueden ejecutarse simultáneamente.
Memoria propia
Un subagente puede mantener conocimiento persistente entre sesiones.
Claude delega, el subagente trabaja y devuelve un resumen
El trabajo detallado puede permanecer fuera de tu conversación principal.
Claude delega
La tarea coincide con la descripción de un subagente especializado.
El agente investiga
Utiliza su propio contexto, herramientas e instrucciones.
Devuelve resultados
Solo las conclusiones relevantes regresan a la conversación principal.
Cada subagente empieza con una ventana de contexto propia
Esta es una de las diferencias más importantes respecto de trabajar directamente en la conversación principal.
No recibe automáticamente toda tu conversación
Un subagente normal comienza con un contexto nuevo. Claude prepara un mensaje que resume la tarea y el agente investiga desde allí.
El agente puede leer docenas de archivos, ejecutar tests o procesar logs extensos sin añadir directamente todo ese contenido al contexto principal.
Qué contexto recibe un subagente personalizado
Su system prompt propio.
El mensaje de delegación preparado por Claude.
Los archivos CLAUDE.md relevantes.
Información básica del entorno y directorio de trabajo.
Una instantánea del estado de Git cuando corresponde.
Los Skills
definidos mediante
skills:.
Los subagentes integrados Explore y Plan omiten CLAUDE.md y el estado de Git para realizar exploraciones más ligeras.
Subagentes incluidos en Claude Code
Claude Code ya dispone de varios agentes internos que puede utilizar automáticamente.
Exploración rápida
Agente de solo lectura especializado en búsqueda, archivos y comprensión del codebase.
Investigación para Plan Mode
Investiga el codebase antes de que Claude presente una estrategia.
Tareas complejas
Puede combinar investigación, razonamiento y modificaciones.
Usar un subagente para explorar el codebase
Una investigación puede producir muchísimo contenido que no necesitas conservar en la conversación principal.
Usa un subagente Explore para investigar
cómo funciona la autenticación.
Devuélveme únicamente:
- archivos principales
- flujo completo
- dependencias
- puntos de extensión
- riesgos
No modifiques código.Cómo crear un subagente personalizado
Los subagentes personalizados son archivos Markdown con YAML frontmatter.
Ubicación recomendada
.claude/agents/code-reviewer.mdDisponible en todos tus proyectos
~/.claude/agents/code-reviewer.md/agents ya no abre el antiguo asistente de creación
Claude Code cambió recientemente el flujo para crear agentes.
Pídele a Claude que cree el archivo
Crea un subagente de proyecto llamado code-reviewer
en .claude/agents/.
Debe:
- revisar calidad
- revisar seguridad
- buscar regresiones
- revisar tests
- ser solo lectura
- utilizar Sonnet
/agents
ya no abre
el asistente interactivo
de creación.
Puedes pedirle directamente
a Claude que escriba
el archivo
o crearlo manualmente.
Subagente básico para revisar código
---
name: code-reviewer
description: Revisa cambios de código buscando bugs, problemas de seguridad, regresiones y falta de tests. Úsalo después de cambios importantes.
tools: Read, Glob, Grep
model: sonnet
---
Eres un revisor senior de código.
Cuando seas invocado:
1. identifica los archivos modificados
2. revisa la lógica
3. busca regresiones
4. busca problemas de seguridad
5. revisa manejo de errores
6. comprueba cobertura de tests
7. evita comentarios puramente estéticos
Para cada problema incluye:
- severidad
- archivo
- causa
- impacto
- recomendación
No modifiques archivos.Campos del frontmatter de un subagente
Solo
name
y
description
son obligatorios.
| Campo | Función |
|---|---|
name |
Identificador único del agente |
description |
Cuándo Claude debería delegarle trabajo |
tools |
Herramientas que puede utilizar |
disallowedTools |
Herramientas explícitamente bloqueadas |
model |
Modelo utilizado por el agente |
permissionMode |
Modo de permisos |
maxTurns |
Máximo de turnos agentic |
skills |
Skills cargados al iniciar |
mcpServers |
Servidores MCP disponibles |
memory |
Memoria persistente |
hooks |
Hooks propios del agente |
effort |
Nivel de esfuerzo del agente |
background |
Preferencia de ejecución en segundo plano |
isolation |
Permite aislarlo mediante worktree |
La descripción determina cuándo Claude utiliza el agente
Claude consulta las descripciones para decidir qué agente debería ejecutar.
“Revisa código”
No explica qué tipo de revisión debe realizar ni cuándo usarlo.
Define tarea + momento
Explica qué especialidad tiene y qué solicitudes deberían delegarse.
description: Especialista en seguridad WordPress. Revisa plugins, themes, AJAX, REST API, nonces, capabilities, SQL y manejo de archivos. Úsalo proactivamente después de cambios relacionados con autenticación, usuarios, pagos o datos sensibles.Claude puede delegar sin que nombres el subagente
Cuando la solicitud coincide claramente con su descripción, Claude puede decidir utilizarlo automáticamente.
Si quieres aumentar
la probabilidad
de delegación automática,
puedes incluir
expresiones como
“use proactively”
o su equivalente
dentro de
description.
Las descripciones de todos tus subagentes forman parte del contexto que Claude utiliza para descubrirlos.
Cómo llamar explícitamente a un subagente
Nombra al agente
Usa el subagente code-reviewer
para revisar los cambios de autenticación.Garantizar un agente concreto
También puedes
escribir @
y seleccionar
el subagente
desde el selector,
de forma similar
a mencionar
un archivo.
Nombrarlo
en lenguaje natural
normalmente anima
a Claude a delegar.
La mención
@
selecciona explícitamente
qué subagente
debe ejecutarse.
Ejecutar toda una sesión con un agente
También puedes utilizar una definición de agente como comportamiento principal de una sesión completa.
claude --agent code-reviewerLa sesión principal utiliza el system prompt, herramientas y modelo definidos por ese agente.
Definir un agente predeterminado para el proyecto
{
"agent": "code-reviewer"
}
El flag
--agent
tiene prioridad
si además defines
un agente
mediante settings.
Elegir un modelo para cada subagente
No todas las tareas necesitan el mismo nivel de capacidad.
| Valor | Uso habitual |
|---|---|
haiku |
Búsquedas y tareas simples |
sonnet |
Desarrollo y revisión general |
opus |
Razonamiento y tareas complejas |
inherit |
Utilizar el modelo de la conversación principal |
Una búsqueda relativamente sencilla puede ejecutarse en un modelo más ligero, reservando modelos de mayor capacidad para tareas complejas.
Limitar las herramientas disponibles
Un agente de revisión no necesita necesariamente permiso para modificar archivos.
---
name: security-reviewer
description: Revisa código buscando problemas de seguridad
tools: Read, Grep, Glob
model: sonnet
---
Revisa el código.
No modifiques archivos.
Devuelve únicamente hallazgos verificables.Si el agente solo necesita leer, no le concedas herramientas de escritura.
Bloquear herramientas con disallowedTools
---
name: repo-analyzer
description: Analiza estructura y arquitectura del repositorio
disallowedTools:
- Write
- Edit
---
Investiga el proyecto
y devuelve un informe.
No modifiques archivos.Configurar permissionMode por subagente
| Modo | Comportamiento |
|---|---|
default |
Pide permisos cuando corresponde |
acceptEdits |
Acepta ediciones permitidas con menos interrupciones |
auto |
Utiliza controles automáticos del modo Auto |
dontAsk |
Niega automáticamente prompts no preautorizados |
plan |
Exploración de solo lectura |
Determinados modos
de la conversación principal
pueden prevalecer
sobre
permissionMode
del subagente.
Precargar Skills dentro de un subagente
Puedes proporcionar conocimiento especializado directamente desde que el agente comienza.
---
name: api-developer
description: Implementa endpoints siguiendo las convenciones del proyecto
model: sonnet
skills:
- api-conventions
- error-handling-patterns
---
Implementa endpoints
siguiendo los Skills
cargados en tu contexto.Los Skills declarados aquí se inyectan al contexto al iniciar el subagente.
Dar memoria persistente a un subagente
Un agente especializado puede acumular conocimiento sobre patrones, errores y arquitectura.
---
name: code-reviewer
description: Revisa código y aprende patrones recurrentes del proyecto
memory: project
---
Revisa el código.
Actualiza tu memoria
cuando descubras:
- patrones arquitectónicos
- convenciones
- errores recurrentes
- ubicaciones importantes
- decisiones técnicas| Scope | Uso |
|---|---|
user |
Aprendizajes entre todos tus proyectos |
project |
Memoria del repositorio compartible por Git |
local |
Memoria local del proyecto no versionada |
Permite construir conocimiento institucional específico de un repositorio.
Dar servidores MCP únicamente a un subagente
También puedes limitar una integración externa al agente que realmente necesita utilizarla.
---
name: browser-tester
description: Prueba funcionalidades en un navegador real
mcpServers:
- playwright:
type: stdio
command: npx
args:
- "-y"
- "@playwright/mcp@latest"
---
Usa Playwright
para navegar,
interactuar
y verificar
la funcionalidad solicitada.Definir un servidor directamente dentro del subagente evita cargar sus herramientas en la conversación principal cuando no son necesarias.
Claude Code MCP →Subagentes en foreground y background
Bloquea la conversación
La conversación principal espera hasta que el subagente finaliza.
Trabaja en paralelo
Puedes seguir trabajando mientras el subagente continúa con su tarea.
Si un subagente en background necesita autorización, Claude Code puede mostrar la solicitud en la sesión principal.
Ejecutar varios subagentes simultáneamente
Funciona especialmente bien cuando las áreas pueden investigarse de forma independiente.
Investiga este proyecto en paralelo.
Usa un subagente para:
- autenticación
Otro para:
- base de datos
Y otro para:
- API
Cada uno debe devolver:
- arquitectura
- archivos relevantes
- dependencias
- riesgos
- problemas encontrados
Después sintetiza las conclusiones.Aislar operaciones que generan demasiado contenido
Este es uno de los usos más efectivos de los subagentes.
Suites extensas
El agente procesa cientos de líneas y devuelve solo los fallos relevantes.
Logs grandes
Puede buscar patrones sin llenar la sesión principal.
Documentación
Investiga múltiples fuentes y devuelve conclusiones concretas.
Usa un subagente para ejecutar
toda la suite de tests.
No devuelvas la salida completa.
Devuélveme únicamente:
- tests fallidos
- mensaje de error
- causa probable
- archivo relacionadoEncadenar varios subagentes
No todos tienen que trabajar simultáneamente.
Usa primero el subagente performance-reviewer
para detectar problemas de rendimiento.
Después utiliza el subagente optimizer
para proponer soluciones
a los problemas encontrados.
No implementes nada todavía.Un subagente también puede delegar trabajo
Claude Code permite actualmente delegación en varios niveles.
Hasta tres niveles de subagentes
De forma predeterminada, un subagente puede crear otros subagentes hasta tres niveles por debajo de la conversación principal.
Por ejemplo, un agente de auditoría podría delegar autenticación, API y base de datos a agentes especializados y devolver un único informe final.
Limitar la profundidad de subagentes
{
"env": {
"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
}
}
Si estableces
el valor en
1,
los subagentes
no podrán crear
una segunda capa.
Cuántos subagentes pueden ejecutarse al mismo tiempo
El límite predeterminado actual es 20
Cuando ya existen 20 subagentes ejecutándose dentro de una sesión, Claude Code normalmente impide crear otro hasta liberar capacidad.
{
"env": {
"CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "10"
}
}Cuándo conviene utilizar un subagente
La tarea genera muchísima salida que no necesitas conservar.
Necesitas una especialización clara como seguridad o base de datos.
Quieres limitar herramientas disponibles.
La tarea puede ejecutarse de forma independiente.
Quieres realizar varias investigaciones en paralelo.
Necesitas un agente con MCP específico.
Necesitas memoria especializada entre sesiones.
Cuándo NO conviene utilizar un subagente
Necesitas conversación constante y refinamiento paso a paso.
Planificación, implementación y testing dependen fuertemente del mismo contexto.
Solo necesitas realizar un cambio pequeño y localizado.
La latencia es importante y el agente tendría que reconstruir mucho contexto.
Subagent vs Skill
| Aspecto | Subagent | Skill |
|---|---|---|
| Contexto aislado | Sí | Normalmente no |
| Procedimiento reutilizable | Posible | Ideal |
| Modelo propio | Sí | Depende de ejecución |
| Herramientas propias | Sí | Puede autorizarlas |
| Memoria propia | Sí | No de la misma forma |
| Ideal para checklist | Posible | Sí |
Un subagente puede precargar Skills, y un Skill puede ejecutarse dentro de un subagente.
Subagent normal vs fork de la conversación
Un fork es un tipo especial de subagente.
| Aspecto | Subagent normal | Fork |
|---|---|---|
| Contexto inicial | Nuevo | Copia la conversación |
| Historial del chat | No | Sí |
| Tools | Según definición | Hereda el pool principal |
| Ideal para | Tarea autocontenida | Side task con mucho contexto previo |
Crear una subtarea desde el contexto actual
/subtask crea tests unitarios para los cambios del parserResulta útil cuando un agente nuevo tendría que reconstruir demasiado contexto de la conversación para entender la subtarea.
Continuar el trabajo de un subagente anterior
Una nueva invocación normalmente crea una nueva instancia, pero Claude puede reanudar determinados subagentes.
Usa code-reviewer
para revisar el módulo de autenticación.
[El agente termina]
Continúa esa misma revisión
y analiza ahora
el sistema de autorización.Los agentes integrados Explore y Plan son de una sola ejecución y no devuelven un Agent ID reutilizable. Para trabajo continuado, utiliza general-purpose o un agente personalizado.
Aislar un subagente mediante Git worktree
Para agentes que modifican código, puedes separarlos del checkout principal.
---
name: feature-developer
description: Implementa funcionalidades de forma aislada
tools: Read, Glob, Grep, Edit, Write, Bash
model: sonnet
isolation: worktree
---
Implementa la tarea
dentro de tu worktree.
Ejecuta tests
antes de finalizar.El subagente trabaja sobre una copia aislada del repositorio en vez de editar directamente el checkout principal.
Ejemplo de subagente especialista en WordPress
---
name: wordpress-security
description: Especialista en seguridad WordPress. Úsalo para revisar plugins, themes, AJAX, REST API, formularios, usuarios, WooCommerce y consultas SQL.
tools: Read, Glob, Grep
model: sonnet
memory: project
---
Eres especialista en seguridad WordPress.
Revisa:
## Inputs
- sanitize_text_field
- sanitize_email
- absint
- esc_url_raw
- validaciones personalizadas
## Outputs
- esc_html
- esc_attr
- esc_url
- wp_kses
## Autorización
- current_user_can
- roles
- capabilities
- ownership
## Requests
- nonces
- AJAX
- REST API
- permission_callback
## Base de datos
- $wpdb->prepare()
- SQL injection
- validación de IDs
- tipos de datos
## Archivos
- uploads
- MIME
- rutas
- traversal
## WooCommerce
Cuando corresponda revisa:
- checkout
- orders
- My Account
- customer data
- endpoints
Devuelve hallazgos
ordenados por severidad.
No modifiques archivos.Ejemplo de subagente Debugger
---
name: debugger
description: Especialista en investigar bugs, errores de runtime, tests fallidos y comportamiento inesperado. Úsalo cuando exista un error reproducible.
tools: Read, Glob, Grep, Bash
model: sonnet
---
Investiga el problema antes de proponer cambios.
Proceso:
1. reproduce el error
2. identifica el flujo afectado
3. sigue el stack trace
4. encuentra la causa raíz
5. descarta hipótesis incorrectas
6. identifica la corrección mínima
7. indica cómo verificarla
No ocultes síntomas.
Busca la causa real.
Devuelve:
- causa
- evidencia
- archivos involucrados
- propuesta de solución
- tests recomendadosSubagente con reglas condicionales mediante Hooks
Los Hooks permiten validar una acción antes de ejecutarla.
Agente de base de datos de solo lectura
Puedes permitir
Bash
pero utilizar
un Hook
PreToolUse
para bloquear
operaciones SQL
de escritura.
En lugar de bloquear Bash completamente, el Hook puede inspeccionar cada comando y permitir únicamente operaciones seguras.
Claude Code Hooks →Errores al crear subagentes
Description demasiado genérica: Claude no sabe cuándo delegar.
Demasiadas herramientas: aumenta innecesariamente las capacidades del agente.
Esperar que conozca todo el chat: un subagente normal comienza con contexto aislado.
System prompt enorme: utiliza instrucciones precisas y mueve conocimiento reutilizable a Skills.
Usarlo para cambios triviales: puede añadir latencia innecesaria.
Nombres duplicados: mantén identificadores únicos en cada árbol de agents.
YAML inválido: puede provocar que Claude Code ignore el archivo.
Conceder MCP innecesarios: limita integraciones al agente que realmente las necesita.
Claude Code no detecta mi subagente
Comprueba que
el archivo
empiece directamente
con ---.
Confirma que
existen
name
y
description.
El nombre debe utilizar minúsculas y guiones.
Evita
:
dentro
del nombre.
Revisa que el YAML sea válido.
Si acabas
de crear
por primera vez
el directorio
agents,
reinicia Claude Code.
Iniciar Claude con logs
claude --debugCómo diseñar buenos subagentes
Dale una especialidad clara.
Escribe una description corta pero específica.
Aplica mínimo privilegio en tools.
Utiliza Skills para conocimiento reusable.
Usa memoria únicamente cuando el aprendizaje deba persistir.
Aísla cambios paralelos mediante worktrees.
No devuelvas resultados intermedios enormes: pide resúmenes.
Utiliza la conversación principal cuando las fases comparten mucho contexto.
Qué mecanismo utilizar en Claude Code
Documentación oficial de Claude Code Subagents
Los subagentes están evolucionando rápidamente, especialmente en contexto, paralelismo, nesting, memoria y aislamiento.
Custom Subagents
Creación, configuración, modelos, tools, memoria y delegación.
Ver documentación oficial →Agents
Agentes, paralelismo y trabajo en sesiones separadas.
Ver Agents →Skills
Procedimientos y conocimiento que pueden precargarse dentro de agentes.
Ver Skills →Guías relacionadas
Continúa con MCP, Plugins, Hooks, Sandbox y automatización avanzada.
FAQ sobre Claude Code Subagents
Respuestas sobre creación, contexto, tools, modelos, memoria, nesting y delegación.
Un subagente es un asistente especializado que Claude Code puede utilizar para ejecutar una tarea concreta dentro de su propio contexto.
Los agentes
específicos de un proyecto
se guardan normalmente
en
.claude/agents/.
Los agentes personales
disponibles en todos
tus proyectos
se guardan en
~/.claude/agents/.
Claude Code incluye subagentes integrados y también puede delegar automáticamente a agentes personalizados cuando una tarea coincide con su descripción.
Un subagente normal comienza con un contexto aislado y no recibe automáticamente todo el historial de la conversación. Claude prepara una tarea resumida para delegarle.
Un subagente normal comienza con contexto nuevo. Un fork hereda la conversación, herramientas y contexto acumulado de la sesión principal.
Un Skill representa principalmente instrucciones o procedimientos reutilizables. Un subagente ejecuta una tarea en un contexto separado y puede tener modelo, herramientas, permisos y memoria propios.
Sí.
El campo
model
permite seleccionar
aliases como
sonnet,
opus,
haiku
o inherit,
además de IDs
de modelos compatibles.
Sí.
El campo
memory
puede utilizar
scopes
user,
project
o local
para mantener
conocimiento
entre conversaciones.
Sí. Claude Code permite actualmente subagentes anidados. El límite predeterminado es de tres niveles por debajo de la conversación principal y puede configurarse.
Claude Code utiliza actualmente un límite predeterminado de 20 subagentes ejecutándose de forma concurrente dentro de una sesión, aunque el valor puede configurarse.
Conecta Claude Code con herramientas externas mediante MCP
Ya sabes cómo delegar tareas especializadas en agentes con su propio contexto, modelo y herramientas. El siguiente paso es permitir que Claude Code acceda a servicios externos mediante Model Context Protocol.
Claude Code MCP →