Subagentes
Los subagentes son "ayudantes especializados" que Claude Code puede lanzar para trabajar en paralelo: uno revisa código, otro investiga, otro escribe tests... mientras el agente principal coordina y tú solo revisas resultados.
Revisado el 16 de agosto de 2026 · Claude Code v2.1.233
¿Para qué sirven?
En tareas grandes, en vez de hacerlo todo de forma lineal, Claude Code puede repartir el trabajo entre varios subagentes con roles concretos (revisor, planificador, depurador, investigador). Ventajas:
- Paralelismo: varios trabajando a la vez = más rápido.
- Contexto limpio: cada subagente tiene su propia "memoria", sin mezclar.
- Especialización: cada uno con sus instrucciones y herramientas.
- Background: pueden correr de fondo sin bloquearte.
Qué cambió en v2.1.232
Desde esa versión, un subagente con subagent_type: "fork" puede heredar la conversación completa y reutilizar el prompt cache. Además, los agentes que no son teammates y se lanzan desde una sesión interactiva pasan a segundo plano por defecto.
Esto no convierte todos los subagentes en copias del principal. Un subagente normal sigue siendo útil para aislar contexto; usa un fork solo cuando necesite el historial completo. Revisa también archivos, permisos, modelo y directorio de trabajo efectivos antes de confiar en su resultado.
Crear un subagente
Un subagente es un archivo Markdown con frontmatter YAML (configuración) y un cuerpo que es su system prompt (sus instrucciones de personalidad y rol).
.claude/agents/
├── revisor.md
├── depurador.md
└── investigador.mdEjemplo: un subagente revisor de código
---
name: revisor
description: Revisa código en busca de bugs y malas prácticas. Úsalo tras escribir o cambiar código.
tools: Read, Grep, Glob
model: sonnet
color: blue
---
Eres un revisor de código senior. Tu trabajo es leer los cambios y encontrar:
- Bugs potenciales y casos límite no cubiertos.
- Nombres poco claros y código difícil de mantener.
- Problemas de seguridad.
No edites archivos: solo informa de lo que encuentres, ordenado por gravedad.
Sé directo pero constructivo.Campos del frontmatter
| Campo | Para qué sirve |
|---|---|
name | Nombre del subagente. Obligatorio. |
description | Cuándo usarlo. El agente principal lo lee para delegar. Obligatorio. |
tools | Lista blanca de herramientas que puede usar (p. ej. Read, Grep). Limítalas por seguridad. |
model | Modelo a usar: sonnet, opus, fable o inherit (heredar del principal). |
permissionMode | Modo de permisos para este subagente. |
color | Color con el que se muestra en la interfaz. |
hooks | Hooks específicos de este subagente. |
skills | Skills que se precargan al lanzarlo. |
background | Si es true, corre en segundo plano. |
effort | Nivel de esfuerzo/razonamiento. |
Dónde se guardan
- Proyecto (recomendado):
.claude/agents/<nombre>.md - Personal:
~/.claude/agents/<nombre>.md - Vía plugin: dentro del plugin (
agents/...) - Solo para una sesión: con el flag
--agents '{...}'(no se guarda en disco)
Cómo invocarlos
Delegación natural
Simplemente pídeselo al agente principal:
Mención directa
@"revisor (agent)" revisa src/pagos.tsAsistente interactivo
Usa el comando /agents para abrir un asistente que te guía en la creación y gestión de subagentes sin escribir el YAML a mano.
Desde la terminal
# Lanzar con un subagente concreto
claude --agent revisor
# Ver, monitorizar y gestionar subagentes en paralelo
claude agentsNo confundas tres mecanismos
| Mecanismo | Úsalo cuando | Contexto |
|---|---|---|
| Subagente aislado | Investigar o revisar sin llenar el hilo principal | Propio y acotado |
subagent_type: "fork" | Necesita el historial completo para continuar una rama | Hereda conversación y prompt cache |
/fork | Quieres otra sesión visible que continúe en paralelo | Copia la conversación a una sesión de background |
Crear uno sin saber YAML
Subagentes en paralelo (ejemplo real)
tools de cada subagente a lo mínimo. Un revisor solo necesita leer (Read, Grep); no le des permiso para editar o ejecutar comandos si no hace falta.Fuentes oficiales
Mapa completo de AulafyConsulta cómo encaja esta lección sin salir de tu ruta.
Mapa completo de Aulafy
Cómo se relacionan todos los cursos
No es una lista que debas completar. Empieza por la base, elige un resultado y profundiza solo cuando tu proyecto necesite más control.
- 1Comprender
- 2Aplicar o construir
- 3Operar con confianza
Empieza aquí
Crea una base común: qué puede hacer la IA, cómo pedir resultados y cómo comprobarlos antes de especializarte.
Desde esta base puedes aplicar la IA a una tarea o aprender a construir con código.
Elige una aplicación
Convierte la base en un resultado visible: una web, una mejora de negocio, contenido o una experiencia interactiva.
Si necesitas mantener código, datos o infraestructura, continúa por la rama técnica.
Construye con código
Prepara el entorno, trabaja con agentes de programación y aprende a ejecutar modelos con control sobre tus proyectos.
Esta rama prepara los conocimientos necesarios para diseñar y operar sistemas de IA fiables.
Lleva sistemas a producción
Combina recuperación, agentes, evaluación, seguridad, despliegue y adaptación de modelos cuando el problema lo exija.
No es obligatorio completarlo todo: elige solo la pieza que tu sistema necesita y vuelve al mapa cuando crezca.