Módulo 6: Subagents: delegar trabajo a agentes especializados

Módulo 6: Subagents — delegar trabajo a agentes especializados

Descripción

Ya sabes cómo trabajar con Claude Code: dominas el workflow Explore → Plan → Code, tienes CLAUDE.md configurado, y has creado skills y hooks que automatizan tu workflow. Hasta ahora, has interactuado con un solo agente — el agente principal de Claude Code que ejecuta tus instrucciones directamente. Ahora viene el salto: ¿qué pasa cuando un solo agente no es suficiente?

Este módulo enseña el sistema de subagents de Claude Code — la capacidad de delegar trabajo a agentes especializados que operan en paralelo o secuencialmente, cada uno optimizado para un tipo de tarea específico. Aprenderás a usar los subagents built-in (Explore, Plan, General-purpose, statusline-setup, claude-code-guide), a crear custom subagents para tareas de tu proyecto, a aprovechar el Plugin Marketplace oficial (más de 100 plugins instalables con un solo comando /plugin), y a entender el modelo emergente de Agent Teams para orquestación multi-agente.

Los subagents son la feature más diferenciadora de Claude Code. Ningún otro agente de código permite este nivel de delegación y especialización. Dominar subagents es lo que separa a un usuario competente de un usuario avanzado.

Dónde estamos en la guía

Módulo 01: Qué es Claude Code ✅
Módulo 02: Instalación y setup ✅
Módulo 03: CLAUDE.md y memoria ✅
Módulo 04: Workflow agentic ✅
Módulo 05: Skills y Hooks ✅
Módulo 06: Subagents ← ESTÁS AQUÍ
Módulo 07: Integraciones (Git, SDK, Remote Control)
Módulo 08: Proyecto integrador

En los módulos anteriores configuraste Claude Code (02-03), aprendiste a trabajar con él (04), y lo personalizaste (05). Ahora pasamos de personalizar a escalar. Este módulo te enseña a multiplicar la capacidad de Claude Code delegando trabajo a agentes especializados.

El mental model: un equipo, no un individuo

Hasta ahora has trabajado con Claude Code como un solo desarrollador: le das una instrucción, la ejecuta, te devuelve el resultado. Es efectivo, pero tiene limitaciones. Un solo agente tiene un solo context window, procesa una tarea a la vez, y mezcla análisis con implementación.

Los subagents cambian el modelo mental:

┌──────────────────────────────────────────────────────────────┐
│                    SIN SUBAGENTS                              │
│                                                              │
│  Tú ──▶ Claude Code ──▶ analiza ──▶ planifica ──▶ implementa │
│                    (todo en secuencia, un solo contexto)      │
│                                                              │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                    CON SUBAGENTS                              │
│                                                              │
│                 ┌──▶ Explore subagent (analiza archivos)     │
│                 │                                            │
│  Tú ──▶ Claude │──▶ Plan subagent (diseña solución)         │
│         (lead)  │                                            │
│                 └──▶ General subagent (implementa tarea)     │
│                                                              │
│            (paralelo, contextos separados, especialización)  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Piensa en un tech lead que coordina un equipo. El tech lead no escribe todo el código — delega: "tú analiza los tests, tú implementa el endpoint, tú revisa la documentación". Cada persona se enfoca en su tarea, y el tech lead integra los resultados. Eso es exactamente lo que hace Claude Code con subagents.

La analogía precisa

Concepto de equipo	Concepto en Claude Code	Función
Tech lead	Agente principal (parent)	Orquesta, delega, integra resultados
Analista	Explore subagent	Lee y analiza, no modifica
Arquitecto	Plan subagent	Diseña soluciones sin ejecutar
Developer	General-purpose subagent	Ejecuta tareas completas
Asistente	statusline-setup	Configura ajustes de interfaz
Documentador	claude-code-guide	Responde sobre features de Claude Code

Por qué el modelo multi-agente es superior

El modelo de un solo agente tiene tres problemas fundamentales que los subagents resuelven:

1. Context pollution (contaminación de contexto)

Cuando un agente analiza 50 archivos para entender la arquitectura y luego implementa un cambio pequeño, la información del análisis ocupa contexto que no necesita para la implementación. Con subagents, el Explore subagent consume su propio contexto para el análisis, devuelve un resumen compacto, y el agente principal usa ese resumen — sin cargar los 50 archivos completos.

2. Serialización innecesaria

Sin subagents, todo se ejecuta en secuencia: analizar, planificar, implementar. Con subagents, puedes paralelizar: mientras un subagent analiza los tests, otro analiza la documentación, y un tercero busca dependencias. Tres tareas que tomarían 3 minutos en secuencia toman 1 minuto en paralelo.

3. Falta de especialización

Un agente general que hace todo es como un fullstack developer que también hace DevOps, QA, y documentación. Funciona, pero no es óptimo. Los subagents están optimizados para su tarea: el Explore subagent tiene acceso read-only y es rápido para búsquedas; el Plan subagent diseña sin ejecutar; el claude-code-guide subagent se especializa en responder sobre la propia herramienta.

Por qué subagents importan ahora

La evolución del desarrollo con IA

2023: Un prompt, una respuesta (chatbot)
2024: Múltiples turns, un agente (agentic coding)
2025: Múltiples agentes, orquestación (multi-agent)
2026: Agent Teams, delegación autónoma (donde estamos)

Los subagents son el paso natural en la evolución del desarrollo asistido por IA. Pasamos de hablar con un chatbot a trabajar con un agente, y ahora a dirigir un equipo de agentes.

El impacto práctico

Sin subagents, una tarea como "refactoriza el módulo de autenticación" requiere que Claude Code:

Lea todos los archivos relacionados (consume contexto)
Entienda la arquitectura actual (más contexto)
Diseñe la nueva arquitectura (más contexto)
Implemente los cambios (el contexto ya está contaminado)
Ejecute tests (más contexto)

Con subagents:

Explore subagent → analiza y devuelve un resumen
Plan subagent → diseña usando el resumen
Agente principal → implementa con plan claro y contexto limpio
General-purpose subagent → ejecuta tests en paralelo

Menos contexto consumido, mejor calidad, mayor velocidad.

Objetivo del módulo

Al completar este módulo, serás capaz de:

✅ Usar los subagents built-in: Explore, Plan, General-purpose, statusline-setup, claude-code-guide
✅ Gestionar subagents con el comando /agents (interfaz interactiva) y el CLI claude agents
✅ Crear custom subagents con YAML frontmatter (tools, model, hooks, memory, initialPrompt, etc.)
✅ Habilitar memoria persistente en subagents (~/.claude/agent-memory/)
✅ Definir subagents inline vía flag --agents con JSON (útil para CI/CD)
✅ Entender los 5 scopes (Managed / CLI flag / Project / User / Plugin)
✅ Diferenciar subagent vs skill vs hook (cuándo usar cada uno)
✅ Instalar y gestionar plugins desde el Plugin Marketplace oficial con /plugin
✅ Decidir cuándo instalar un plugin de la comunidad vs construir lo tuyo
✅ Entender el modelo de Agent Teams y cuándo escalar a multi-agente
✅ Diseñar estrategias de delegación para tareas complejas

Prerequisitos

Conocimiento requerido:

✅ Módulo 05 completado (Skills y Hooks configurados)
✅ Módulo 04 completado (Workflow Explore → Plan → Code dominado)
✅ CLAUDE.md configurado en tu proyecto (Módulo 03)
✅ Claude Code instalado y funcionando (Módulo 02)

Para la práctica:

✅ Un proyecto real con al menos 15-20 archivos (para que los subagents tengan material)
✅ Familiaridad con el ciclo Explore → Plan → Code
✅ Al menos un skill creado en .claude/skills/

Verificación rápida:

Antes de continuar, verifica que puedes responder estas preguntas:

¿Cuáles son los tres modos de Claude Code y cuándo usas cada uno?
¿Qué diferencia hay entre un skill y una instrucción en CLAUDE.md?
¿Qué son los hooks y cuáles son los 5 eventos del ciclo de vida?

Respuestas

Explore (análisis read-only), Plan (diseño sin ejecución), Agent/Code (ejecución completa). El ciclo típico es Explore → Plan → Code, y puedes ir directo a Code para tareas simples.
CLAUDE.md se carga siempre al inicio de cada sesión (contexto general del proyecto). Un skill se carga bajo demanda con /nombre o automáticamente por Claude cuando detecta que su description matchea tu request. El formato actual es SKILL.md + YAML frontmatter dentro de un directorio.
Los hooks son scripts/comandos que se ejecutan automáticamente en 22+ eventos del ciclo de vida, incluyendo: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart/SessionEnd, PreCompact/PostCompact, SubagentStart/SubagentStop, Notification, Stop, y más. Soportan 4 handler types: command, http, prompt, agent. Se configuran en .claude/settings.json.

Si no estás listo:

Revisa primero:

Módulo 04: El workflow agentic
Módulo 05: Skills y Hooks

Roadmap del módulo

Este módulo tiene 5 cápsulas progresivas:

Cápsula 01 — Introducción al módulo (esta cápsula)

Contexto, mental model, y roadmap. Entiendes qué son los subagents, por qué importan, y cómo encajan en el ecosistema de Claude Code.

Cápsula 02 — Built-in subagents

Los subagents que Claude Code trae integrados: Explore, Plan, General-purpose, statusline-setup, claude-code-guide. Cómo funcionan, cuándo se activan, qué permisos tiene cada uno. Cuándo Claude los crea automáticamente vs cuándo pedirlos explícitamente.

Cápsula 03 — Custom subagents

Cómo crear tus propios agentes especializados en .claude/agents/. Estructura del archivo, configuración de herramientas y restricciones. La diferencia entre skills y subagents. Patterns para subagents de equipo.

Cápsula 04 — Plugin Marketplace

El marketplace oficial de Anthropic (más de 100 plugins) integrado en Claude Code. El comando /plugin, instalación y gestión, criterios para decidir entre instalar y construir, marketplaces alternativos, consideraciones de seguridad.

Cápsula 05 — Introducción a Agent Teams

El modelo emergente de Agent Teams (experimental/research preview). Team lead, teammates, task board, resolución de dependencias. Cuándo escalar de subagents a Agent Teams.

Mapa de progresión

Cápsula 01 (esta)     → Mental model y contexto
Cápsula 02            → Built-in subagents: los que ya tienes
Cápsula 03            → Custom subagents: los que tú creas
Cápsula 04            → Plugin Marketplace: los que la comunidad construyó
Cápsula 05            → Agent Teams: el futuro multi-agente

Dificultad: ⭐ ──────────────────────────────────▶ ⭐⭐⭐⭐

Las cápsulas 01-02 son fundamentales — entiendes y usas subagents built-in. La cápsula 03 es intermediate — creas subagents propios. La cápsula 04 es práctica — instalas capacidades pre-construidas del marketplace. La cápsula 05 es advanced/exploratory — introduce el modelo de Agent Teams que aún está en preview.

Qué construirás en este módulo

A lo largo de las 5 cápsulas, aprenderás a:

Usar Explore subagent para analizar tu codebase antes de implementar
Usar Plan subagent para diseñar soluciones arquitectónicas
Delegar tareas paralelas a múltiples subagents
Crear un custom subagent para una tarea repetitiva de tu proyecto
Instalar plugins del marketplace oficial para sumar capacidades sin construirlas
Entender Agent Teams y cuándo tiene sentido escalar a multi-agente

Al final del módulo, sabrás cuándo y cómo delegar trabajo, creando un workflow donde Claude Code multiplica su capacidad sin multiplicar la complejidad.

Un vistazo al módulo completo

Para que visualices cómo se integran los conceptos, aquí tienes un escenario real:

La sesión sin subagents

Tú: Refactoriza el módulo de usuarios. Separa la lógica de 
    negocio del acceso a datos.

Claude Code (solo):
  → Lee 15 archivos del módulo de usuarios (ocupa ~30% del contexto)
  → Analiza la estructura actual (más contexto)
  → Piensa en la nueva arquitectura (más contexto)
  → Empieza a implementar... pero ya consumió 60% del contexto
  → Resultado: implementación incompleta, tiene que comprimir
  → Pierde detalles en la compresión, introduce inconsistencias
  
Total: 8 minutos, calidad inconsistente, 2 iteraciones correctivas

La sesión con subagents

Tú: Refactoriza el módulo de usuarios. Separa la lógica de 
    negocio del acceso a datos.

Claude Code (como lead):
  → Lanza Explore subagent: "Analiza la estructura del módulo
    de usuarios, identifica qué es lógica de negocio y qué es 
    acceso a datos"
  → Explore devuelve: resumen de 20 líneas con la clasificación
  
  → Lanza Plan subagent: "Con este análisis, diseña la 
    separación en capas: services y repositories"
  → Plan devuelve: plan de 5 pasos con archivos a crear/mover
  
  → Claude Code implementa con contexto limpio y plan claro
  → Lanza General-purpose subagent: "Ejecuta npm test -- --related users"
  → Tests pasan
  
Total: 4 minutos, calidad consistente, 0 iteraciones correctivas

Esa es la diferencia. No es solo velocidad — es calidad de output, porque cada agente opera con un contexto limpio y especializado.

Cómo se integra con lo que ya sabes

Subagents y el workflow Explore → Plan → Code (Módulo 04)

Los modos Explore y Plan que aprendiste en el Módulo 04 son, internamente, subagents. Cuando cambias a modo Explore, Claude Code está usando un subagent especializado en lectura. Cuando usas /plan, usa un subagent de planificación. Ya los has usado — este módulo te enseña a hacerlo conscientemente y a crear los tuyos.

Subagents y CLAUDE.md (Módulo 03)

Los subagents heredan el contexto del proyecto. Cuando un Explore subagent analiza tu codebase, tiene acceso a las convenciones definidas en CLAUDE.md. Cuando creas un custom subagent, puedes referenciarlo en CLAUDE.md para que el agente principal sepa que existe.

Subagents y Skills/Hooks (Módulo 05)

Skills y subagents son mecanismos complementarios pero distintos:

Mecanismo	Qué es	Cuándo usarlo
Skill	Instrucciones en markdown que Claude lee	Tareas simples y repetitivas (crear componente, escribir test)
Subagent	Agente separado con su propio contexto	Tareas complejas que requieren especialización o paralelización
Hook	Script automático en eventos del ciclo de vida	Validaciones y automatizaciones (lint, format, test)

La regla: si la tarea se resuelve con instrucciones texto → skill. Si necesita un agente dedicado con su propio razonamiento → subagent. Si debe ejecutarse automáticamente → hook.

Conceptos clave que verás

Parent-child model

El agente principal (parent) crea subagents (children). El parent delega, los children ejecutan, y los children devuelven resultados al parent. El parent integra y decide qué hacer después.

Parent (agente principal)
├── Decide qué delegar y a quién
├── Recibe resultados resumidos
└── Integra todo en una respuesta coherente

Children (subagents)
├── Reciben una instrucción específica
├── Trabajan en su propio contexto
└── Devuelven resultado compacto al parent

Context isolation

Cada subagent tiene su propio contexto. No comparten el context window del parent. Esto es una feature, no un bug — evita la contaminación de contexto que degrada la calidad.

Ejemplo concreto: si un Explore subagent lee 30 archivos para analizar tu codebase, esos 30 archivos NO se cargan en el context del parent. El parent solo recibe el resumen de 20 líneas que el subagent produce. Resultado: el parent mantiene su contexto limpio para la implementación.

Tool restrictions

No todos los subagents tienen las mismas herramientas. El Explore subagent solo puede leer y buscar. El Plan subagent diseña sin ejecutar. Esto es intencional — las restricciones hacen a los subagents más seguros y predecibles.

Subagent	Read	Write/Edit	Execute	Search
Explore	✅	❌	❌	✅
Plan	✅	❌	❌	✅
General-purpose	✅	✅	✅	✅
statusline-setup	✅	✅	❌	❌
claude-code-guide	✅	❌	❌	✅

Automatic vs explicit

Claude Code crea subagents automáticamente cuando detecta que una tarea se beneficiaría de la delegación. Pero también puedes pedirlos explícitamente. Saber cuándo intervenir y cuándo dejar que Claude decida es una habilidad que desarrollarás en este módulo.

Señales de que Claude Code usará un subagent automáticamente:

Le pides analizar muchos archivos (→ Explore subagent)
Usas /plan (→ Plan subagent)
La tarea tiene componentes independientes paralelizables
Le pides ejecutar comandos mientras trabaja en otra cosa

Conexión con el proyecto integrador

En el Módulo 08, construirás una herramienta CLI completa con Claude Code. Los subagents serán parte integral de tu workflow:

Explore subagent para analizar el template inicial y entender la estructura
Plan subagent para diseñar la arquitectura de comandos
Custom subagent (opcional) para tareas repetitivas del proyecto (ej. agregar un nuevo comando con toda la boilerplate)
Delegación consciente para mantener el contexto limpio durante sesiones largas

Dominar subagents no solo acelera tu trabajo en el proyecto integrador — te prepara para workflows profesionales donde la delegación a agentes es la norma.

Versiones y compatibilidad

Este módulo cubre:

Claude Code 2.0+
Opus 5 (1M token context window)
Sonnet 5 (1M token context window)

Features cubiertos:

✅ Subagents built-in: Explore, Plan, General-purpose, statusline-setup, claude-code-guide
✅ Custom subagents en .claude/agents/
✅ Plugin Marketplace oficial (/plugin) con más de 100 plugins curados
✅ Parent-child orchestration
✅ Automatic subagent creation
⚠️ Agent Teams (research preview, experimental)

Nota sobre cambios:

Los subagents built-in son parte fundamental de la arquitectura de Claude Code — los conceptos son estables. Los custom subagents son una feature más reciente y puede tener ajustes en la API. Agent Teams está en research preview y puede cambiar significativamente. Siempre consulta la documentación oficial para verificar la sintaxis actual.

Resumen

Este módulo es donde Claude Code deja de ser un solo agente y se convierte en un equipo de agentes que tú diriges.

Lo que aprendiste en esta cápsula:

Los subagents permiten delegar trabajo a agentes especializados
El modelo mental es "tech lead + equipo", no "un solo developer"
Los subagents resuelven tres problemas: context pollution, serialización, falta de especialización
Hay subagents built-in (Explore, Plan, General-purpose, statusline-setup, claude-code-guide) y custom subagents que tú creas
El Plugin Marketplace oficial (/plugin) te da acceso a más de 100 capacidades pre-construidas instalables con un comando
Skills, subagents y hooks son mecanismos complementarios con propósitos distintos
Agent Teams es el siguiente paso evolutivo (experimental)

Siguiente cápsula: 02 - Built-in subagents — cómo funcionan Explore, Plan, General-purpose, statusline-setup y claude-code-guide, cuándo se activan, y cómo usarlos efectivamente.

Recursos adicionales

Documentación oficial

Sub-agents — Arquitectura y tipos de subagents en Claude Code
Best Practices — Workflows recomendados incluyendo delegación
Claude Code Overview — Capabilities y arquitectura general

Subagents y orchestration

Plugins Reference — Skills, agents, hooks, MCP bundled
Interactive Mode — Permisos y task management

Complementarios

Memory — Cómo CLAUDE.md interactúa con subagents
CLI Reference — Todos los comandos y slash commands

← AnteriorPermission System: Control de acceso en Claude Code Siguiente →Built-in Subagents: los agentes especializados de Claude Code