Subagentes en Claude Code: delegá como un jefe

En este tutorial vas a crear tu primer subagente en Claude Code: un especialista con su propia memoria de trabajo al que el agente principal le delega tareas, igual que un jefe delega en su equipo. Es para vos si ya usás Claude Code a diario y sentís que tus conversaciones largas se enredan porque una sola IA está haciendo demasiadas cosas a la vez.

Antes de empezar

• Claude Code instalado y funcionando en tu compu (si todavía no lo tenés, empezá por ahí).
• Un proyecto real donde trabajar: una carpeta con código, contenido o documentos tuyos.
• Haber usado Claude Code al menos unas semanas. Los subagentes son nivel avanzado; sin la base te vas a frustrar.
• Saber que esto consume más de tu plan: cada subagente es una conversación aparte que gasta tokens (las "unidades" de texto que el modelo procesa y que tu plan mide). Delegar mucho = consumir más.

Un concepto antes de arrancar: un subagente es una instancia separada del modelo, con su propio contexto limpio y sus propias instrucciones. El agente principal le pasa una tarea, el subagente trabaja solo y devuelve un resumen con el resultado. Lo importante: lo que el subagente lee y procesa NO ensucia la conversación principal. Esa es la magia.

Paso 1 — Entendé cuándo delegar (y cuándo no)

Delegá cuando la tarea es pesada en lectura y liviana en resultado: revisar veinte archivos para responder una pregunta, buscar dónde está un error, auditar un texto largo. El subagente se traga todo ese material en su propio contexto y a vos te llega solo la conclusión.

No delegues cuando la tarea necesita el hilo completo de tu conversación: el subagente arranca de cero, no sabe nada de lo que vinieron charlando. Si la tarea depende de diez decisiones que tomaron juntos, hacela en el chat principal o pasale esas decisiones por escrito en el encargo.

Paso 2 — Creá el subagente con /agents

Dentro de Claude Code escribí:

/agents

Se abre un menú para crear un agente nuevo. Elegí si va a vivir en el proyecto (solo disponible ahí) o a nivel usuario (disponible en todos tus proyectos). Te va a pedir nombre, descripción y qué herramientas puede usar.

Por debajo, cada subagente es un simple archivo de texto en la carpeta .claude/agents/ de tu proyecto. Podés editarlo a mano cuando quieras:

---
name: revisor-de-estilo
description: Revisa textos en español y devuelve una lista
  de correcciones de tono, tildes y claridad. Usalo siempre
  que haya que revisar contenido antes de publicar.
tools: Read, Grep
---

Sos un corrector de estilo exigente. Leés el texto que te
indiquen y devolvés SOLO una lista numerada de problemas
con su corrección propuesta. No reescribís el texto entero.

Paso 3 — Escribí la descripción como un aviso de trabajo

La description no es decoración: es lo que el agente principal lee para decidir cuándo delegarle algo a este subagente. Si ponés "ayuda con textos", nunca va a saber cuándo usarlo. Escribila como si contrataras a alguien: qué hace, con qué material, qué entrega y en qué situación hay que llamarlo. Frases tipo "usalo siempre que…" funcionan muy bien como gatillo.

Paso 4 — Dale solo las herramientas que necesita

En el ejemplo de arriba el revisor solo puede leer archivos y buscar texto. No puede escribir, no puede ejecutar comandos. Eso no es desconfianza paranoica: es el mismo principio que en cualquier equipo — cada rol con los permisos de su rol. Un subagente investigador no necesita permiso de escritura; uno que corre pruebas no necesita tocar tu contenido. Menos herramientas también significa menos formas de que se distraiga.

Paso 5 — Delegá, esperá el resumen y verificá vos

Ahora pedile algo al agente principal que encaje con la descripción:

Revisá los tres artículos de la carpeta borradores
antes de publicarlos.

Vas a ver que delega al revisor (o pedíselo explícito: "usá el subagente revisor-de-estilo"). Cuando vuelva el resumen, no lo aceptes a ciegas: abrí uno de los archivos y comprobá que las correcciones existen y tienen sentido. Delegar no es desentenderse — eso también es igual que con un equipo humano.

Errores comunes

• El subagente "todero". Un agente que "ayuda con todo" no sirve para nada concreto. Arreglo: un trabajo por agente; si aparece otro trabajo, otro agente.
• Esperar que recuerde la conversación. Arranca en blanco, siempre. Arreglo: incluí en el encargo el contexto mínimo que necesita (o guardá las decisiones en un archivo y decile que lo lea).
• Delegar todo por deporte. Para tareas cortas, delegar es más lento y más caro que hacerlo directo. Arreglo: delegá solo lo pesado en lectura o lo repetitivo.
• Confiar en el resumen sin mirar. El subagente puede decir "listo" y no estar listo. Arreglo: verificá una muestra del trabajo con tus propios ojos, siempre.

Siguiente paso

Cuando domines un subagente, el salto natural es coordinar varios a la vez: equipos que trabajan en paralelo sobre partes distintas de un problema, con un consolidador que junta todo al final. Ahí entrás al mundo de la orquestación — y la pregunta deja de ser "cómo" y pasa a ser "cuándo vale la pena".