Takren

Subagentes en Claude Code: qué son y cómo usarlos

Por Javier Misuraca · Actualizado: junio 2026

Un subagente es una sesión secundaria de Claude Code que se lanza desde tu sesión principal, ejecuta una tarea acotada con su propia ventana de contexto, y devuelve solo el resultado final. Todo el ruido del proceso (las búsquedas, los archivos leídos, las llamadas a herramientas) muere en el subagente y nunca ensucia tu sesión principal.

Si trabajas con Claude Code más de un rato seguido, los subagentes son la capacidad que más rinde. Esta guía explica por qué, y cómo crear el tuyo.

¿Qué problema resuelven los subagentes?

Llevas dos horas en una sesión productiva. Pediste un plan grande: el modelo exploró el código, hizo varias búsquedas web, leyó una docena de archivos y te devolvió una respuesta sólida. Pero cuando vas a la siguiente tarea, notas que empieza a divagar, sus respuestas pierden filo y tu cuota se consume rápido.

No es que el modelo se haya vuelto peor. Tu ventana de contexto está saturada de información que ya no necesitas, y esa basura cognitiva degrada cada turno nuevo. Es el fenómeno que en Ship with Claude Code llamamos Long Context Failure.

Long Context Failure: el fenómeno por el que un contexto lleno de ruido degrada la calidad de cada turno nuevo, aunque el modelo no haya cambiado.

Los subagentes son la solución de arquitectura a ese problema.

¿Cómo funcionan los subagentes?

Cada subagente tiene su propia ventana de contexto (típicamente 200.000 tokens en los modelos estándar, más en planes empresariales o vía API), su propio modelo asignado y, opcionalmente, su propio conjunto restringido de herramientas. Cuando termina, se cierra y solo el resultado consolidado viaja de vuelta. Todo lo demás se descarta.

El ahorro se ve mejor con números. Imagina que planificas una feature grande:

Multiplica ese ahorro por cada exploración, cada depuración y cada búsqueda de una sesión larga, y entiendes por qué los workflows serios dependen de subagentes.

La metáfora útil: tu sesión principal es un director de orquesta, no un instrumento. Si tú haces la investigación, la auditoría y el análisis a mano, terminas con la cabeza saturada. Si delegas a especialistas que te traen su informe ejecutivo, integras solo conclusiones y mantienes la cabeza limpia para decidir.

¿Qué tipos de subagente existen?

En Claude Code vas a trabajar con tres familias:

  1. Built-in: los que Claude Code despliega automáticamente. Los más visibles son Explore (búsqueda y lectura del código base, normalmente con Haiku para velocidad) y Planning (planificación con un modelo más fuerte como Sonnet). Aparecen en /agents y la sesión principal decide cuándo invocarlos sin que tú lo pidas.
  2. De plugins: vienen empaquetados en plugins externos. Se instalan con el sistema de plugins y aparecen en /agents junto a los nativos. Los detalles de cada tipo están en la documentación oficial de subagentes.
  3. Personalizados: los que tú diseñas. Llevan un prompt de sistema, un modelo asignado y una lista explícita de herramientas permitidas. Viven en .claude/agents/ (locales al proyecto) o en ~/.claude/agents/ (globales).

¿Cómo crear un subagente? Paso a paso

1. Lista los que ya tienes:

/agents

Verás general-purpose, Explore, Planning y cualquiera de plugins o personalizado que tengas.

2. Invoca uno manualmente con @:

@Explore lístame todos los archivos donde se importa la librería de logging.

El símbolo @ fuerza el envío a ese subagente en lugar de dejar que la sesión principal decida.

3. Crea uno personalizado: desde /agents, elige crear un agente nuevo. Define si es local al proyecto o global, escribe una descripción clara (cuanto más específica, mejor la elige la sesión principal), asigna modelo y elige herramientas.

4. Aplica el principio de mínimo privilegio. Esta es la regla que más gente ignora y la que más rinde: dale al subagente solo las herramientas que necesita. Si solo lee y busca, dale Read, Glob, Grep, WebFetch, WebSearch. Nada de Edit, Write ni Bash. Cada herramienta extra es una fuente de ruido y de decisiones malas.

5. Asigna el modelo a propósito:

Al guardar, el subagente queda como un archivo .md en .claude/agents/. Puedes editarlo a mano y hacer commit al repositorio para que lo use todo el equipo.

¿Cuándo usar un subagente y cuándo no?

La regla son dos condiciones, y se tienen que cumplir las dos:

  1. La tarea consume mucho contexto temporal que no necesitas conservar.
  2. La tarea produce un resultado consolidado pequeño que sí necesitas.

Planificación, búsqueda en código grande, depuración exploratoria, investigación web y revisión de diffs cumplen las dos. Una tarea corta, no: el subagente tiene latencia de arranque y costo propio en tokens, así que para algo rápido sale más caro que ejecutarlo en línea.

Dos errores frecuentes que conviene evitar:

Un paso más: equipos de subagentes

Cuando dominas el subagente individual, el siguiente patrón es Scout → Worker → Synthesizer: uno explora, varios procesan en paralelo y uno integra los resultados. Es la base para paralelizar problemas grandes (refactors masivos, debugging de sistemas distribuidos) sin saturar una sola sesión. Para supervisar varios agentes a la vez, Claude Code ofrece el panel Agent View.

Preguntas frecuentes

¿Qué es un subagente en Claude Code?

Un subagente es una sesión secundaria de Claude Code que se lanza desde la sesión principal, ejecuta una tarea acotada con su propia ventana de contexto y devuelve solo el resultado final. Todo el ruido del proceso (búsquedas, archivos leídos, llamadas a herramientas) queda en el subagente y no contamina la sesión principal.

¿Cuánto contexto ahorra usar un subagente?

En una planificación típica, sin subagente la sesión principal puede acumular unos 50.000 tokens de exploración de los que solo 5.000 son útiles a futuro. Con un subagente de planificación, esos 45.000 tokens de ruido viven y mueren dentro del subagente; la sesión principal recibe solo el plan consolidado.

¿Cómo se invoca un subagente en Claude Code?

Con el símbolo @ seguido del nombre: por ejemplo, @Explore lístame los archivos donde se importa la librería de logging. El comando /agents muestra los disponibles: los built-in (Explore, Planning, general-purpose), los de plugins y los personalizados que viven en .claude/agents/.

¿Cuándo no conviene usar un subagente?

Cuando la tarea es corta. El subagente tiene latencia de arranque y coste propio en tokens; para algo rápido sale más caro que ejecutarlo en la sesión principal. La regla de dos condiciones: la tarea debe consumir mucho contexto temporal Y producir un resultado consolidado pequeño. Si no se cumplen las dos, no vale la pena.

¿Qué modelo se asigna a un subagente personalizado?

Haiku 4.5 para investigación y lectura de código: rápido, económico y suficiente para consolidar información. Sonnet 4.6 para planificación o ejecución. El alias opus solo cuando la calidad estructural importa más que la velocidad. El modelo se elige al crear o editar el archivo .md del subagente en .claude/agents/.

Recursos relacionados

Lleva los comandos contigo

Los comandos de subagentes (/agents, @, claude --agent, SendMessage) y decenas más están en la Cheat Sheet de Claude Code: una hoja imprimible, en español, con lo que más se consulta bajo presión.

Descargar la Cheat Sheet gratis

Es el resumen de Ship with Claude Code, la guía de Takren (14 módulos, 190 capítulos, actualizaciones gratuitas).