# Subagentes en Claude Code: cuándo delegar y cuándo estorban La primera vez que usé un subagente fue por accidente y por desesperación. Estaba buscando en qué punto de una plataforma de facturación de unas cuantas decenas de miles de líneas se calculaba un prorrateo, le pedí a Claude que lo encontrara, y vi cómo se me comía media ventana de contexto leyendo ficheros que no eran. Cuando dio con el sitio, ya no me quedaba sitio para trabajar en él. Ese es exactamente el problema que resuelve un subagente, y por eso me molesta tanto que se hayan convertido en un concurso de personalidades. Un subagente no es un empleado con carácter. Es **una ventana de contexto separada, con su propio prompt de sistema, sus propias herramientas y su propio modelo**, que hace un trabajo y te devuelve el resultado. Nada más. Y ese «nada más» es justo lo valioso. Este post es lo que he aprendido usándolos a diario, después de [los comandos que uso](/post/comandos-de-claude-code) y antes de que nadie te venda una agencia entera. ## Qué es, mecánicamente Un subagente es un fichero Markdown con front matter YAML. Vive en uno de dos sitios: - `~/.claude/agents/` — personal, disponible en todos tus proyectos. - `.claude/agents/` dentro del repo — del proyecto, y va a git, así que lo tiene todo el equipo. Los dos directorios se escanean recursivamente, o sea que puedes organizarlos en subcarpetas sin que eso afecte a su identidad: lo único que identifica a un agente es el campo `name`. El fichero mínimo son dos campos y un cuerpo: ```markdown --- name: revisor-migraciones description: Revisa migraciones de base de datos buscando bloqueos de tabla, índices que faltan y cambios no reversibles. Úsalo antes de aprobar una migración. --- Eres un revisor de migraciones de PostgreSQL y MariaDB... ``` `name` tiene una regla que conviene saberse porque no perdona: **solo minúsculas y guiones**. Ni espacios, ni mayúsculas, ni dos puntos (los dos puntos están reservados para los agentes que vienen de un plugin, que se llaman `plugin:agente`). Y tiene que ser único dentro de su directorio. `description` es lo que Claude lee para decidir si te delega el trabajo. Es la única parte del fichero que se carga siempre. ## El campo que casi nadie rellena A partir de ahí vienen los opcionales, y son los que separan un subagente de un prompt largo con ínfulas. **`tools`** es una lista blanca. Le dices exactamente qué puede tocar: ```yaml tools: Read, Grep, Glob ``` Con eso, ese agente **no puede escribir un fichero ni ejecutar un comando** aunque se lo pidas, aunque alucine, aunque se lo pida un fichero del repo que lea. Si no pones el campo, hereda todas tus herramientas. Todas. Existe también `disallowedTools` para el caso contrario: heredar el conjunto completo y quitarle un par de cosas. **`model`** decide con qué modelo corre: `haiku`, `sonnet`, `opus`, `fable`, un ID completo, o `inherit` (el de tu sesión, que es el valor por defecto). Un agente que clasifica líneas de log o que extrae los nombres de fichero de un `git diff` no necesita el modelo caro. Yo tengo un par en Haiku y no he notado la diferencia salvo en la factura y en la velocidad. Y hay más que uso menos pero conviene conocer: `permissionMode` para que un agente concreto vaya en modo plan o acepte ediciones sin preguntar; `maxTurns` para cortarle las alas a uno que se puede ir de bucle; `memory` para darle memoria persistente de usuario, proyecto o local; `effort` para bajarle o subirle el esfuerzo de razonamiento; `isolation: worktree` para que trabaje en un worktree de git aparte y no te toque el árbol. Si tuviera que quedarme con un consejo de todo el post sería este: **`tools` y `model` son el noventa por ciento del valor de un subagente**. Un agente sin `tools` es un agente al que le has dado tu terminal. ## Lo que cuesta tenerlos ahí Aquí está la parte que casi nadie cuenta, y es una restricción dura de diseño. Las **descripciones de todos tus subagentes se cargan en el contexto de la conversación principal**. Tienen que estar: son lo que el modelo lee para saber a quién puede delegar. El cuerpo del fichero no —eso solo se carga cuando el agente arranca de verdad—, pero la descripción sí, y en cada turno. La documentación pone el límite en unos **15.000 tokens** para la suma de todas las descripciones de tus agentes personalizados, y Claude Code te avisa al arrancar si te pasas. Traducido: cada agente que instalas «por si acaso» te está cobrando un alquiler permanente en la ventana de contexto que usas para trabajar. Diez agentes con descripciones de dos líneas son gratis. Doscientos, no. De ahí la regla práctica: **descripción corta y específica en el front matter, instrucciones largas en el cuerpo**. La descripción dice *cuándo* llamarlo; el cuerpo dice *cómo* hace su trabajo, y solo se paga cuando se usa. ## Las tres razones legítimas para delegar Después de meses con esto, todas las veces que un subagente me ha compensado caen en una de tres categorías. **Uno: aislar contexto.** Es la razón principal y la que me llevó al primer accidente. Cuando la respuesta requiere leer veinte ficheros y solo me interesan tres líneas del resultado, delegar significa que esas veinte lecturas ocurren en *otra* ventana y a mí me llega la conclusión. La búsqueda del prorrateo la resuelvo hoy con un agente de exploración, y lo que aterriza en mi conversación son dos rutas de fichero y un número de línea. Lo que se ahorra no es tiempo: es sitio. **Dos: restringir privilegios.** Tengo un revisor con `tools: Read, Grep, Glob` y nada más. Le paso el diff de una rama y me dice lo que ve. No puede arreglar nada, y esa es la gracia: quiero un dictamen, no que me toque el árbol de trabajo mientras opina. La misma idea vale para cualquier agente que vaya a leer contenido que no controlas del todo —un fichero de un cliente, la salida de un servicio externo—: si no tiene `Bash`, no hay conversación que valga. **Tres: economía de modelo.** Trabajo hecho, no arte. Extraer datos, clasificar, resumir un log, convertir un formato. Eso va en Haiku, corre más rápido y cuesta una fracción. Si una tarea no encaja en ninguna de las tres, casi siempre es mejor hacerla en la conversación principal. ## Cuándo estorban Y ahora la parte que no sale en los README. **Cuando necesitas ver el proceso, no el resultado.** Un subagente te devuelve un informe. Si lo que quieres es ir corrigiendo el rumbo a mitad —«no, por ahí no», «prueba con el otro fichero»—, delegar te deja fuera de la conversación justo cuando querías estar dentro. Para explorar acompañado, ventana principal. **Cuando la tarea es pequeña.** Arrancar un subagente tiene un coste fijo: su prompt de sistema, su contexto inicial, su ida y vuelta. Para leer un fichero que ya sabes cuál es, delegar es más caro y más lento que hacerlo. **Cuando el trabajo necesita continuidad.** El agente no recuerda nada de la conversación anterior salvo lo que le pases en el encargo, y no verá lo que pase después. Las tareas que se construyen sobre lo hablado hace veinte minutos se hacen en el sitio donde se habló. **Cuando delegas por moda.** Esto lo digo por experiencia propia: hubo una semana en la que le puse un agente a todo, y lo único que conseguí fue perder el hilo de lo que estaban haciendo cinco procesos a la vez. Hay un límite de concurrencia por defecto de veinte subagentes simultáneos, y te aseguro que el límite útil de un humano supervisando está muy por debajo. El mío está en dos o tres, y siendo generoso. ## Cómo escribo yo uno Tres reglas y una manía. **Un agente, un trabajo.** Si la descripción necesita un «y también», son dos agentes. El «asistente de backend que además revisa seguridad y de paso escribe tests» no se llama nunca porque el modelo no sabe cuándo le toca. **Restringe siempre `tools`.** Empieza por lo mínimo y amplía cuando falle. Es infinitamente más fácil añadir `Bash` el día que lo necesites que averiguar por qué un agente de documentación ha reescrito un fichero de configuración. **Pon `model` explícito.** Aunque sea para escribir `inherit`. Obliga a hacerse la pregunta de cuánto vale el trabajo que estás delegando. Y la manía: escribo el agente **después** de haber hecho la tarea a mano al menos dos veces. Sé cómo se resuelve, sé dónde me atasqué, y el prompt sale de eso en vez de salir de imaginarme un puesto de trabajo. Mis agentes son feos y cortos —ochenta líneas, sin emojis, sin secciones tituladas «Tu identidad y memoria»— y hacen exactamente lo que dicen. Un subagente bien hecho no se parece a un empleado. Se parece más a un [alias de git](/post/git-aliases-que-uso-cada-dia): una cosa pequeña, aburrida y afiladísima que usas cien veces al día sin pensar. Y como los alias, los buenos no son los que copias de la lista de otro. Son los que escribes el día que te hartas de repetir algo.