Módulo 6: Subagents: delegar trabajo a agentes especializados
Built-in Subagents: los agentes especializados de Claude Code
Built-in Subagents: los agentes especializados de Claude Code
Descripción
Claude Code no es un solo agente — es un agente principal que puede crear agentes hijos especializados para delegar trabajo. Estos subagents built-in vienen integrados y no requieren configuración: general-purpose (ejecución completa de subtareas), Explore (análisis read-only), Plan (diseño sin ejecución), statusline-setup (configuración de status line), y claude-code-guide (documentación de Claude Code).
Cada subagent tiene un perfil distinto: herramientas permitidas, velocidad, profundidad de análisis, y tipo de output. Saber cuándo usar cada uno — y cuándo dejar que Claude Code los active automáticamente — es la diferencia entre desperdiciar context window y usarlo quirúrgicamente.
Esta cápsula cubre los 5 subagents built-in en profundidad: qué hacen, cómo funcionan internamente, cuándo se activan, y cómo pedirlos explícitamente. Con ejemplos prácticos que puedes replicar en tu proyecto.
Qué es un subagent
Un subagent es una instancia ligera de agente que Claude Code crea para manejar una subtarea. No es un proceso separado ni un servidor externo — es un agente que opera dentro de la misma sesión de Claude Code pero con su propio contexto y restricciones.
Anatomía de un subagent
┌──────────────────────────────────────────────────────────┐
│ AGENTE PRINCIPAL (Parent) │
│ │
│ Context window: [tu conversación + proyecto] │
│ Tools: Read, Write, Execute, Search, Glob, etc. │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ SUBAGENT (Child) │ │
│ │ │ │
│ │ Context propio: [instrucción + archivos leídos] │ │
│ │ Tools: [subset del parent] │ │
│ │ Output: resultado compacto → devuelto al parent │ │
│ └────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────┘
Características comunes de todos los subagents
- Context aislado: Cada subagent tiene su propio context window. No comparte el contexto del parent directamente — recibe una instrucción y trabaja con ella.
- Tools restringidas: Los subagents tienen un subset de las herramientas del parent. Un Explore subagent no puede escribir archivos. Un statusline-setup subagent solo puede leer y editar.
- Output compacto: El subagent devuelve un resultado resumido al parent. El parent no recibe todo lo que el subagent leyó — recibe la conclusión.
- Lifecycle efímero: Los subagents se crean para una tarea, la ejecutan, devuelven el resultado, y se destruyen. No persisten entre invocaciones.
- Proyecto compartido: Aunque el contexto es aislado, los subagents operan sobre el mismo proyecto. Si un subagent escribe un archivo, el parent lo verá.
Context de subagents
Cada subagent recibe su propia ventana de contexto. Esto significa:
- Los subagents NO comparten contexto con el agente principal
- Debes incluir toda la información relevante en el prompt del subagent
- El resultado del subagent se devuelve como un mensaje al agente principal
- El agente principal NO ve las herramientas intermedias que usó el subagent
Los 5 subagents built-in
1. Explore subagent
El Explore subagent es un agente read-only optimizado para análisis de código. Su propósito es leer, buscar, entender — sin modificar nada.
Perfil técnico
| Propiedad | Valor |
|---|---|
| Modo | Read-only |
| Tools disponibles | Glob, Grep, Read (NO Edit, Write, ni Agent) |
| Tools NO disponibles | Edit, Write, Bash, Agent |
| Velocidad | Rápido (modelo optimizado para lectura) |
| Cuándo se activa | Análisis de codebase, búsqueda de patterns, comprensión de arquitectura |
Qué puede hacer
- Leer archivos del proyecto
- Buscar patterns en el código (grep, búsqueda semántica)
- Analizar la estructura de directorios
- Identificar dependencias entre módulos
- Mapear la arquitectura del proyecto
Qué NO puede hacer
- Escribir o modificar archivos
- Ejecutar comandos en terminal
- Instalar dependencias
- Crear archivos nuevos
Ejemplo básico
Tú: Analiza todos los archivos de test del proyecto. ¿Qué
framework se usa? ¿Cuál es la convención de nombres?
¿Hay tests unitarios e integración separados?
Claude Code crea automáticamente un Explore subagent que:
- Busca archivos
*.test.*,*.spec.*,__tests__/ - Lee samples de tests para identificar el framework
- Analiza la estructura de directorios de tests
- Devuelve al parent un resumen como:
Resumen del Explore subagent:
- Framework: Vitest (vitest.config.ts encontrado)
- Naming: [name].test.ts para unitarios, [name].integration.test.ts para integración
- Estructura: tests unitarios coubicados con los módulos, tests de integración en __tests__/integration/
- Cobertura: 47 archivos de test, 12 módulos sin tests
- Patterns: describe/it con factories en __tests__/factories/
El parent recibe este resumen compacto — no los 47 archivos completos. Esa es la eficiencia del modelo.
Ejemplo intermedio
Tú: Antes de refactorizar el módulo de autenticación, necesito
entender todas las dependencias. ¿Qué otros módulos importan
desde auth/? ¿Qué interfaces expone?
Explore subagent analiza:
- Todos los imports que referencian
auth/ - Las interfaces y tipos exportados desde
auth/ - Los módulos que dependen transitivamente
- Devuelve un grafo de dependencias en texto
Dependencias de auth/:
├── auth/index.ts exporta: AuthService, AuthMiddleware, UserSession (type)
├── Importado por:
│ ├── routes/api.ts → usa AuthMiddleware
│ ├── routes/admin.ts → usa AuthMiddleware, AuthService
│ ├── services/user.ts → usa AuthService, UserSession
│ ├── services/payment.ts → usa AuthService (solo verificación)
│ └── middleware/cors.ts → usa UserSession (type only)
└── Dependencias internas de auth/:
├── auth/jwt.ts → jsonwebtoken, config/secrets
├── auth/session.ts → redis, auth/jwt
└── auth/middleware.ts → auth/session, auth/jwt
Con este mapa, puedes refactorizar con confianza sabiendo exactamente qué se afecta.
2. Plan subagent
El Plan subagent diseña soluciones sin ejecutarlas. Es el modo /plan que ya conoces del Módulo 04, pero aquí lo entiendes como subagent.
Perfil técnico
| Propiedad | Valor |
|---|---|
| Modo | Read-only + razonamiento |
| Tools disponibles | Glob, Grep, Read (NO Edit, Write, ni Agent) |
| Tools NO disponibles | Edit, Write, Bash, Agent |
| Velocidad | Moderado (razonamiento profundo) |
| Cuándo se activa | Diseño de features, planificación de migraciones, decisiones de arquitectura |
Qué puede hacer
- Leer código existente para informar el plan
- Analizar trade-offs entre opciones
- Producir planes de implementación paso a paso
- Identificar riesgos y dependencias
- Proponer arquitectura sin implementarla
Qué NO puede hacer
- Escribir archivos
- Ejecutar comandos
- Implementar el plan que diseña
Ejemplo básico
Tú: /plan Diseña la migración de Express a Fastify.
No implementes nada todavía.
Plan subagent produce:
Plan de migración Express → Fastify
Fase 1: Preparación (sin romper nada)
1. Instalar fastify y @fastify/cors, @fastify/jwt
2. Crear fastify-app.ts paralelo a express-app.ts
3. Migrar config/server.ts para soportar ambos
Fase 2: Migración de rutas (una por una)
4. Crear adaptador de middleware Express → Fastify
5. Migrar rutas en orden: health → auth → users → products
6. Cada ruta: migrar + test + verificar
Fase 3: Migración de middleware
7. Reescribir auth middleware para Fastify hooks
8. Reescribir error handler como Fastify error handler
9. Reescribir validation (Joi → Fastify schema validation)
Fase 4: Cleanup
10. Eliminar express-app.ts y dependencias Express
11. Actualizar CI/CD config
12. Ejecutar suite completa de tests
Riesgos identificados:
- Middleware custom que usa req/res de Express directamente
- Tests de integración que importan app de Express
- 3 dependencias que dependen de Express types
Estimación: 4-6 sesiones de Claude Code
Ejemplo intermedio
Tú: /plan Tengo que agregar soporte para múltiples idiomas
en la app. Analiza qué opciones hay (i18next, react-intl,
custom) y recomienda una con justificación.
El Plan subagent lee la estructura del proyecto, analiza las dependencias existentes, y produce un plan con comparación de opciones, recomendación fundamentada, y pasos de implementación.
3. General-purpose subagent
El General-purpose subagent tiene capacidad de ejecución completa. Claude Code lo usa cuando necesita delegar una tarea que requiere leer, razonar, y potencialmente ejecutar acciones.
Perfil técnico
| Propiedad | Valor |
|---|---|
| Modo | Ejecución completa (con restricciones del parent) |
| Tools disponibles | TODAS las herramientas (Bash, Read, Write, Edit, Glob, Grep, Agent, etc.) |
| Velocidad | Variable (depende de la complejidad de la tarea) |
| Cuándo se activa | Tareas delegadas complejas, análisis profundo con razonamiento |
Qué puede hacer
- Todo lo que Explore puede (leer, buscar, analizar)
- Razonamiento profundo sobre problemas complejos
- Potencialmente escribir archivos (si el parent lo permite)
- Ejecutar secuencias de acciones para cumplir una tarea
Ejemplo básico
Tú: Busca todos los TODO comments en el proyecto, clasifícalos
por prioridad (critical, important, nice-to-have), y dame
un resumen.
Claude Code delega a un General-purpose subagent que:
- Busca todos los
TODO,FIXME,HACK,XXXen el proyecto - Lee el contexto de cada uno para clasificar
- Produce un informe organizado:
TODOs del proyecto (43 encontrados):
CRITICAL (5):
- src/auth/jwt.ts:45 TODO: tokens no se invalidan en logout
- src/db/migration.ts:12 FIXME: race condition en migración concurrente
- src/api/payment.ts:89 HACK: hardcoded API key (debe ir a env)
- ...
IMPORTANT (15):
- src/services/user.ts:23 TODO: agregar validación de email
- ...
NICE-TO-HAVE (23):
- src/utils/format.ts:7 TODO: soportar más formatos de fecha
- ...
Ejemplo intermedio
Tú: Necesito entender cómo fluyen los datos desde que un
usuario hace login hasta que recibe el dashboard.
Traza el flujo completo.
El General-purpose subagent sigue el flujo a través de múltiples archivos:
Flujo de login → dashboard:
1. POST /api/auth/login (routes/auth.ts:34)
→ Recibe { email, password }
→ Llama AuthService.login()
2. AuthService.login (services/auth.ts:67)
→ UserRepository.findByEmail()
→ bcrypt.compare(password, hash)
→ JWTService.createToken({ userId, role })
→ SessionStore.create(userId, token)
→ Return { token, refreshToken }
3. Redirect a /dashboard (client/router.tsx:23)
→ AuthGuard verifica token en localStorage
→ GET /api/dashboard (routes/dashboard.ts:12)
4. DashboardController.getData (controllers/dashboard.ts:8)
→ UserService.getProfile(userId from token)
→ StatsService.getUserStats(userId)
→ NotificationService.getUnread(userId)
→ Return { profile, stats, notifications }
5. Dashboard.tsx renderiza con los datos
4. statusline-setup subagent
El statusline-setup subagent se especializa en configurar los settings de la status line de Claude Code. Es un subagent muy enfocado con acceso limitado.
Perfil técnico
| Propiedad | Valor |
|---|---|
| Modo | Configuración |
| Tools disponibles | Read, Edit |
| Tools NO disponibles | Bash, Write, Glob, Grep, Agent |
| Velocidad | Rápido |
| Cuándo se activa | Cuando se necesita configurar o ajustar la status line |
Ejemplo
Claude Code activa este subagent internamente cuando necesita
ajustar la configuración de la status line. Es un subagent de
soporte interno — raramente lo invocas directamente.
5. claude-code-guide subagent
El claude-code-guide subagent es un agente de documentación que responde preguntas sobre las features de Claude Code: hooks, MCP, settings, integraciones con IDEs, y más.
Perfil técnico
| Propiedad | Valor |
|---|---|
| Modo | Consulta de documentación |
| Tools disponibles | Glob, Grep, Read, WebFetch, WebSearch |
| Tools NO disponibles | Bash, Write, Edit, Agent |
| Velocidad | Rápido |
| Cuándo se activa | Preguntas sobre cómo usar Claude Code, sus features, configuración |
Ejemplo
Tú: ¿Cómo configuro hooks en Claude Code?
Claude Code puede delegar a claude-code-guide, que busca en la
documentación oficial y devuelve una respuesta precisa sobre la
configuración de hooks.
Cuándo Claude Code crea subagents automáticamente
Claude Code no siempre espera que le pidas un subagent. En varios escenarios, los crea automáticamente:
Escenario 1: Tareas que requieren exploración amplia
Cuando le pides algo que requiere leer muchos archivos, Claude Code crea un Explore subagent en lugar de cargar todos los archivos en el context window principal:
Tú: ¿Cómo está organizado el módulo de pagos?
Claude Code detecta que necesita explorar el directorio payments/ con múltiples archivos y crea un Explore subagent. El subagent lee los archivos y devuelve un resumen, manteniendo el context principal limpio.
Escenario 2: Tareas paralelizables
Cuando una tarea tiene componentes independientes, Claude Code puede crear múltiples subagents en paralelo:
Tú: Analiza la calidad del código en los módulos de auth,
payments, y notifications.
Claude Code crea 3 Explore subagents en paralelo — uno por módulo. Cada uno analiza su módulo y devuelve resultados. El parent integra los 3 análisis en una respuesta coherente.
Escenario 3: Separación análisis-implementación
Cuando Claude Code necesita entender antes de implementar, usa un Explore subagent primero:
Tú: Agrega paginación al endpoint de productos.
Internamente:
- Explore subagent → analiza cómo están implementados los endpoints actuales
- Parent → usa el análisis para implementar la paginación de forma consistente
Cuándo NO se crean automáticamente
- Tareas triviales ("cambia el nombre de esta variable")
- Cuando el contexto ya tiene la información necesaria
- Preguntas directas que no requieren exploración
- Cuando el context window tiene suficiente espacio
Cómo pedir subagents explícitamente
No siempre necesitas esperar a que Claude Code decida. Puedes pedirlos directamente:
Pedir exploración explícita
Tú: Usa un subagent de exploración para analizar todos los
archivos de configuración del proyecto. Quiero saber qué
variables de entorno se usan y dónde.
Pedir plan explícito
Tú: /plan Antes de implementar, usa el modo plan para
diseñar la solución completa.
Pedir delegación explícita
Tú: Delega a subagents las siguientes tareas en paralelo:
1. Analizar los tests existentes
2. Buscar todos los endpoints sin validación
3. Verificar que todas las rutas tienen auth middleware
Keywords que activan subagents
Ciertas palabras en tus prompts hacen más probable que Claude Code use subagents:
| Keyword/frase | Subagent probable |
|---|---|
| "analiza", "explora", "investiga" | Explore |
| "diseña", "planifica", "propón" | Plan |
| "busca todos", "clasifica", "traza" | General-purpose |
| "ejecuta", "corre", "verifica" | General-purpose |
| "en paralelo", "simultáneamente" | Múltiples subagents |
Comparaciones y decisiones
¿Cuándo usar cada subagent?
┌──────────────────────────────────────────────────────────────┐
│ ÁRBOL DE DECISIÓN │
│ │
│ ¿Necesitas modificar archivos o ejecutar comandos? │
│ ├── NO → ¿Necesitas razonamiento profundo? │
│ │ ├── NO → EXPLORE subagent │
│ │ └── SÍ → PLAN subagent │
│ └── SÍ → ¿Es una subtarea delegable? │
│ ├── SÍ → GENERAL-PURPOSE subagent │
│ └── NO → Agente principal (no subagent) │
│ │
└──────────────────────────────────────────────────────────────┘
Explore vs General-purpose para análisis
| Criterio | Explore | General-purpose |
|---|---|---|
| Velocidad | Más rápido | Más lento |
| Profundidad | Búsqueda + lectura | Razonamiento + análisis |
| Output | Datos encontrados | Datos + interpretación |
| Uso de contexto | Eficiente | Mayor consumo |
| Ejemplo | "¿Qué archivos importan lodash?" | "¿Es seguro eliminar lodash del proyecto?" |
Regla: Si necesitas datos → Explore. Si necesitas análisis de datos → General-purpose.
Plan subagent vs dar instrucciones al parent
| Criterio | Plan subagent | Instrucción directa |
|---|---|---|
| Complejidad | Features complejos, migraciones | Cambios puntuales |
| Riesgo | Alto (afecta múltiples archivos) | Bajo (1-2 archivos) |
| Decisiones | Múltiples opciones con trade-offs | Solución obvia |
| Ejemplo | "Diseña el sistema de cache" | "Agrega cache a este endpoint" |
Regla: Si hay decisiones de diseño que tomar → Plan. Si la implementación es directa → instrucción al parent.
Patterns comunes
Pattern 1: Explore → Plan → Code (con subagents explícitos)
El workflow del Módulo 04, pero ahora consciente de que son subagents:
Paso 1 (Explore subagent):
Tú: Explora el módulo de notificaciones. ¿Qué tipos de
notificaciones hay? ¿Cómo se envían? ¿Hay cola o es
síncrono?
Paso 2 (Plan subagent):
Tú: /plan Con ese análisis, diseña el soporte para
notificaciones push. Dame opciones y trade-offs.
Paso 3 (Parent agent):
Tú: Implementa la opción 2 del plan. Empieza por el
servicio de push notifications.
Pattern 2: Análisis paralelo
Cuando necesitas analizar múltiples áreas independientes:
Tú: Analiza en paralelo:
1. La estructura de la base de datos (modelos, relaciones)
2. La cobertura de tests (qué módulos tienen tests, cuáles no)
3. Las dependencias externas (qué paquetes se usan, versiones)
Dame un resumen consolidado de los tres análisis.
Claude Code crea 3 subagents, los ejecuta concurrentemente, e integra los resultados.
Pattern 3: Delegación de subtarea
Cuando estás implementando algo complejo y necesitas que un subagent haga una parte:
Tú: Implementa el endpoint de búsqueda de productos.
Pero primero, delega a un subagent que analice cómo
están implementados los otros endpoints para mantener
consistencia.
Pattern 4: Verificación post-implementación
Después de implementar, usa subagents para verificar:
Tú: Acabas de implementar el módulo de cache. Ahora:
1. Usa un subagent para verificar que no rompiste ningún test
2. Usa otro para verificar que la implementación sigue
las convenciones del proyecto
Capacidades avanzadas de subagents
Aislamiento con worktrees
Los subagents pueden ejecutarse en un worktree aislado — una copia temporal del repositorio:
- Usa
isolation: "worktree"al lanzar el subagent - El subagent trabaja en una copia separada del repo
- Si no hace cambios, el worktree se limpia automáticamente
- Si hace cambios, se devuelve el path y branch del worktree
- Útil para: exploración destructiva, pruebas de refactoring, cambios experimentales
Continuar un subagent existente
Si necesitas seguir trabajando con un subagent que ya completó una tarea, puedes usar SendMessage con el ID o nombre del agente. El subagent se reanuda con todo su contexto preservado.
Esto es útil cuando el resultado del subagent necesita refinamiento o cuando quieres pedirle tareas adicionales sin empezar desde cero.
Ejecución en background
Los subagents pueden ejecutarse en segundo plano con run_in_background: true. Cuando un agente se ejecuta en background:
- Recibes notificación automática cuando completa
- NO necesitas hacer polling ni sleep
- Puedes seguir trabajando en otras cosas mientras el subagent trabaja
- Ideal para: tareas de investigación largas, búsquedas extensas, builds paralelos
Pitfalls y edge cases
Pitfall 1: Over-delegation
No todo necesita un subagent. Si la tarea es simple, un subagent agrega overhead sin beneficio:
❌ "Usa un subagent para leer el archivo package.json"
✅ "¿Qué versión de React usa el proyecto?" (Claude lee directamente)
Regla: Si la tarea requiere leer 1-3 archivos y no necesita razonamiento profundo, el parent puede hacerlo directamente.
Pitfall 2: Subagent sin contexto suficiente
Los subagents reciben una instrucción, pero no tu historial completo. Si tu instrucción depende de contexto previo, el subagent no lo tendrá:
❌ "Analiza el problema que mencioné antes"
✅ "Analiza el bug en src/auth/login.ts donde el token no
se invalida al hacer logout"
Regla: Haz que las instrucciones a subagents sean autocontenidas.
Pitfall 3: Esperar que subagents compartan estado
Los subagents no comparten contexto entre sí. Si creas 3 subagents en paralelo, cada uno opera de forma independiente:
❌ Esperar que el subagent 2 use información del subagent 1
✅ El parent integra resultados de los 3 subagents
Pitfall 4: Subagents para tareas que necesitan iteración
Los subagents son best-effort en una sola ejecución. Si la tarea requiere iteración (intentar algo, ver si funciona, ajustar), es mejor que lo haga el parent:
❌ "Delega a un subagent que debuggee el error de producción"
✅ Debuggear directamente con el parent, iterando
Edge case: Conflictos de escritura
Si dos subagents intentan escribir al mismo archivo (cosa que normalmente Claude Code no permite), hay un mecanismo de resolución: el parent serializa las escrituras.
Edge case: Subagent que falla
Si un subagent no puede completar la tarea (ej. no encuentra los archivos, la búsqueda no tiene resultados), devuelve el resultado parcial al parent. El parent decide si reintentar con instrucciones diferentes o manejar el caso manualmente.
Ejemplo completo integrado
Escenario: Agregar un nuevo módulo de reportes
Tienes un proyecto Node.js con Express y PostgreSQL. Necesitas agregar un módulo de reportes que genere informes de ventas.
Paso 1: Exploración
Tú: Antes de implementar el módulo de reportes, necesito
entender la estructura. Analiza:
1. Cómo están organizados los módulos existentes (structure)
2. Qué queries SQL se usan para acceder a ventas
3. Si hay algún endpoint que ya genere datos similares
Claude Code crea Explore subagents:
Resultado del análisis:
Estructura de módulos:
src/
├── controllers/ → un controller por dominio
├── services/ → lógica de negocio
├── repositories/ → acceso a datos (Knex)
├── routes/ → Express routers
└── types/ → interfaces TypeScript
Queries de ventas:
- repositories/sale.ts tiene findAll, findById, findByDateRange
- findByDateRange acepta {from, to} y retorna Sale[]
- No hay aggregations (SUM, COUNT, GROUP BY)
Endpoints similares:
- GET /api/sales/summary → retorna count y total del mes actual
- No hay reportes por rango de fecha ni por categoría
Paso 2: Planificación
Tú: /plan Con ese análisis, diseña el módulo de reportes.
Necesito reportes de ventas por rango de fecha, por
categoría, y un dashboard con métricas clave.
Plan subagent produce un plan detallado de 8 pasos.
Paso 3: Implementación con verificación
Tú: Implementa los pasos 1-3 del plan (repository, service,
types). Después de implementar, verifica que compila y que
los tests existentes siguen pasando.
Claude Code implementa y verifica:
tsc --noEmit && npm testResultado: compilación OK, 47/47 tests pasan.
Paso 4: Continuar implementación
Tú: Implementa los pasos 4-6 (controller, routes, validación).
Incluye tests para los nuevos endpoints.
El agente principal implementa, crea tests, y verifica: 52/52 tests.
Ejercicios prácticos
Ejercicio 1: Exploración dirigida
Abre Claude Code en tu proyecto y ejecuta:
Analiza la estructura de mi proyecto usando un subagent de
exploración. Quiero saber:
1. Cuántos archivos hay por tipo (ts, js, json, md)
2. Qué directorios son los más grandes
3. Si hay archivos que no pertenecen a ningún patrón claro
Qué esperar
Claude Code creará un Explore subagent que:
- Usará Glob para contar archivos por extensión
- Analizará la estructura de directorios
- Identificará archivos "huérfanos" que no siguen convenciones
El resultado debe ser un resumen estructurado con números concretos. Si Claude no crea un subagent explícitamente, aún usa internamente las herramientas de exploración — el resultado debe ser similar.
Ejercicio 2: Plan para una feature nueva
/plan Diseña cómo agregarías un sistema de caché a mi
proyecto. Evalúa las opciones: in-memory (node-cache),
Redis, o file-based. Recomienda una con justificación
basada en la estructura actual del proyecto.
Qué esperar
El Plan subagent debe:
- Leer la estructura del proyecto para entender el stack
- Evaluar las 3 opciones con pros/contras
- Recomendar una basada en el contexto real (ej. si ya usas Redis para sessions, recomendar Redis; si es un proyecto pequeño, recomendar in-memory)
- Producir un plan de implementación de 4-6 pasos
Si no explora tu proyecto antes de planificar, pídele que lo haga: "Primero analiza mi proyecto y luego planifica".
Ejercicio 3: Análisis paralelo
Analiza en paralelo estas tres áreas de mi proyecto:
1. Dependencias: qué paquetes se usan y si alguno está desactualizado
2. Tests: qué módulos tienen tests y cuáles no
3. Seguridad: ¿hay secrets hardcodeados, TODO de seguridad,
o dependencias vulnerables?
Dame un reporte consolidado.
Qué esperar
Claude Code debe crear múltiples subagents (o al menos paralelizar internamente). El resultado debe tener tres secciones claras con hallazgos específicos de tu proyecto. Si no paraleliza, los resultados serán secuenciales pero igualmente válidos.
Bonus: si Claude Code ejecuta npm audit como parte del análisis de seguridad, eso indica que usó un general-purpose subagent con acceso a Bash.
Ejercicio 4: Workflow Explore → Plan → Code completo
Elige una mejora pequeña para tu proyecto (ej. agregar validación a un endpoint, mejorar el manejo de errores). Ejecuta el ciclo completo conscientemente:
Paso 1: Explora cómo se maneja [X] actualmente en el proyecto.
Paso 2: /plan Diseña cómo mejorar [X].
Paso 3: Implementa el plan.
Paso 4: Verifica que todo compila y los tests pasan.
Qué esperar
Este ejercicio debería tomar 10-15 minutos. En cada paso, observa:
- ¿Claude Code creó un subagent? ¿De qué tipo?
- ¿El contexto del parent se mantuvo limpio?
- ¿El plan fue informado por la exploración?
El valor del ejercicio es experimentar el ciclo completo con consciencia de qué subagent opera en cada fase.
Ejercicio 5: Delegación explícita
Quiero que delegues a un subagent la siguiente tarea:
"Busca todas las funciones async en el proyecto que no
tienen manejo de errores (try/catch o .catch()). Lista
cada una con su archivo y línea."
Qué esperar
Claude Code debe crear un subagent que:
- Busque funciones
asyncen el proyecto - Analice cuáles tienen try/catch y cuáles no
- Devuelva una lista con ubicaciones
Este es un ejercicio de análisis estático simplificado. No esperes 100% de precisión — el análisis basado en búsqueda de texto no cubre todos los edge cases (ej. error handling en un wrapper superior).
Resumen
Los built-in subagents son el mecanismo principal de delegación en Claude Code. No necesitas configurar nada para usarlos — vienen integrados y Claude Code los activa según la tarea.
Lo que aprendiste en esta cápsula:
- Hay 5 subagents built-in: general-purpose (ejecución completa), Explore (read-only), Plan (diseño), statusline-setup (configuración), claude-code-guide (documentación)
- Cada subagent tiene tools restringidas y context aislado
- Claude Code crea subagents automáticamente cuando detecta tareas paralelizables o que requieren exploración amplia
- Puedes pedir subagents explícitamente con instrucciones directas
- Los subagents devuelven resultados compactos al parent, manteniendo el context window limpio
- El patrón principal es Explore → Plan → Code, ahora entendido como una secuencia de subagents
- No over-delegar: si la tarea es simple, el parent puede hacerla directamente
Siguiente cápsula: 03 - Custom subagents — cómo crear tus propios agentes especializados con instrucciones, herramientas y restricciones definidas por ti.
Recursos adicionales
Documentación oficial
- Sub-agents — Tipos, configuración y comportamiento de subagents
- Best Practices — Workflows y context management con subagents
- CLI Reference — Comandos y modos disponibles
Patterns y workflows
- Interactive Mode — Task management y delegación
- Plugins Reference — Skills, agents, hooks: cómo interactúan