Cómo agregar un flujo con subagentes en Claude Code (paso a paso)

Tu sesión principal de Claude Code es un espacio de trabajo compartido, y cada tarea ruidosa que corres ahí (una pasada de seguridad sobre un diff, una corrida de tests que falla a ratos, una auditoría de dependencias de cuarenta archivos) te quema contexto que preferirías gastar en el problema de verdad. Un subagente resuelve eso: es un asistente con nombre, con su propio prompt, su propia lista de herramientas permitidas y su propia ventana de contexto desechable, así que el desorden se queda en su ventana y a la tuya solo regresa un resumen limpio. Al terminar esta guía vas a tener un subagente funcionando, con commit en un repo, invocado de dos formas y conectado a un flujo real de revisar antes de hacer commit, más los modos de falla que hacen que la gente se rinda con los subagentes demasiado pronto.

Esto no es una función que "prendes". Es un archivo pequeño y un contrato claro. Si le aciertas al contrato, delegar se siente de lo más natural. Si lo erras, lo único que armaste fue un agente solo, más lento y disfrazado.

01 · Requisitos y qué es realmente un subagente

Antes de los pasos, asegúrate de tener las piezas en su lugar. Nada de esto es complicado, pero saltarte la que no es te quema una sesión completa.

• Claude Code instalado y autenticado. Corre claude dentro de un directorio de proyecto y confirma que te sale el prompt.
• Un proyecto real donde trabajar, idealmente un repo git. Los subagentes brillan en tareas con archivos que leer. En una carpeta vacía no sirven de nada.
• Permiso de escritura en la raíz del proyecto, porque ahí es donde los subagentes viven, en un directorio .claude/agents/.
• Una tarea clara y acotada en mente. "Revisa todo mi codebase" no es trabajo para un subagente. "Revisa un diff buscando inyección, secretos y chequeos de authz que falten" sí lo es.

Un subagente son tres cosas y nada más: un name, un system prompt que define su trabajo y una lista de herramientas permitidas que limita lo que puede hacer. Corre en una ventana de contexto nueva que no puede ver tu conversación principal, solo el prompt que lleva encima y la tarea que le entregas. Ese aislamiento es justamente la gracia del asunto. El subagente se traga todo el ruido y te devuelve una conclusión. El ruido se queda muriendo en su ventana.

02 · Crea el archivo del agente

Los subagentes son archivos markdown con frontmatter YAML. Crea el directorio y el archivo:

mkdir -p .claude/agents
$EDITOR .claude/agents/security-reviewer.md

Ahora escribe el agente. El frontmatter es el contrato que lee la máquina. El cuerpo es el system prompt:

---
name: security-reviewer
description: Revisa un diff por inyección, secretos filtrados y chequeos de authz faltantes. Úsalo antes de cualquier commit que toque manejo de input, auth o queries.
tools: Read, Grep, Bash
model: sonnet
---

Revisas código solo por problemas de seguridad. No refactorizas, no renombras
ni arreglas estilo. Por cada hallazgo, devuelve exactamente un bloque:

- archivo:línea
- severidad: baja | media | alta
- el riesgo concreto en una frase
- un arreglo específico (un diff o una frase, no "considera mejorar esto")

Si no encuentras nada, dilo claro. Nunca inventes hallazgos para verte útil.
Corre Bash solo para inspección de lectura (git diff, grep). Nunca escribas archivos.

Cuatro campos son los que cargan con el peso:

1. name va en minúsculas, con guiones, único. Así es como lo vas a invocar.
2. description es la línea más importante de todas. Claude la lee para decidir cuándo delegar, así que arranca con el verbo y deja clara la condición que lo dispara. "Revisa un diff… Úsalo antes de cualquier commit que toque auth" le gana por mucho a "Un agente de seguridad."
3. tools es la lista de herramientas permitidas. Dale solo lo que la tarea necesita. Un revisor lee y hace grep. No tiene por qué cargar con Write ni Edit.
4. model es tu perilla de velocidad y costo. Usa sonnet para la mayoría del trabajo delegado, reserva el modelo más pesado para razonamiento de verdad difícil, y usa haiku para pasadas baratas de alto volumen.

03 · Invócalo, de dos formas

Puedes entregarle trabajo a un subagente de forma explícita o dejar que Claude lo enrute por su cuenta.

Explícita: lo nombras en tu mensaje. Así agarras el hábito y así pruebas el agente de forma aislada:

Usa el subagente security-reviewer sobre el diff en stage. Este es el contexto
que necesita: este PR agrega un endpoint público /api/export que lee un param
"format" del usuario y llama por shell a un convertidor. Enfócate ahí.

Fíjate cuánto contexto viaja con el mensaje. El subagente no puede ver tu conversación, así que ese párrafo es todo su mundo. La causa número uno de una corrida inútil de subagente es una instrucción de una sola línea que da por sentado que el agente vio todo lo que vienes hablando.

Automática: si la description está bien afilada, Claude va a recurrir al agente por su cuenta cuando la conversación encaje. Lo vas a ver delegar, el subagente trabaja en su propio contexto, y un resumen aterriza de vuelta en tu hilo. Esa es la recompensa: las cuarenta líneas de salida de grep y el filtrado de falsos positivos nunca tocan tu ventana principal.

Agentes de proyecto vs. personales

Un archivo en .claude/agents/ dentro del repo se comparte con todo el que lo clone. Un archivo en ~/.claude/agents/ es tuyo en todos tus proyectos. Pon los estándares del equipo (el revisor de seguridad, el corredor de tests) en el repo, y deja los ayudantes personales en tu home. Cuando los dos definen el mismo name, gana el archivo del proyecto.

04 · Ejemplo resuelto: revisar antes del commit

Aquí va el workflow de punta a punta. La meta: que nada llegue a commit sin una pasada de seguridad, y que esa pasada nunca te ensucie la sesión principal.

1. Terminas un cambio y lo pones en stage. En tu hilo principal dices: "Revisa el diff en stage con el subagente security-reviewer antes de que haga commit."
2. Claude levanta el subagente con un contexto nuevo. Corre git diff --staged, hace grep de los patrones obvios, lee los archivos tocados y hace la criba.
3. El subagente devuelve solo su lista de hallazgos, pongamos dos medios y uno alto, como resumen. El diff crudo y todo su razonamiento se quedan en su ventana.
4. Lees tres hallazgos ordenaditos en vez de hacer scroll por toda la investigación del agente. Arreglas el alto, asumes el riesgo en uno de los medios, y haces commit.

La ganancia no es que Claude encontró bugs. Tu hilo principal también podía hacerlo. La ganancia es que los encontró sin gastarte el contexto en la búsqueda, así que la sesión que hace el trabajo de feature de verdad se mantiene afilada por más tiempo. Encadena un segundo agente, un test-runner que devuelva pasa/falla más el primer assert que truena, y ya tienes una puerta de calidad delegada que casi no le cuesta atención a tu hilo principal.

05 · Errores comunes

El mismo puñado de errores explica casi todas las historias de "los subagentes no me sirvieron de nada".

• Las instrucciones vagas. El agente no puede ver tu chat. Un "revisa esto" no le deja nada con qué trabajar. Dale el contexto por adelantado, siempre.
• Exceso de herramientas. Darle a cada agente el conjunto completo de herramientas te quita justo la seguridad que la lista permitida venía a darte, y un revisor con acceso a Write tarde o temprano va a "ayudarte" editándote el código. Acótalo.
• Delegar lo trivial. Levantar un subagente implica volver a leer contexto y te cuesta un viaje de ida y vuelta. Para una tarea de treinta segundos, ese costo extra es pérdida pura. Delega cuando la limpieza, mantener el ruido fuera de tu ventana principal, vale más que el arranque.
• El agente por vanidad. Cinco subagentes para un problema que uno solo resolvería en secuencia te sale más lento, no más rápido. Paraleliza solo el trabajo que de verdad es independiente. Si no, una sola tarea encadenada está perfecta.
• El que se autocalifica. Un agente que hace el trabajo y además dictamina que quedó correcto es puro teatro. Si la corrección importa, el verificador es un rol aparte, con su propio prompt.

Los subagentes no hacen a Claude Code más inteligente. Lo hacen más ordenado. La disciplina que te obligan a tener (un trabajo acotado, una lista de herramientas ajustada, unas instrucciones que se bastan por sí solas, una forma que devolver) es la misma que hace que cualquier delegación funcione, sea humana o máquina. Empieza con un solo agente bien acotado y con commit en un repo, úsalo durante una semana, y vas a sentir exactamente dónde encaja el siguiente.