Guías prácticas para trabajar con agentes de IA, con un laboratorio al final de cada una
Un subagente trabaja en su propia ventana de contexto y te devuelve solo el resumen. Lo que ahorra es sitio en tu conversación; lo que gasta sale de la misma cuota.
6 min de lectura laboratorio: decisor publicado el 7 oct 2026
Le pides al agente que busque dónde se usa una función en el repositorio. Lee treinta ficheros, te enseña los treinta, y de todo eso tú vas a usar dos líneas. Las otras veintiocho lecturas se quedan en la conversación, ocupando sitio, hasta que la sesión empieza a ir peor.
Eso es lo que resuelve un subagente: hace el trabajo sucio en otra ventana y te devuelve solo la conclusión.
Un subagente es un ayudante especializado al que se le encarga una tarea lateral. La documentación lo plantea justo para el caso de arriba: cuando una tarea secundaria inundaría la conversación principal de resultados de búsqueda, registros o contenido de ficheros que no vas a volver a mirar. V
Cada subagente corre en su propia ventana de contexto, con su propio prompt de sistema, su propio acceso a herramientas y sus propios permisos. Trabaja por su cuenta y devuelve el resultado. V
Lo que entra en tu conversación es, por tanto, lo que él decida resumir. Esa es la ganancia y también el riesgo: si resume mal, tú no ves lo que descartó. I
La pregunta útil no es si la tarea es grande. Es si vas a volver a leer lo que produce.
Delega cuando la salida es material de paso: buscar en qué ficheros aparece algo, revisar un registro largo, leer una documentación entera para sacar un dato, recorrer un repositorio que no conoces. Lo que necesitas es la conclusión, no el camino.
No delegues cuando la salida es el trabajo. Si estás editando un fichero, la conversación necesita tener delante lo que hay en él. Un resumen de un fichero que vas a cambiar no sirve: lo que hace falta es el fichero.
Tampoco cuando la tarea depende de lo que ya habéis hablado. El subagente arranca en su propia ventana y no lleva encima tu conversación, así que lo que no le cuentes en el encargo, no lo sabe. I
En Claude Code esto ya ocurre solo en un sitio: en modo plan, la exploración del repositorio se delega a un subagente para que lo que lee se quede en otra ventana y la conversación principal siga siendo de solo lectura. V
Tu primer subagente, en cuatro pasos. Si solo te llevas una cosa de esta sección, que sea esta lista. Lo demás es el porqué de cada paso.
~/.claude/agents/ si lo quieres en todos tus proyectos; .claude/agents/ dentro de un proyecto si solo lo quieres ahí. V.md con el nombre que le vayas a dar, por ejemplo revisor-de-registros.md.No hay nada más que instalar ni que activar. Un subagente es un fichero de texto en una carpeta.
Antes de nada, una cosa que no se configura: lo de la ventana aparte y el resumen ocurre solo. No hay un ajuste que encender. En cuanto una tarea se delega a un subagente, esa tarea corre en su propia ventana y lo que vuelve es lo que él resume. V Definir uno sirve para otra cosa: para no tener que explicar el mismo encargo cada vez.
Dónde va el fichero. Un subagente es un fichero de texto en una de estas dos carpetas, y la que elijas decide quién lo ve: V
~/.claude/agents/ — disponible en todos los proyectos de tu máquina..claude/agents/ dentro de un proyecto — solo en ese proyecto.Qué forma tiene. Una cabecera entre tres guiones y, debajo, las instrucciones que quieres que lleve siempre. Así es un ejemplo de la propia documentación: V
--- name: code-improver description: Revisa ficheros y propone mejoras de legibilidad y rendimiento. Úsalo después de escribir o modificar código. tools: Read, Grep, Glob model: sonnet --- Eres un especialista en mejorar código. Para cada problema que encuentres, explícalo, enseña el código actual y propón una versión mejorada.
El cuerpo es su prompt de sistema: lo que sabe de sí mismo antes de recibir ningún encargo. Y description no es decoración: es lo que Claude lee para decidir si le pasa una tarea. V Si está vaga, no se usará; si dice cuándo conviene usarlo, sí.
Cómo se crea sin escribirlo a mano. Puedes pedírselo a Claude describiendo lo que quieres y dónde, y escribe el fichero con su nombre, su descripción, sus herramientas, su modelo y su prompt. V Después se usa nombrándolo: «usa el agente code-improver para revisar este proyecto». V
Los campos que más se tocan, además de los del ejemplo:
disallowedTools: lo que no puede usar, cuando es más corto decir eso que la lista entera.effort: con cuánto esfuerzo de razonamiento corre. Manda sobre el de la sesión, pero no sobre la variable de entorno CLAUDE_CODE_EFFORT_LEVEL. Vhooks y skills le enganchan los suyos, que no tienen por qué ser los de la sesión.permissionMode, mcpServers, maxTurns, memory, background, isolation y alguno más. VHay un detalle que ahorra contexto y casi nadie usa: si declaras un servidor MCP dentro de la cabecera del subagente en vez de en el fichero compartido, las descripciones de sus herramientas no entran en la conversación principal. El subagente tiene las herramientas; tú no pagas su sitio. V
Aquí está lo que más se malinterpreta. Un subagente manda sus propias peticiones, y cuentan para los mismos límites de uso que tu conversación principal. V No es trabajo gratis que ocurre aparte.
Lo que ahorra es sitio, no consumo. Tu ventana no se llena de material de paso, la sesión aguanta más y compacta menos. Lo que gasta sale del mismo sitio de siempre, y lanzar varios a la vez gasta proporcionalmente más. I
De ahí que la palanca más directa sea el modelo. El subagente de exploración que trae Claude Code puede redefinirse con un modelo más barato: basta declarar uno propio con model: haiku para que la exploración corra ahí. V
Y desde la versión 2.1.292, del 6 de octubre, se le puede pedir también el esfuerzo con el que corre, no solo el modelo. V Una búsqueda no necesita el mismo esfuerzo que un diseño.
Cuando la tarea es corta. Delegar tiene su propio coste: hay que explicarle el encargo entero, porque no sabe nada de lo vuestro. Para leer dos ficheros sale más caro el encargo que la tarea.
Cuando necesitas ver lo que vio. Si el detalle importa —una revisión de seguridad, un dato que hay que citar con su fuente— el resumen te deja sin la prueba. Ahí conviene que lea la conversación principal, o pedirle expresamente que devuelva las citas literales. I
Cuando lo que buscas es ahorrar cuota. No es lo que hace. Si el problema es que gastas demasiado, el camino es otro: menos herramientas conectadas, menos contexto por turno, un modelo más barato donde no haga falta el bueno. I
Y cuando ya tienes muchos. Cada subagente definido es una descripción más que Claude tiene que leer para decidir a quién delega. Tres bien escritos funcionan mejor que doce que se solapan. I
Hasta dónde llega: esta guía trata los subagentes de Claude Code, no la orquestación de varios agentes independientes entre sí. Y no mide tu consumo: dice de dónde sale, que es de la misma cuota.
Marca las que se cumplan en tu caso.
Usa el laboratorio de arriba con tu propio caso.
Las piezas que lo completan.
Si algo no encaja con tu caso, o si encuentras un error, escríbeme: se corrige y se anota.
Escríbeme