Subagentes: trabajadores especializados

Módulo: 8. Un ejército de agentes | Tiempo: ~30 min de teoría + 45 min de práctica

Lo esencial

Eres el director de una empresa. Cuando hace falta una auditoría legal, no estudias derecho tú mismo. Contratas a un abogado, le explicas la tarea, él trabaja en su oficina y te trae el resultado. No viste lo que hizo por dentro: solo necesitas el resultado final. Un subagente funciona exactamente igual: el agente principal contrata a un especialista, este trabaja en su propio contexto y devuelve un resultado resumido.

Conceptos clave

• Subagente = un agente aparte con contexto independiente (su propia ventana de contexto)
• 5 razones para usarlos: contexto, herramientas, reutilización, especialización, costo
• Subagentes integrados: Explore (solo lectura), Plan (solo lectura), General-purpose (todas las herramientas)
• Formato del archivo: Markdown con frontmatter YAML en .claude/agents/<name>.md
• Crear un subagente personalizado: pedírselo a Claude o escribir el archivo a mano (el asistente /agents de versiones anteriores se eliminó)
• Ámbitos: proyecto (.claude/agents/), usuario (~/.claude/agents/), CLI, managed, plugin
• Configuración: 18 campos de frontmatter (rol, herramientas, modelo, hooks, memoria, color y más)
• El anidamiento está limitado: por defecto los subagentes pueden llamar a otros, pero no más allá de tres niveles
• Cuándo NO usar subagentes

Teoría

Qué es un subagente, técnicamente

🎨 Imagínalo así: un subagente es como un abogado externo. Eres el director, necesitas una opinión legal y no vas a aprender derecho. Contratas a un abogado, le explicas la tarea, él trabaja en su oficina y te trae el resultado listo. Tu escritorio queda limpio.

Según la documentación oficial de Anthropic: los subagentes son asistentes de IA especializados que se encargan de ciertos tipos de tareas. Cada subagente trabaja en su propia ventana de contexto, con un prompt del sistema personalizado, acceso limitado a herramientas y permisos independientes.

Usa un subagente cuando una tarea secundaria vaya a ensuciar la conversación principal con resultados de búsqueda, logs o contenido de archivos que ya no vas a usar. El subagente hace el trabajo en su contexto y devuelve solo un resumen.

Crea un subagente personalizado cuando lanzas una y otra vez al mismo trabajador con las mismas instrucciones.

Cuando el agente principal llama a un subagente, se crea una instancia aparte de Claude con el contexto limpio. Esa instancia:

• Recibe una tarea concreta y un prompt del sistema personalizado (NO el prompt del sistema completo de Claude Code)
• Trabaja de forma independiente: no ve el historial de la sesión principal (la excepción es fork, ver abajo)
• Solo tiene acceso a las herramientas permitidas
• Al terminar, devuelve el resultado al agente principal y "muere"
• Su contexto se libera

Agente principal (contexto acumulado: 30K tokens)
│
├── Llama al subagente "researcher"
│   ├── El subagente recibe: la tarea + los datos necesarios
│   ├── Trabaja con el contexto limpio (0 + tarea = ~2K tokens)
│   ├── Reúne información, analiza
│   └── Devuelve: un resumen comprimido (500 tokens) → muere
│
El agente principal sigue con el resumen
(30K + 500 = 30.5K, no 30K + todo el trabajo del subagente)

🎨 Imagínalo así: el subagente quema su contexto como un vaso desechable: hizo la tarea y a la basura. El agente principal recibe solo el destilado: un párrafo en lugar de 50 páginas de logs.

Sin subagentes, cada acción se suma al contexto principal. Después de 2 horas de trabajo, el contexto está saturado y el modelo empieza a "olvidar" las primeras partes de la conversación.

Sobre el anidamiento: en las primeras versiones, los subagentes no podían llamar a otros subagentes. Ahora pueden, pero no más allá de tres niveles por debajo de la conversación principal (el límite se ajusta con la variable CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH). Para empezar, es más fácil mantener la cadena plana: llama a los subagentes uno tras otro desde la conversación principal, así es más fácil entender quién hizo qué.

5 razones para usar subagentes

Razón 1: cuidar el contexto

Reunir 50 páginas de datos en el agente principal = 50 páginas en el contexto para siempre. Delégalo a un subagente → las reúne, las comprime en un resumen de 1 página → te lo devuelve. El contexto del agente principal queda limpio.

Razón 2: limitar las herramientas

🎨 Imagínalo así: el principio de mínimo privilegio es como el cirujano y el camillero. El camillero lleva los instrumentos, pero no le dan el bisturí. El researcher lee, pero no escribe: no va a romper lo que no debe tocar.

El subagente "investigador" solo tiene acceso a la búsqueda web y a leer archivos. El subagente "programador" tiene acceso a bash y a editar archivos. El agente principal lo tiene todo.

¿Por qué importa? Un subagente no puede borrar un archivo por accidente si no tiene acceso a bash. Principio de mínimo privilegio.

Razón 3: reutilización

Creas el subagente "competitor-researcher" una vez → lo usas en 10 proyectos distintos. No tienes que describir cada vez cómo hacer un análisis de competencia.

Razón 4: especialización

Un agente enfocado en una sola tarea la hace mejor que un agente universal. Un "researcher" con un prompt especial para buscar información → mejor que un agente "hazlo todo" que intenta buscar, analizar y escribir al mismo tiempo.

Razón 5: control de costos

🎨 Imagínalo así: no contrates a un chef para pelar papas. Haiku para el trabajo mecánico (reunir datos, dar formato), Opus solo para la estrategia. La diferencia de precio entre Haiku y Opus es de varias veces, y hasta el modelo más potente, de un orden de magnitud.

Tareas distintas requieren modelos distintos:

Reunir datos (trabajo mecánico) → Claude Haiku ($1 entrada / $5 salida por 1 millón de tokens)
Analizar datos (requiere razonamiento) → Claude Sonnet ($2 / $10)
Decisiones estratégicas → Claude Opus ($4 / $20)

Precios de la API a octubre de 2026. Precios y versiones vigentes: Lo vigente. Si eliges el modelo correcto para cada tarea, ahorras varias veces en las tareas mecánicas.

Subagentes integrados de Claude Code

Claude Code trae varios subagentes integrados. Cada uno hereda los permisos de la sesión principal con restricciones adicionales de herramientas. El modelo de los agentes integrados depende de la versión y de la configuración; revisa lo vigente en la documentación:

Explore: búsqueda rápida de solo lectura en el código

• Modelo: por defecto el de la sesión principal, se puede cambiar
• Herramientas: solo lectura (Write y Edit prohibidos)
• Para qué: buscar archivos, navegar el código, analizar la estructura del proyecto
• Al llamarlo, Claude indica el nivel de detalle: quick (búsqueda puntual), medium (equilibrio), very thorough (análisis completo)

Plan: investigador para el modo de planificación

• Modelo: lo hereda de la sesión principal
• Herramientas: solo lectura (Write y Edit prohibidos)
• Para qué: reunir contexto antes de armar un plan
• Se usa cuando estás en plan mode y Claude necesita entender el código

General-purpose: universal para tareas complejas

• Modelo: lo hereda de la sesión principal
• Herramientas: todas las disponibles
• Para qué: investigaciones complejas, operaciones de varios pasos, modificar código

Auxiliares:

Estos subagentes se activan automáticamente cuando el agente principal decide que la tarea es buena para delegar.

Formato del archivo de un subagente (oficial)

Los subagentes se definen como archivos Markdown con frontmatter YAML. Es el formato oficial de Anthropic:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Estructura: frontmatter YAML (ajustes) + cuerpo en Markdown (el prompt del sistema del subagente). El subagente recibe este prompt del sistema, la tarea del agente principal, el CLAUDE.md del proyecto y una instantánea del git status, pero NO el prompt del sistema completo de Claude Code ni el historial de la conversación.

Todos los campos del frontmatter YAML (18 campos)

Dónde guardar los subagentes (ámbitos)

Los de proyecto (.claude/agents/): para el equipo, súbelos a git. Los de usuario (~/.claude/agents/): personales, disponibles en todas partes.

Si hay un conflicto de nombres, gana la prioridad más alta.

Crear un subagente: tres formas

Forma 1: pedírselo a Claude (recomendada)

En las versiones anteriores había un asistente /agents para esto. Desde la versión 2.1.198 se eliminó: el comando /agents ahora solo recuerda qué hacer. Los subagentes se crean pidiéndoselo a Claude:

Crea un subagente personal market-researcher en ~/.claude/agents/:
investiga mercados y competidores, solo lee archivos y busca en la web,
modelo haiku, color green

Claude escribirá el archivo con el frontmatter necesario. Revisa el resultado y ajusta la descripción para que quede claro cuándo llamar al agente.

Forma 2: a mano, creando un archivo .md

Crea el archivo .claude/agents/market-researcher.md:

---
name: market-researcher
description: Investiga mercados y reúne datos sobre la competencia. Úsalo cuando haga falta reunir información sobre el mercado, competidores, precios o tendencias.
tools: Read, Glob, Grep, WebFetch, WebSearch
model: haiku
color: green
---

Eres un investigador de mercados. Reúne datos de fuentes abiertas,
analiza a la competencia, encuentra tendencias. Devuelve un resumen
estructurado con los hallazgos clave.

Los subagentes se cargan al iniciar la sesión. Si creaste el archivo a mano, reinicia la sesión para que se cargue.

Forma 3: con la CLI (para automatizar o probar rápido)

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Los subagentes de la CLI viven solo en la sesión actual y no se guardan en disco.

Elegir el modelo

Claude Haiku  → para tareas mecánicas (reunir datos, dar formato, buscar)
Claude Sonnet → para tareas que requieren razonar (análisis, código, redacción)
Claude Opus   → para tareas estratégicas complejas (arquitectura, análisis crítico)

Prioridad para elegir el modelo (de la más alta a la más baja):

1. El parámetro model en una llamada concreta
2. El campo model en el frontmatter del subagente
3. La variable de entorno CLAUDE_CODE_SUBAGENT_MODEL
4. El modelo de la sesión principal

Para obligar a todos los subagentes a usar un mismo modelo, agrega una segunda variable, CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1: así se impone sobre lo demás.

Nota a octubre de 2026: Claude Haiku 4.5 podría retirarse de la API no antes del 15.10.2026. Revisa la página Lo vigente.

Manejo de herramientas: tools vs. disallowedTools

Allowlist: indicar SOLO las permitidas:

tools: Read, Grep, Glob, Bash

El subagente NO puede editar archivos, escribir ni usar MCP.

Denylist: prohibir algunas concretas y heredar el resto:

disallowedTools: Write, Edit

El subagente hereda TODO menos escribir y editar archivos.

Si se indican ambos, primero se aplica disallowedTools y luego tools.

Limitar las llamadas anidadas: Agent(type)

Cuando un subagente se lanza como agente principal (con --agent), puedes limitar a qué subagentes puede llamar. Si quitas Agent de la lista tools, el subagente no podrá lanzar a nadie:

tools: Agent(worker, researcher), Read, Bash

Solo se permiten worker y researcher. Los demás se bloquean. La profundidad total del anidamiento se limita con CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (el valor 1 desactiva el anidamiento).

Memoria persistente (memory)

🎨 Imagínalo así: un subagente con memoria es como un contador que lleva una libreta. Después de diez revisiones de tu código conoce todos tus patrones de memoria. Sin memoria, empieza de cero cada vez, como en su primer día de trabajo.

Un subagente puede acumular conocimiento entre sesiones:

memory: project

Con la memoria activada, el subagente recibe automáticamente instrucciones para leer y escribir en su MEMORY.md.

Código de colores

En la terminal, cada subagente se muestra con un color distinto. Disponibles: red, blue, green, yellow, purple, orange, pink, cyan.

Ves de un vistazo quién está trabajando.

Ejemplos de subagentes personalizados (en el formato oficial)

Code Reviewer (solo lectura):

---
name: code-reviewer
description: Analiza el código en busca de bugs, problemas de seguridad y calidad. Úsalo DESPUÉS de escribir cualquier código, antes del commit.
tools: Read, Glob, Grep
model: sonnet
color: red
memory: project
---

You are a code reviewer. Focus on code quality, security, and best practices.
Check your memory for patterns you've seen before.

Debugger:

---
name: debugger
description: Debugging specialist for errors and test failures. Úsalo cuando haya un mensaje de error concreto.
tools: Read, Grep, Glob, Bash
model: sonnet
color: yellow
---

You are an expert debugger. Analyze errors, identify root causes, and provide fixes.

Build Validator (con un modelo barato):

---
name: build-validator
description: Ejecuta las pruebas y verifica que el código compile. Úsalo antes de cada deploy.
tools: Bash, Read
model: haiku
color: green
---

Run tests and build checks. Report only failures with error messages.

Subagente con su propio servidor MCP:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

Llamar a un subagente: cuatro formas

1. Delegación automática: Claude decide por sí mismo con base en la descripción del subagente:

Analiza el rendimiento de la base de datos
→ Claude ve que existe el subagente db-reader → delega

2. Mencionarlo en el prompt: dale una pista a Claude:

Use the code-reviewer subagent to look at my recent changes

3. @-mention: garantiza que se llame a un subagente concreto:

@"code-reviewer (agent)" revisa el módulo auth

4. Lanzar toda la sesión como subagente:

claude --agent code-reviewer

El prompt principal se reemplaza por el prompt del sistema del subagente.

Foreground vs. background y fork

🎨 Imagínalo así: foreground es dar la tarea y esperar en la puerta a que la terminen. Background es dar la tarea e irte a hacer lo tuyo: el agente trabaja en paralelo y tú no te quedas parado.

• Foreground: bloquea la conversación principal hasta que termina. Las solicitudes de permiso llegan a ti.
• Background: trabaja en paralelo mientras sigues. En las sesiones interactivas actuales, los subagentes trabajan en segundo plano por defecto (fork mode activado). Las solicitudes de permiso aparecen en la sesión principal con el nombre del subagente.

Presiona Ctrl+B para mandar la tarea actual a segundo plano.

Fork: un subagente que hereda toda la conversación (prompt del sistema, historial, herramientas, modelo) en lugar de empezar desde cero. Usa la caché de prompt compartida, así que es más barato que un subagente normal. Para lanzar un fork a mano: /subtask <descripción de la tarea>.

Cuándo usar subagentes

✅ Usa subagentes cuando:

• La tarea produce un montón de salida que no hace falta en el contexto principal (pruebas, logs, documentación)
• Necesitas limitar las herramientas o los permisos disponibles
• El trabajo es autosuficiente y se puede devolver un resumen
• Son tareas que se repiten muchas veces en distintos proyectos

✅ Investigación en paralelo:

Investiga los módulos authentication, database y API en paralelo, en subagentes separados

Cada subagente investiga su área de forma independiente y luego Claude sintetiza los hallazgos.

❌ No uses subagentes cuando:

• La tarea requiere ir y venir con frecuencia (ajustes iterativos)
• Varias fases comparten mucho contexto (plan → implement → test)
• Son correcciones rápidas y puntuales (el costo extra > la tarea misma)
• Importa la velocidad: el subagente empieza desde cero y pierde tiempo reuniendo contexto

Para una pregunta rápida sobre el contexto actual usa /btw en lugar de un subagente: ve todo el contexto, pero no tiene herramientas.

Práctica

Tarea 1: crear un subagente "investigador" pidiéndoselo a Claude

1. Abre Claude Code
2. Pídele: "Crea un subagente personal market-researcher en ~/.claude/agents/" y describe los parámetros:
   • Name: market-researcher
   • Description: explica cuándo usarlo (2-3 oraciones)
   • Tools: solo lectura y búsqueda web
   • Model: haiku (ahorro)
   • Color: green
   • Memory: no hace falta
3. Abre el archivo creado y revisa el frontmatter
4. Pruébalo: pídele a Claude "usa el subagente market-researcher para investigar a los 3 competidores principales en el nicho de educación en línea"
5. Observa en la terminal cómo el agente principal le delega la tarea al subagente (color verde)
6. Comprueba que el subagente devolvió un resumen estructurado

Tarea 2: crear un subagente a mano, como archivo

1. Crea el archivo .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews code for quality, security, and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
color: red
memory: project
---

You are a senior code reviewer. Analyze code and provide specific,
actionable feedback on quality, security, and best practices.
Update your agent memory with patterns and conventions you discover.

2. Reinicia la sesión de Claude Code
3. Verifica: escribe @ y comprueba que code-reviewer aparece en las sugerencias
4. Pruébalo: @"code-reviewer (agent)" revisa el archivo server.ts

Tarea 3 (extra): crear un subagente con la CLI

claude --agents '{"quick-search": {"description": "Fast codebase search", "prompt": "Search the codebase and return concise findings.", "tools": ["Read", "Grep", "Glob"], "model": "haiku"}}'

Herramientas y recursos

• Pedírselo a Claude: la forma principal de crear un subagente (el asistente /agents se eliminó en la versión 2.1.198; ahora el comando solo recuerda las carpetas)
• claude agents: la pantalla de todas las sesiones en segundo plano (agent view, research preview), no la lista de archivos de subagentes
• .claude/agents/: carpeta de subagentes del proyecto (archivos .md con frontmatter YAML)
• ~/.claude/agents/: carpeta de subagentes del usuario (disponibles en todos los proyectos)
• Agentes integrados: Explore (solo lectura), Plan (solo lectura), General-purpose (todas las herramientas), fork
• Documentación: https://code.claude.com/docs/en/sub-agents

Ideas clave

Un subagente es un especialista contratado. Lo contratas, le explicas la tarea, recibes el resultado y lo dejas ir. Tu contexto principal queda limpio.

El archivo de un subagente = Markdown con frontmatter YAML. 18 campos de configuración: del modelo y las herramientas a la memoria, los hooks y sus propios servidores MCP.

Principio de mínimo privilegio: tools: Read, Grep, Glob: el researcher lee, no escribe. disallowedTools: Write, Edit: otro camino al mismo resultado.

Haiku para reunir datos, Sonnet para analizar, Opus para la estrategia. El modelo correcto = un ahorro de varias veces.

El anidamiento está limitado a tres niveles. Para empezar, mantén la cadena plana: llama a los subagentes uno tras otro desde la conversación principal.

Un subagente con memory: project acumula conocimiento entre sesiones. Después de 10 revisiones de código, conoce los patrones de tu proyecto.

Qué sigue

→ Equipos de agentes: trabajo en paralelo