📖 Glosario vivo
Términos centrales de esta ruta. Vuelve aquí siempre que lo necesites.
Qué son los subagentes
Imagínalo así: tú eres gerente de proyecto. En vez de hacerlo todo por tu cuenta, delegas tareas específicas a los miembros del equipo, cada uno con su propio espacio de trabajo. Cuando terminan, te entregan el resultado. Eso es exactamente lo que hacen los subagentes.
Hasta ahora usaste Claude Code como un único agente, conversando directamente con él. Pero Claude Code tiene una capacidad poderosa: puede lanzar otros agentes para ejecutar tareas en paralelo. Estos agentes secundarios se llaman subagentes.
Cada subagente recibe una instrucción específica, trabaja de forma independiente (con su propio contexto y herramientas) y devuelve el resultado al agente principal cuando termina. El agente principal no tiene que esperar a que un subagente termine para lanzar otro. Esto te permite multiplica la capacidad de trabajo de Claude Code sin aumentar la complejidad del contexto principal.
En 1 frase: los subagentes son instancias independientes de Claude Code que el agente principal inicia para realizar trabajo en paralelo.
La herramienta Task
A Task tool es el mecanismo que Claude Code usa internamente para crear subagentes. Cuando Claude decide que necesita delegar una tarea, invoca la herramienta Task y le pasa una descripción de lo que debe hacer el subagente. El subagente recibe esa instrucción, realiza el trabajo y devuelve el resultado textual al agente principal.
En la práctica, no necesitas llamar explícitamente a la herramienta Task. Basta con indicarle a Claude algo como "haz estas tres cosas en paralelo" o "crea un subagente para analizar las pruebas mientras refactorizas el código". Claude lo entiende y lo orquesta automáticamente. Lo importante es que cada Task crea un nuevo contexto, con su propio CLAUDE.md cargado, y no comparte el estado de la memoria con el padre.
Cómo funciona por dentro
1. El agente principal decide delegar e invoca Task(prompt="...")
2. El sistema crea una nueva sesión de Claude Code con el prompt proporcionado
3. El subagente ejecuta la tarea usando sus propias herramientas (Read, Edit, Bash...)
4. Al terminar, el resultado textual vuelve al padre como respuesta de la Task
5. El padre continúa su trabajo con esta información
En 1 frase: la herramienta Task crea un subagente con un prompt propio, lo ejecuta de forma aislada y devuelve el resultado al agente principal.
Tipos de agente disponibles
No todos los subagentes necesitan permisos completos. Claude Code permite iniciar agentes con distintos niveles de acceso, siguiendo el principio de mínimo privilegio: dar solo los permisos necesarios para la tarea. Esto reduce el riesgo y evita que un subagente cambie algo que no debía.
Solo lectura
Solo lee archivos y analiza. No edita nada. Ideal para: análisis de codebase, búsqueda de patrones, auditoría.
Acceso completo
Lee, edita archivos y ejecuta comandos. El estándar para tareas que necesitan modificar el código.
Background
Se ejecuta en segundo plano mientras el proceso principal continúa. Ideal para tareas largas como builds o suites de pruebas.
En 1 frase: elige el tipo de agente según el nivel de permisos que necesites: lectura, escritura completa o ejecución en segundo plano.
Comunicación entre padre e hijo
La comunicación entre padre e hijo sigue un modelo simple: el padre envía una instrucción (el prompt de Task) y el hijo devuelve un resultado textual. No hay estado compartido en memoria entre ellos. Si el hijo necesita información del codebase, la busca por su cuenta usando sus herramientas.
El punto clave: el prompt de Task debe ser completo y autocontenido. El subagente no tiene acceso al historial de conversación del agente padre. Si quieres que siga un estándar específico, inclúyelo en el prompt. Piensa como si estuvieras escribiendo una instrucción para un colega que acaba de llegar al proyecto.
Error común
Suponer que el subagente "sabe" lo que el agente padre discutió antes. El subagente empieza desde cero. Si la información es crítica, pásala explícitamente en el prompt de la Task.
En 1 frase: el padre envía una instrucción, el hijo devuelve texto; no hay memoria compartida entre ellos.
Aislamiento y worktrees
Cuando dos agentes editan los mismos archivos al mismo tiempo, surgen conflictos. La solución es el aislamiento vía worktrees. Un git worktree es un directorio de trabajo adicional vinculado al mismo repositorio, cada uno con su propia rama. Cada subagente trabaja en su propio worktree, sin interferir con el espacio de los demás.
Claude Code puede crear worktrees automáticamente al iniciar subagentes. Al final, las ramas de los worktrees se fusionan de vuelta en la rama principal. Es como si cada miembro del equipo tuviera su propia copia del proyecto para trabajar y luego juntaran todo.
En 1 frase: los worktrees dan a cada subagente su propio espacio de trabajo aislado y evitan conflictos entre archivos.
Cuándo usarlo y cuándo no
Los subagentes no son gratis. Cada uno consume tokens para cargar el contexto (CLAUDE.md, herramientas, etc.) y tiene un costo adicional de inicialización. Para tareas simples que el agente principal resuelve en segundos, lanzar un subagente es un desperdicio. La regla práctica: usa subagentes cuando la tarea es independiente, sustancial (más de 30 segundos de trabajo) y paralelizable.
Usa subagentes cuando
- - Las tareas son independientes entre sí
- - Cada tarea tarda más de 30 segundos
- - Quieres proteger el contexto del padre
- - Necesitas editar archivos diferentes en paralelo
- - Quieres especializar agentes (pruebas vs. docs vs. lint)
No uses subagentes cuando
- - La tarea es trivial (renombrar una variable)
- - Las tareas dependen del resultado de la otra
- - El contexto ya está casi al límite
- - Necesitas interacción en tiempo real
- - El costo en tokens no se justifica
En 1 frase: los subagentes son útiles para tareas independientes y sustanciales; no para todo.
🧾 Resumen del módulo
Siguiente módulo:
4.2 — Paralelismo real: lanza varios agentes y recopila resultados en la práctica.