Subagentes en Claude Code: cuándo conviene delegar

Hay un momento, trabajando con Claude Code, en el que la conversación principal se llena de cosas que no necesitas leer: salidas de tests, el contenido de archivos que solo querías ojear, logs de un script. El plan original sigue ahí, pero queda enterrado bajo el ruido. Para eso existen los subagentes.

Un subagente es una instancia aislada de Claude que se lanza con su propio contexto, su propio system prompt y, opcionalmente, un set restringido de herramientas. Hace su tarea aislada y devuelve solo el resumen a la conversación principal. La intuición es la misma que con cualquier función: la sesión principal hace la llamada, el subagente devuelve el valor.

qué resuelve, en realidad

La doc oficial los vende para cinco cosas, pero al final todas se reducen a tres problemas reales:

1. El contexto se ensucia rápido. Buscar en un repo grande, correr un linter, leer un archivo de dos mil líneas — todo eso consume tokens que no vas a volver a usar. En el subagente esa información se queda donde tiene que quedarse: fuera.
2. Quieres garantizar restricciones. Un agente con solo Read, Grep, Glob no puede tocar nada por accidente, da igual lo que le pidas. Esa garantía no la consigues con buenas intenciones.
3. Repites el mismo prompt una y otra vez. “Eres un revisor de código, busca…” — ese párrafo se convierte en un archivo y lo invocas con @code-reviewer el resto de tu vida.

Si no tienes ninguno de estos tres problemas, no necesitas un subagente. La conversación principal es más rápida, conserva contexto entre pasos y no tiene la latencia de arrancar desde cero.

cómo se definen

Un subagente es un archivo Markdown con frontmatter YAML. Dónde lo guardes determina su alcance:

Los dos campos obligatorios son name (identificador) y description (cuándo Claude debería delegar en él). El cuerpo del archivo es el system prompt:

---
name: code-reviewer
description: Revisa cambios recientes en busca de problemas de calidad y seguridad. Usar proactivamente tras editar código.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Eres un revisor de código senior. Cuando te invoquen:
1. Corre git diff para ver los cambios recientes
2. Enfócate solo en los archivos modificados
3. Reporta problemas críticos primero, luego warnings, luego sugerencias

Tres cosas a notar:

• description no es decorativa. Es lo que Claude lee para decidir si delegar. Añadir “usar proactivamente” cambia el comportamiento — empieza a invocar el subagente sin que se lo pidas.
• tools es un allowlist. Si lo omites, hereda todo. Si quieres lo contrario (todo menos un par de cosas), usa disallowedTools.
• model puede bajar el costo. Un investigador que solo lee archivos no necesita Opus. haiku o sonnet son perfectamente capaces y devuelven resultados más rápido.

cuándo conviene (y cuándo no)

La trampa con los subagentes es la misma que con cualquier abstracción: usarlos de más. Cada subagente añade latencia — arranca desde cero, sin tu contexto — y su resultado final vuelve a ocupar contexto en la conversación principal. No es gratis.

Usa un subagente cuando:

• La salida es ruidosa y solo te importa el resumen. Tests, búsquedas amplias, fetch de docs externas.
• Quieres restringir herramientas. Un investigador read-only que no pueda escribir por error.
• El mismo prompt se repite entre sesiones. Convertirlo en archivo es más barato que reescribirlo.
• Quieres correr varias tareas independientes en paralelo. Un subagente por cada módulo a investigar.

Quédate en la conversación principal cuando:

• La tarea necesita iteración. “Prueba esto, ahora cambia aquello, ahora vuelve a probar” — la latencia de spawn hace esto miserable.
• Necesitas el mismo contexto en varias fases. Planificar → implementar → testear funciona mejor sin reiniciar.
• Es un cambio rápido y dirigido. Para arreglar una línea no hace falta delegar.

Hay un patrón que a veces es mejor que cualquier subagente: un skill. Si lo que quieres es reusar un prompt o un workflow que no necesita aislamiento de contexto, un skill se carga en la conversación principal y comparte todo lo que ya tienes. Subagentes para aislar; skills para reusar.

un ejemplo real: investigador read-only

Este es el patrón que más uso. Un subagente que busca, lee y reporta — pero no toca nada.

---
name: explorer
description: Investiga el código para responder preguntas estructurales. Lee, busca, reporta. No modifica archivos. Usar proactivamente cuando la pregunta sea "dónde está X" o "cómo se conecta Y con Z".
tools: Read, Grep, Glob, Bash
model: haiku
---

Eres un investigador de código. Tu trabajo es responder preguntas
sobre la estructura del repo sin modificar nada.

Cuando te pregunten:
1. Busca de manera amplia primero (Grep, Glob) y luego enfoca (Read).
2. Si el repo es grande, prioriza archivos por su path antes de leerlos.
3. Reporta solo lo relevante. No pegues archivos enteros.

Devuelve siempre rutas con números de línea (`src/foo.ts:42`)
para que la conversación principal pueda navegar directamente.

Lo guardas en .claude/agents/explorer.md, reinicias la sesión, y a partir de ahí Claude lo invoca solo cuando la pregunta encaja con el description. El truco que de verdad lo hace útil son las últimas dos líneas: pedir paths con número de línea convierte el resumen en algo accionable — la conversación principal puede saltar directo al archivo sin re-buscar.

detalles que importan

Reinicia la sesión tras editar el archivo a mano. Los subagentes se cargan al arrancar. Si los creas con el comando /agents se cargan al momento; si los editas en tu editor de texto, no.

Hereda permisos del padre. Si tu sesión principal está en bypassPermissions, acceptEdits o auto, el subagente lo hereda y no puede bajar el nivel. Lo contrario sí funciona: el padre puede estar en modo normal y el subagente correr en plan.

Los subagentes no pueden invocar a otros subagentes. Si necesitas encadenar tareas, hazlo desde la conversación principal: “usa el code-reviewer, luego el optimizer con lo que encuentre”. Claude se encarga de pasarle el contexto relevante al siguiente.

Los logs viven en su propio sitio. Cada invocación deja un transcript en ~/.claude/projects/<proyecto>/<sesión>/subagents/agent-<id>.jsonl. Útil cuando algo salió raro y quieres saber qué pasó dentro.

el resumen, en una frase

Un subagente es una forma de decirle a Claude “haz esto en otro lado y vuelve con el resumen”. Vale la pena cuando lo que hace es ruidoso, restringido o repetido. No vale la pena cuando lo que necesitas es seguir hablando.