Un subagente es una "instancia hija" de Claude Code que el agente principal lanza para hacer trabajo aislado: explorar un repo enorme, revisar un PR sin contaminar el contexto, ejecutar tareas independientes en paralelo. Bien usados, hacen que tu agente principal mantenga el contexto limpio y ahorran tokens.
Objetivos
Entender qué es un subagente y por qué existe.
Conocer los subagentes incorporados (general-purpose, Explore, Plan).
Crear un subagente personalizado para tu equipo.
Lanzar subagentes en paralelo y recoger resultados.
Aislar trabajo sucio en git worktrees.
6.1 Por qué existen los subagentes
El agente principal tiene un contexto: tu CLAUDE.md, la conversación, los ficheros que ha leído, los comandos que ha ejecutado. Cada operación añade tokens. En sesiones largas, el contexto se infla y la calidad cae.
Un subagente rompe esa dinámica:
Recibe una tarea con un prompt cerrado.
Tiene su propio contexto, vacío.
Devuelve una respuesta resumida al agente principal.
Resultado: el principal solo ve la respuesta del subagente, no las 80 lecturas de fichero que el subagente hizo internamente. El contexto del principal se mantiene compacto.
Mental model: agente principal = senior que orquesta. Subagentes = juniors a quienes delegas tareas concretas. El senior recibe el resumen, no el detalle.
6.2 Subagentes incorporados
Claude Code expone tres tipos por defecto:
Tipo
Para qué
Tools
general-purpose
Cualquier tarea multi-paso. Por defecto.
Todas
Explore
Búsquedas amplias en el repo cuando no estás seguro de dónde mirar.
Read-only (no Edit, no Write)
Plan
Diseñar una estrategia de implementación, no ejecutarla.
Read-only + razonamiento
Cuándo usa cada uno
Explore: cuando le pides "encuentra todos los sitios donde se usa X" o "dime cómo está organizado el módulo de pagos". El agente principal podría hacerlo, pero quemar 60 lecturas de archivo en su propio contexto contamina la sesión. Mejor delegar.
Plan: cuando hay que diseñar antes de tocar. "¿Cómo refactorizaríamos auth para soportar OAuth?" — el subagente Plan investiga y devuelve una propuesta sin tocar código.
general-purpose: para tareas independientes que se pueden hacer en paralelo. "Lanza 3 agentes a revisar este código por separado: uno mira seguridad, otro performance, otro estilo".
6.3 Lanzar subagentes en paralelo
El agente principal puede lanzar varios subagentes a la vez si las tareas son independientes. Esto multiplica throughput y mantiene el contexto principal limpio.
En la práctica, le dices algo como:
> Necesito tres revisiones del PR actual:
1. Subagente "security": busca vulnerabilidades.
2. Subagente "perf": busca cuellos de botella.
3. Subagente "tests": evalúa cobertura y calidad.
Lánzalos en paralelo y consolida los tres informes en uno.
El agente principal:
Lanza tres llamadas Agent en una misma respuesta (paralelas).
Espera a que las tres terminen.
Recibe los tres resúmenes.
Genera un informe consolidado.
El coste de tokens del principal es muy inferior a hacerlo todo él mismo, porque solo ve los resúmenes finales.
Cuándo NO paralelizar: tareas que dependen entre sí. Si la tarea B necesita la salida de A, no puedes lanzarlas a la vez. Mantén la secuencia.
6.4 Crear un subagente personalizado
Igual que las skills y los slash commands, los subagentes personalizados se definen en ficheros de configuración:
~/.claude/agents/<nombre>.md — global del usuario.
.claude/agents/<nombre>.md — del proyecto, versionado.
Ejemplo: subagente fundae-validator
Crea .claude/agents/fundae-validator.md:
---
name: fundae-validator
description: Valida ficheros de comunicación a FUNDAE (XML, formato oficial).
Comprueba esquema XSD, NIF de empresa, dígitos de control, estructura de
acciones formativas. Trigger cuando se solicite validar un grupo formativo
antes de enviar.
tools: [Read, Glob, Grep, Bash(xmllint:*)]
model: claude-sonnet-4-6
---
Eres un experto en la API de comunicación de FUNDAE. Tu trabajo es revisar
un fichero XML de comunicación de inicio o final de grupo formativo y
detectar errores antes de que se envíe.
Revisa:
1. Validez sintáctica (xmllint --noout).
2. Validez contra el XSD oficial de FUNDAE 2026.
3. Coherencia interna:
- NIF de empresa con dígito correcto.
- Fechas en orden (inicio < fin).
- Horas declaradas coherentes con la modalidad (online ≤ teleformación).
- Costes dentro del módulo económico vigente (€/h).
4. Riesgos típicos:
- Acción formativa sin código de homologación.
- Coste por participante > módulo + 10%.
- Documento sin firma electrónica de empresa.
Devuelve un informe estructurado:
- BLOCKERS (no se puede enviar): ...
- WARNINGS (se puede enviar pero verifica): ...
- OK: lista de checks que pasan.
NO modifiques el fichero. Solo informa.
A partir de ese momento puedes invocarlo desde el agente principal:
> Lanza el subagente fundae-validator sobre data/grupo-2026-q2.xml
y resúmeme el informe.
Modelo de este subagente. Útil para abaratar (usar Haiku para tareas mecánicas).
isolation
"worktree" para crear un git worktree aislado.
6.5 Subagentes con git worktrees
Un git worktree es un checkout secundario del repo en otra carpeta, apuntando a otra rama. Sirve para que un subagente trabaje sin tocar tu árbol de trabajo principal.
Si declaras isolation: worktree en el frontmatter, el sistema crea automáticamente:
.claude/worktrees/<random-name>/ ← worktree aislado
└── (todo el repo en una rama temporal)
El subagente trabaja allí. Si no hace cambios, el worktree se borra. Si hace cambios, se conserva con la rama generada y el agente principal recibe la ruta y el nombre de rama.
Caso de uso: cambios destructivos especulativos
"Quiero ver cómo quedaría si refactorizamos el módulo Auth, pero sin tocar mi rama actual." Lanzas un subagente con isolation worktree, te entrega el resultado en una rama paralela, y tú decides si mergeas o descartas.
Caso de uso: experimentos de migración
Migrar el repo de Vite a Webpack es un cambio enorme con riesgo. Hazlo en un worktree. Si rompe algo, abandonas la rama y el principal sigue intacto.
Combo poderoso: subagente + worktree + plan mode. Lanzas el subagente en plan mode dentro de un worktree para diseñar la migración. Si el plan te convence, sales de plan mode y dejas que ejecute en el worktree. Si rompe algo, descartas la rama. Riesgo cero.
6.6 Cuándo NO usar subagentes
Los subagentes consumen tokens (uno por uno tienen contexto propio). No es gratis. Evítalos cuando:
La tarea es pequeña. Si el agente principal puede hacerlo en 2-3 lecturas, no merece la pena lanzar un subagente.
El resultado debe quedar en el contexto principal. Por ejemplo: "lee este fichero y discutamos las opciones". El principal necesita el contenido, no un resumen.
La tarea es trivial. "Renombra esta variable" — el agente principal lo hace mejor que delegar.
Hay que aplicar muchos cambios pequeños correlacionados. Si subagente A toca un fichero y subagente B toca otro, pero ambos comparten asunciones, mejor un solo agente que vea todo.
Heurística simple
Lanza un subagente si:
La tarea consume mucho contexto que después no necesitas.
Necesitas paralelismo real entre tareas independientes.
Quieres aislamiento (worktree) para experimentar sin riesgo.
6.7 Subagente vs MCP server vs Skill
Confusión frecuente. Diferencias claras:
Pieza
Qué es
Cuándo
Subagente
Otra instancia de Claude Code con prompt y contexto propios.
Trabajo que se beneficia de aislar contexto / paralelismo.
MCP server
Servicio externo (Chrome, GitHub, base de datos) que expone herramientas.
Acceso a sistemas externos (red, API, devices).
Skill
Paquete de instrucciones que el agente carga bajo demanda.
Conocimiento de dominio reusable.
Y combinables: un subagente puede usar Skills cargadas y herramientas MCP. Por eso son tan potentes en composición.
Práctica
Ejercicio 6.1 · Triple revisión paralela
En un repo Node.js con un PR pendiente, pide al agente principal lanzar tres subagentes general-purpose en paralelo:
Uno revisa seguridad (XSS, SQLi, secretos).
Otro revisa performance (queries N+1, loops anidados).
Otro revisa estilo y nombres (naming, imports).
Pide consolidación final con prioridades. Observa el contexto del agente principal — ¿cuán pequeño se mantiene?
Ejercicio 6.2 · Subagente personalizado
Crea .claude/agents/release-notes-writer.md con:
Tools restringidas a Read y Bash con git.
Modelo Sonnet 4.6.
Prompt que produzca release notes en formato Markdown del estilo de tu equipo.
Pruébalo invocándolo desde el principal. Compara el contexto resultante con hacerlo todo en el principal.
Ejercicio 6.3 · Worktree experimental
Configura un subagente con isolation: worktree y úsalo para experimentar una migración: por ejemplo, cambiar todos los imports CommonJS a ESM. Cuando termine:
Examina el worktree generado.
Compara con tu rama principal.
Decide si mergeas o descartas.
Test de comprensión
1. ¿Cuál es la principal ventaja de delegar a un subagente?
Es más rápido siempre.
Mantiene limpio el contexto del agente principal.
Cuesta menos tokens en total.
Permite usar más Skills.
Respuesta correcta: B. El principal solo ve el resumen, no las decenas de lecturas internas. Útil en sesiones largas y tareas exploratorias. No siempre es más rápido ni más barato (depende).
2. Para "encuentra todos los usos de getUserById en el repo y dime cuántos hay", ¿qué subagente es mejor?
general-purpose
Explore
Plan
Ninguno — el principal lo hace
Respuesta correcta: B · Explore. Es read-only y especializado en búsquedas amplias. Sus lecturas no contaminan el contexto principal.
3. Activas isolation: worktree. ¿Qué ocurre?
El subagente no puede leer ficheros.
Se crea un git worktree y el subagente trabaja ahí, sin tocar tu árbol principal.
Se ejecuta en un container Docker.
No tiene acceso a la red.
Respuesta correcta: B. El sistema crea un worktree paralelo, el subagente trabaja ahí y al terminar conserva la rama si hubo cambios o limpia si no.
4. Tienes 3 tareas: A genera datos, B usa los datos de A para validar, C usa el resultado de B para informar. ¿Las paralelizas con subagentes?
Sí, son tres tareas independientes.
No, hay dependencias en cadena. Mantén la secuencia.
Solo paralelizo A y B.
Solo paralelizo B y C.
Respuesta correcta: B. Paralelizar tiene sentido solo cuando las tareas son independientes. Aquí B necesita la salida de A y C la de B — secuencia obligada.
Resumen
Subagente = instancia hija con contexto propio. Devuelve un resumen.
Tipos incorporados: general-purpose (todo), Explore (búsquedas), Plan (diseño).
Subagentes personalizados en .claude/agents/<nombre>.md.
Paralelizar solo cuando las tareas son independientes.
Worktrees para experimentos sin riesgo (refactor masivo, migración).
Siguiente módulo: MCP servers. Cómo Claude Code se conecta a Chrome, GitHub, bases de datos y otros sistemas.