Subagentes en Claude Code: qué hacen y cuándo usarlos

Respuesta corta: un subagente es un contexto aparte al que Claude Code delega trabajo, con su propio prompt de sistema, sus propios permisos de herramientas y, si quieres, su propio modelo. La documentación de Anthropic enumera cinco motivos para usarlos: preservar contexto manteniendo la exploración y la implementación fuera de tu conversación principal, imponer restricciones limitando qué herramientas puede usar un subagente, reutilizar configuraciones entre proyectos, especializar el comportamiento con prompts de sistema enfocados y controlar el coste enviando tareas a modelos más rápidos y baratos. El primero y el último son los que más cambian tu día a día.

El problema de contexto que resuelven

Cada mensaje de una sesión de Claude Code arrastra consigo toda la conversación. Si lees cuarenta archivos buscando algo, esos cuarenta archivos se quedan en el contexto durante el resto de la sesión, compitiendo con el trabajo que de verdad te importa.

Eso produce dos síntomas visibles. Las sesiones largas se vuelven más lentas y más caras, porque lo que dispara el coste es la ventana de contexto y no el número de mensajes. Y la calidad baja, porque la señal que necesitas queda enterrada bajo salidas de exploración que solo fueron relevantes cinco minutos.

Un subagente lo resuelve de raíz. El trabajo delegado ocurre en su propio contexto y solo vuelve el resultado. Doce archivos leídos durante una búsqueda te cuestan un resumen en la conversación principal en lugar de doce archivos de ruido.

Por eso existen los agentes de exploración integrados, y por eso son los que más vas a usar, a menudo sin darte cuenta.

Los subagentes integrados

Anthropic documenta varios tipos que vienen con Claude Code, y saber a qué está limitado cada uno explica bastantes comportamientos que si no resultan desconcertantes.

Dos detalles de esa tabla merecen una pausa.

El agente Explore tiene tope en Opus en la API de Claude, y Anthropic explica que es para que Explore nunca se ejecute en un modelo más caro que el que ya elegiste para la sesión. Es un freno de coste deliberado, y significa que buscar en tu base de código no te cobra en silencio a tarifa de modelo puntero.

Explore y Plan son ambos de solo lectura, con Write y Edit denegados. Eso es lo que hace segura la delegación: puedes mandar un agente a investigar sin ninguna posibilidad de que empiece a editar mientras está dentro.

Escribir el tuyo

Un subagente propio es un archivo Markdown con frontmatter. La estructura es lo bastante pequeña como para memorizarla.

---
name: code-improver
description: Revisa archivos y sugiere mejoras de legibilidad, rendimiento y buenas prácticas. Usar después de escribir o modificar código.
tools: Read, Grep, Glob
model: sonnet
---
Eres un especialista en mejora de código. Para cada problema que encuentres, explica la causa, muestra el código actual y aporta una versión mejorada.

Cuatro campos hacen todo el trabajo. name es cómo se invoca. description es lo que Claude lee al decidir si delega, lo que la convierte en la línea más importante del archivo. tools restringe lo que puede hacer. model elige el nivel.

La descripción merece más cuidado del que suele recibir. Claude la usa para decidir cuándo aplica este agente, así que una descripción vaga produce un agente que no se usa nunca o se usa para lo que no toca. Incluye la condición de disparo de forma explícita, como en el ejemplo con “Usar después de escribir o modificar código”.

La forma más rápida de crear uno es pedírselo a Claude Code. Describe qué quieres, dónde debe vivir y qué debe poder hacer, y revisa el archivo generado antes de usarlo.

Dónde viven las definiciones de subagentes

Anthropic documenta cinco ubicaciones con un orden de precedencia definido, y conocerlo evita la confusión habitual de que un agente se comporte distinto del archivo que estás mirando.

1. Ajustes gestionados, desplegados de forma centralizada en toda la organización. Máxima prioridad.
2. El flag --agents de la CLI, que acepta JSON y se aplica a la sesión actual.
3. .claude/agents/, acotado al proyecto actual.
4. ~/.claude/agents/, disponible en todos tus proyectos.
5. El directorio agents/ de un plugin, allí donde ese plugin esté activado. Mínima prioridad.

La regla práctica: las definiciones de proyecto pisan a las personales, y lo que tu organización despliega mediante ajustes gestionados pisa a ambas.

El flag --agents está infrautilizado y es útil para trabajo puntual. Le pasas un objeto JSON que define agentes en línea al arrancar Claude Code, cómodo cuando quieres una configuración especializada una sola vez sin dejar un archivo detrás.

Qué saber antes de montar una flota

Delegar cuesta un viaje de ida y vuelta. Hay que arrancar el subagente, darle contexto y devolver su resultado. Para una tarea que la conversación principal resolvería en dos pasos, esa sobrecarga es una pérdida. La delegación compensa cuando el trabajo volcaría mucho material en tu contexto principal.

El subagente no ve tu conversación. Arranca de cero con lo que le pases. Un encargo que da por supuesto un contexto compartido produce un agente trabajando en el problema equivocado, y este es el fallo más común con diferencia.

Las restricciones de herramientas son el objetivo, no una limitación. Un revisor de solo lectura que no puede editar es más útil que uno sin restricciones, porque puedes ejecutarlo sin comprobar después qué tocó.

Los modelos más baratos suelen bastar. Anthropic enumera enviar tareas a modelos más rápidos y baratos como Haiku entre los cinco motivos para usar subagentes. A 1 dólar por millón de tokens de entrada frente a 5 de Opus 5, una tarea mecánica delegada a Haiku es un ahorro real sin coste de calidad.

Puedes desactivarlos. Para bloquear un tipo integrado, añádelo a permissions.deny. Para cortar la delegación por completo, deniega la propia herramienta Agent. Para quitar solo Explore y Plan, define CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1, que requiere Claude Code v2.1.198 o posterior y hace que Claude lea los archivos directamente. En modo no interactivo y en el Agent SDK, CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 elimina todos los tipos integrados y deja solo los tuyos.

Un marco de decisión: delegar o no

Pasa una tarea por estas cinco preguntas antes de escribirle un agente.

1. ¿Va a generar mucha salida que después no necesito? Buscar, explorar, leer muchos archivos, revisar logs. Si la respuesta es sí, delega; es el argumento más fuerte.
2. ¿Conviene impedir que escriba? Revisión, auditoría, análisis e investigación se benefician de un agente de solo lectura, y la restricción es justamente el valor.
3. ¿Es lo bastante mecánico para un modelo más barato? Formateo, refactorizaciones mecánicas, consultas directas. Envíalo a Haiku y mantén tu sesión principal en el modelo que de verdad necesitas.
4. ¿Voy a hacer esto más de un par de veces? Algo puntual no justifica un archivo de definición. Algo semanal sí, y la reutilización se acumula.
5. ¿Puedo darle instrucciones sin mi historial de conversación? Si la tarea solo tiene sentido con tres horas de contexto acumulado, la delegación te va a decepcionar. Reescribe el encargo o quédatelo en el hilo principal.

Tres o más síes significan escribir el agente. Menos significa hacerlo en línea.

Errores frecuentes ahora mismo

• Escribir una description vaga, de modo que Claude nunca delega en ese agente o le delega lo que no debe.
• Dar todas las herramientas a cada agente propio, lo que tira por la borda el principal beneficio de seguridad.
• Delegar algo pequeño, donde la sobrecarga del viaje de ida y vuelta supera el ahorro.
• Dar por hecho que el subagente ve la conversación y darle instrucciones como si así fuera.
• Construir una biblioteca grande de agentes antes de comprobar que alguno se usa.

Tres agentes que merece la pena escribir primero

Si prefieres puntos de partida concretos en lugar de principios, estos tres se ganan el sitio en casi cualquier base de código y cuestan unos minutos cada uno.

Un revisor de solo lectura. Herramientas limitadas a Read, Grep y Glob, modelo en Sonnet, con un prompt de sistema que le indique reportar problemas del código actual y un reemplazo sugerido en lugar de hacer cambios. Como no puede editar, puedes lanzarlo sobre lo que sea sin comprobar después qué tocó.

Un investigador de tests que fallan. Dale la capacidad de ejecutar tests y leer archivos, y un prompt que le pida encontrar la causa raíz y reportarla en lugar de arreglar nada. La separación importa: un agente que diagnostica y reporta te deja decidir si la corrección vale la pena, mientras que uno que diagnostica y arregla te compromete con su primera teoría.

Un verificador de documentación en Haiku. Trabajo mecánico de contrastar lo que la documentación afirma con lo que hace el código. Es exactamente el perfil para un modelo más barato: mucho volumen, poco juicio, salida fácil de verificar.

Fíjate en que dos de los tres son de solo lectura y el tercero va en el modelo más barato. Esa proporción no es casual. Los agentes que se acaban usando son los que se pueden ejecutar sin supervisión o los que son lo bastante baratos para ejecutarse a menudo.

Dónde encaja esto en un flujo más amplio

Los subagentes encajan de forma natural con el modo plan. Investigas en un agente de solo lectura, traes un resumen, planificas contra ese resumen en la conversación principal y luego ejecutas. La exploración nunca entra en tu contexto principal y el plan se construye sobre un extracto limpio en vez de sobre cuarenta archivos de salida en bruto.

También cambian el comportamiento de las sesiones largas. El efecto práctico de desviar la exploración es que una sesión sigue siendo usable mucho más tiempo antes de que la presión de contexto la degrade, y para quien está sacando adelante una tarea grande eso vale más que el ahorro de tokens.

Construir el criterio detrás de la configuración

La mecánica de esta página se aprende en veinte minutos. Lo que lleva más tiempo es saber qué trabajo delegar, cómo redactar el encargo para que la salida sea aprovechable y cuándo una restricción mejora un resultado en lugar de limitarlo.

Ese es el mismo criterio que aplica a cualquier herramienta con agentes: descomponer una tarea en piezas que se puedan hacer de forma independiente, especificar cada una para que la salida sea comprobable y diseñar el paso de revisión que atrapa lo que sale mal. Aprenderlo en una secuencia estructurada en lugar de a base de prueba y error produce un método que se conserva cuando cambian las herramientas, cosa que en este campo pasa sin falta. Si quieres una ruta estructurada, explora las lecciones de Coursiv y consulta los detalles de plan vigentes en el sitio oficial.

Preguntas frecuentes

Tu siguiente paso

Coge la investigación que más repites, esa en la que acabas leyendo una docena de archivos para responder a una pregunta recurrente, y escríbele un agente de solo lectura con tools: Read, Grep, Glob y una descripción que diga cuándo debe usarse. Ejecútalo una vez y compara cómo queda tu conversación principal después frente a una sesión donde hiciste la misma búsqueda en línea. Esa única comparación defiende la delegación mejor que cualquier explicación del mecanismo.