El problema del contexto infinito
Imagina que le pides a Claude que investigue cómo funciona la autenticación de tu proyecto. Empieza a leer archivos. Muchos archivos. De repente llevas 50.000 tokens de contexto llenos de código que solo necesitabas consultar, no recordar.
Ahora cada respuesta es más lenta. Y más cara. Y cuando quieras hacer otra cosa, todo ese contexto sigue ahí, ocupando espacio mental.
La solución: subagentes. Lanzas un agente especializado que hace el trabajo sucio en su propio contexto aislado, te devuelve un resumen, y desaparece. Tu conversación principal queda limpia.
Qué es un subagente
Un subagente es una instancia separada de Claude que:
- Tiene su propio contexto (no contamina tu conversación)
- Puede tener herramientas restringidas (solo lectura, solo bash, etc.)
- Puede usar un modelo diferente (haiku para tareas simples, opus para las complejas)
- Puede ejecutarse en foreground (bloqueante) o background (paralelo)
Piensa en ellos como becarios especializados. Les asignas una tarea, trabajan de forma independiente, y te reportan cuando terminan.
Los subagentes que ya tienes
Claude Code viene con varios subagentes integrados:
| Agente | Modelo | Para qué sirve | Herramientas |
|---|---|---|---|
| Explore | Haiku | Buscar y analizar código | Solo lectura |
| Plan | Hereda | Investigar durante planificación | Solo lectura |
| general-purpose | Hereda | Tareas complejas multi-paso | Todas |
| Bash | Hereda | Comandos en contexto separado | Solo Bash |
| Claude Code Guide | Haiku | Preguntas sobre Claude Code | Documentación |
El más útil es Explore. Cuando Claude necesita buscar algo en tu codebase, lanza un Explore que lee archivos como loco, procesa todo, y devuelve solo lo relevante.
Cómo lanzar subagentes
Desde el REPL (conversación normal)
Simplemente pídelo en lenguaje natural:
Usa un subagente para investigar cómo funciona el sistema de caché
Lanza el agente Explore para encontrar todos los endpoints de la API
Investiga la autenticación en paralelo mientras yo sigo trabajando
Claude entiende estas peticiones y usa la herramienta Task internamente para lanzar el subagente apropiado.
Desde un Skill
En un skill puedes forzar que se ejecute en un subagente aislado con context: fork:
---
name: deep-analysis
description: Análisis profundo de arquitectura
context: fork
agent: Explore
---
Analiza la arquitectura completa del proyecto.
Genera un informe con:
- Estructura de directorios
- Dependencias principales
- Patrones de diseño detectados
Con context: fork, el skill se ejecuta en un subagente. Con agent: Explore, especificas qué tipo de agente usar.
Lanzamiento explícito por tipo
Si quieres ser específico:
Usa el agente Explore para mapear la estructura del proyecto
Usa un agente general-purpose para refactorizar el módulo de pagos
Usa el agente Bash para ejecutar la suite de tests completa
Foreground vs Background
Foreground (bloqueante)
Por defecto, los subagentes se ejecutan en foreground. Tu sesión espera a que terminen.
Investiga cómo funciona el rate limiting
[Claude lanza subagente, esperas, recibes resultado]
Útil cuando necesitas el resultado inmediatamente.
Background (paralelo)
Puedes enviar un subagente al background de dos formas:
1. Pidiéndolo explícitamente:
Investiga el sistema de caché en background mientras reviso otra cosa
2. Con Ctrl+B mientras está ejecutando:
Si un subagente ya está corriendo y quieres seguir trabajando, pulsa Ctrl+B. El agente pasa a background y puedes continuar.
> Analiza todos los tests del proyecto
[Empieza a ejecutar...]
[Pulsas Ctrl+B]
> Vale, mientras tanto, explícame qué hace este archivo
[Sigues trabajando, el análisis continúa en paralelo]
Ver tareas en background
Usa el comando /tasks para ver qué hay corriendo:
/tasks
Esto muestra todas las tareas en background con sus IDs, estado y progreso.
Comunicación con subagentes
Saber qué está haciendo
Mientras un subagente está en foreground, ves su progreso en tiempo real (qué archivos lee, qué comandos ejecuta).
Si está en background, usa /tasks para ver el estado. Cuando termina, Claude te notifica automáticamente con el resultado.
Dar instrucciones adicionales
Si un subagente está corriendo y quieres añadir contexto:
Por cierto, ignora los archivos de test, solo me interesa el código de producción
Claude intenta pasar esta información al subagente si es posible.
Parar un subagente
Para detener una tarea en background:
Para la tarea de análisis
Cancela el subagente que está corriendo
O desde /tasks, puedes cancelar tareas específicas por ID.
Retomar un subagente
Los subagentes mantienen su historial dentro de la sesión. Puedes retomar donde lo dejaron:
Continúa el análisis de autenticación que hiciste antes
y ahora revisa también la autorización
Claude retoma el subagente con todo su contexto previo.
Crear tus propios subagentes
Con el comando /agents (recomendado)
/agents
Selecciona Create new agent, elige el scope (usuario o proyecto), describe qué quieres, y Claude genera el archivo por ti.
Manualmente
Crea un archivo Markdown en .claude/agents/ (proyecto) o ~/.claude/agents/ (global):
---
name: security-scanner
description: Escanea código en busca de vulnerabilidades. Usar proactivamente después de cambios en autenticación o manejo de datos.
tools: Read, Grep, Glob
model: opus
---
Eres un experto en seguridad. Analiza el código buscando:
- Inyección SQL
- XSS
- Secrets hardcodeados
- Validación de input insuficiente
- Dependencias vulnerables
Reporta por severidad: Crítico > Alto > Medio > Bajo.
NO modifiques código, solo reporta.
Configuración del frontmatter
| Campo | Obligatorio | Descripción |
|---|---|---|
name |
Sí | Identificador único (minúsculas y guiones) |
description |
Sí | Cuándo usar el agente (Claude lee esto) |
tools |
No | Herramientas permitidas (por defecto: todas) |
disallowedTools |
No | Herramientas prohibidas |
model |
No | haiku, sonnet, opus, o inherit |
permissionMode |
No | Cómo manejar permisos |
skills |
No | Skills a inyectar en el contexto |
hooks |
No | Hooks del ciclo de vida |
Modos de permisos
| Modo | Comportamiento |
|---|---|
default |
Pide permiso como siempre |
acceptEdits |
Auto-acepta ediciones de archivos |
dontAsk |
Auto-deniega operaciones no solicitadas |
bypassPermissions |
Salta todos los permisos (peligroso) |
plan |
Modo solo lectura |
Ejemplo: Agente de solo lectura
---
name: code-reader
description: Lee y analiza código sin modificar nada
tools: Read, Grep, Glob
disallowedTools: Write, Edit, Bash
permissionMode: plan
---
Analiza el código solicitado.
NUNCA sugieras modificaciones, solo describe lo que encuentras.
Ejemplo: Agente de tests
---
name: test-runner
description: Ejecuta tests y reporta fallos. Usar después de cambios de código.
tools: Bash, Read
model: haiku
---
1. Ejecuta: `uv run pytest -x --tb=short`
2. Si hay fallos, lee los archivos relevantes
3. Reporta:
- Tests pasados: X
- Tests fallidos: Y
- Resumen de cada fallo (archivo, línea, error)
NO intentes arreglar los tests, solo reporta.
Casos de uso habituales
1. Investigación de codebase
Usa Explore para entender cómo funciona el sistema de notificaciones
El Explore lee todo lo necesario, tú recibes un resumen sin contaminar tu contexto.
2. Análisis paralelo
Investiga en paralelo:
- Cómo funciona la autenticación
- Cómo funciona el sistema de pagos
- Cómo funciona el envío de emails
Claude lanza tres subagentes simultáneos. Cada uno investiga su área.
3. Tests en background
Ejecuta los tests en background mientras implemento esta feature
No tienes que esperar. Cuando fallen (o pasen), te avisa.
4. Code review aislado
Usa un subagente para revisar la seguridad de los cambios que acabo de hacer
El review ocurre en contexto separado. Recibes feedback sin ruido.
5. Refactoring seguro
---
name: safe-refactor
description: Refactoriza código con verificaciones
tools: Read, Edit, Bash
hooks:
PostToolUse:
- matcher: "Edit"
hooks:
- type: command
command: "uv run pytest -x"
---
Cada edición dispara los tests automáticamente.
Subagentes vs Skills: Cuándo usar cada uno
| Necesidad | Usar |
|---|---|
| Instrucciones reutilizables en el contexto principal | Skill |
| Tarea que genera mucho output | Subagente |
| Restringir herramientas para una operación | Subagente |
| Trabajo paralelo independiente | Subagente |
| Proceso con pasos definidos que quiero ver | Skill |
| Investigación que no necesito recordar | Subagente |
También puedes combinarlos: un skill con context: fork lanza un subagente.
Limitaciones
- No pueden anidar: Un subagente no puede lanzar otro subagente
- Permisos en background: Los subagentes en background auto-deniegan permisos no preaprobados
- Sesión única: El contexto del subagente vive solo durante la sesión
Tips avanzados
Desactivar subagentes específicos
En settings.json:
{
"permissions": {
"deny": ["Task(Explore)", "Task(mi-agente-custom)"]
}
}
Auto-compactación
Los subagentes tienen auto-compactación al 95% del contexto. Para dispararlo antes:
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50
Ver transcripciones
Los logs de subagentes se guardan en:
~/.claude/projects/{proyecto}/{sesión}/subagents/agent-{id}.jsonl
Útil para debugging o auditoría.
Desactivar background tasks
Si prefieres que todo sea bloqueante:
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
Conclusión
Los subagentes son la forma de escalar tu uso de Claude Code sin que el contexto explote. Delegan trabajo sucio, mantienen tu conversación limpia, y pueden trabajar en paralelo.
Úsalos para investigación, análisis, tests, y cualquier tarea que genere mucho output que no necesitas recordar. Crea los tuyos propios para tareas repetitivas con restricciones específicas.
La combinación de skills (qué hacer) + subagentes (dónde hacerlo) + hooks (cuándo validar) te da un control bastante fino sobre cómo trabaja Claude.
TL;DR: Los subagentes son instancias aisladas de Claude para tareas específicas. Mantienen tu contexto limpio, pueden correr en paralelo (Ctrl+B), y puedes crear los tuyos en .claude/agents/. Usa /tasks para monitorearlos y /agents para gestionarlos.
Documentación oficial: Subagents – Claude Code Docs
Read this article in English.
