Cómo Crear Subagentes de Código Claude Personalizados (Guía de Configuración)

Hay un límite que alcanzas con cualquier sesión de codificación de IA: la ventana de contexto. Llena una conversación con una refactorización extensa, tres rondas de resultados de pruebas y una revisión de código, y el agente comienza a perder el hilo. Los subagentes de Claude Code son la solución. En lugar de un agente que lo maneja todo en un solo contexto, activas trabajadores enfocados, cada uno con su propia ventana de contexto, sus propias instrucciones y sus propios permisos de herramientas. Hacen un trabajo, devuelven un resultado y mantienen el hilo principal limpio.

Esta es la guía práctica de construcción. Cómo crear un subagente personalizado como un archivo de configuración, qué hace cada campo del frontmatter, cómo Claude decide delegarle y cómo configurar un sistema práctico donde un agente revisa el código mientras otro escribe pruebas en paralelo. Si deseas primero la descripción conceptual, nuestro artículo sobre qué son los subagentes de Claude Code y por qué son importantes cubre los conceptos básicos. Aquí nos centramos en construirlos y en el ángulo de las pruebas de API que convierte un subagente de prueba en un paso de verificación en el que puedes confiar.

En resumen

Creas un subagente de Claude Code escribiendo un archivo Markdown en .claude/agents/ con frontmatter YAML: un name, una description que le dice a Claude cuándo delegar, una tools permitida opcional y un model opcional. El cuerpo del archivo se convierte en el prompt del sistema del subagente. Cada subagente se ejecuta en su propia ventana de contexto con sus propias herramientas, lo que te proporciona aislamiento de contexto, paralelismo y especialización. Claude delega automáticamente según la descripción, o invocas un subagente por su nombre. La referencia oficial son los documentos de subagentes de Claude Code.

Subagentes en 60 segundos

Un subagente es una instancia de agente separada a la que el agente principal de Claude Code le asigna una tarea. El agente principal es el ingeniero principal; los subagentes son especialistas que incorpora. El especialista trabaja en su propia conversación, con su propia ventana de contexto y prompt del sistema, y luego devuelve solo el resultado. Tres propiedades hacen que valga la pena configurarlos:

• Su propia ventana de contexto. Un subagente comienza de nuevo solo con la tarea que se le asigna, por lo que el hilo principal nunca se llena con su trabajo intermedio.
• Un prompt de sistema personalizado. Tú configuras cómo se comporta: un revisor que busca agujeros de seguridad, un escritor de pruebas que sigue tus convenciones.
• Herramientas configurables. Otorgas a cada subagente solo las herramientas que necesita, por lo que un revisor no puede escribir y un ejecutor de pruebas solo tiene el acceso de shell suficiente.

Esa es la base conceptual; la descripción general conceptual profundiza en el porqué. El resto de esta guía trata sobre cómo construirlos, lo cual es el mismo principio detrás del marco de agente de Claude Code aplicado al nivel de tareas individuales.

Por qué usar subagentes

Tres razones, y se suman.

Aislamiento de contexto. Una sesión larga se degrada a medida que la ventana de contexto se llena. Cada lectura de archivo, cada ejecución de prueba, cada divagación consume presupuesto y diluye el enfoque. Delegar una tarea voluminosa a un subagente mantiene todo ese trabajo en el contexto del subagente, no en el principal. El agente principal recibe un resumen limpio en lugar de 50,000 tokens de ruido intermedio. Ese aislamiento también es una palanca de costos, ya que no estás arrastrando un contexto hinchado a cada paso. Nuestras notas sobre la reducción de costos de tokens del agente profundizan en la economía.

Paralelismo. Las tareas independientes no necesitan ejecutarse una tras otra. Un agente principal puede despachar varios subagentes a la vez: revisar este módulo mientras se prueba aquel mientras se documenta un tercero. El tiempo real de ejecución se reduce a la tarea individual más lenta en lugar de la suma. Los flujos de trabajo dinámicos de Claude Code llevan esto al límite, extendiendo cientos de subagentes paralelos desde una sola sesión.

Especialización. Un agente general es bueno en todo y excelente en nada. Un subagente con un prompt del sistema ajustado y las herramientas adecuadas es excelente en una cosa. Un revisor impulsado a ser adversario encuentra más errores que un generalista que echa un vistazo al diff. Un escritor de pruebas que conoce tu estilo de aserción produce pruebas que realmente conservarás. Construyes un pequeño equipo de especialistas en lugar de un generalista sobrecargado.

Cómo crear un subagente personalizado

Los subagentes son archivos Markdown simples. Coloca los de nivel de proyecto en .claude/agents/ y los personales en ~/.claude/agents/. Cada archivo tiene frontmatter YAML y un cuerpo que se convierte en el prompt del sistema del subagente.

Aquí tienes un revisor de código:

---
name: code-reviewer
description: Revisa los cambios de código en busca de errores, problemas de seguridad y violaciones de convenciones. Usar después de escribir o editar código.
tools: Read, Grep, Glob
model: sonnet
---

Eres un revisor de código senior. Cuando se te da un diff o un conjunto de archivos:

1. Busca errores de corrección, agujeros de seguridad y casos extremos omitidos.
2. Verifica que el código coincida con las convenciones existentes del proyecto.
3. Informa solo los problemas de alta confianza, clasificados por gravedad.

Sé específico. Cita el archivo y la línea. No des una aprobación automática.

Los campos del frontmatter:

• name — el identificador que usas para invocarlo.
• description — este es el importante. Claude lo lee para decidir cuándo delegar automáticamente. Escríbelo como un disparador claro ("Usar después de escribir código"), no como una etiqueta vaga.
• tools — la lista permitida. Omítelo para heredar las herramientas del agente principal, o lista las específicas para restringir. Un revisor que no puede escribir código no puede cambiarlo accidentalmente.
• model — opcionalmente, fija un modelo. Usa un modelo más barato y rápido para subagentes mecánicos y uno más fuerte para razonamientos difíciles.

El cuerpo es el prompt del sistema. Aquí es donde reside la especialización, así que escríbelo como si le dieras instrucciones a un nuevo empleado: qué hacer, qué priorizar, qué evitar. Combinarlo con un design.md o AGENTS.md del proyecto le da al subagente tus convenciones sin tener que repetirlas en cada archivo.

Cómo invocar subagentes

Hay dos formas en que se ejecuta un subagente.

Delegación automática. Claude lee el campo description de cada subagente disponible y delega por sí mismo cuando una tarea coincide. Termina de editar un archivo y el agente principal puede entregar el diff a tu code-reviewer sin que se le diga, porque la descripción dice "usar después de escribir código". Las buenas descripciones impulsan una buena delegación.

Invocación explícita. También puedes nombrarlo directamente: "usa el subagente code-reviewer en los cambios del módulo de pedidos". Así es como fuerzas a un especialista específico cuando no quieres dejar la delegación al azar.

De cualquier manera, el subagente se ejecuta en su propio contexto, realiza el trabajo y devuelve un resultado al hilo principal. Ves cómo se produce el traspaso y puedes configurar cuánto detalle se muestra. Para encadenar subagentes en secuencias deterministas y repetibles, los comandos de barra y el SDK te brindan más control que la solicitud ad hoc; la descripción general de Claude Code cubre la superficie de configuración.

Subagentes vs el SDK de Agente vs flujos de trabajo dinámicos

Estos se superponen, así que aquí te mostramos cuándo encaja cada uno.

Los subagentes son la opción conversacional dentro de la sesión: estás trabajando en Claude Code y quieres uno o dos especialistas. Cuando necesitas un bucle programático que se ejecute según un horario sin presencia humana, recurres al SDK de Agente de Claude y escribes la orquestación tú mismo. Si estás sopesando una opción alojada frente a desarrollar la tuya propia, nuestra comparación de agentes gestionados vs SDK de Agente desglosa las ventajas y desventajas. Los tres no son tanto competidores como peldaños en una escalera desde lo interactivo hasta lo totalmente automatizado.

Un ejemplo práctico: revisión y escritura de pruebas en paralelo

Vamos a juntarlo. Supongamos que el agente principal acaba de implementar un nuevo endpoint de pedidos. Quieres que se revise y pruebe, y no hay razón para que eso suceda en secuencia.

Define dos subagentes. El code-reviewer anterior, más un escritor de pruebas:

---
name: api-test-writer
description: Escribe casos de prueba de API para endpoints nuevos o modificados. Usar después de implementar un endpoint.
tools: Read, Grep, Write, Bash
model: sonnet
---

Eres un escritor de pruebas de API contra la especificación OpenAPI del proyecto.

1. Lee la especificación y la implementación del endpoint.
2. Escribe pruebas que cubran el éxito, errores de validación y autenticación.
3. Afirma los códigos de estado y valida los cuerpos de respuesta contra el esquema.
4. Ejecuta el conjunto y reporta aprobado/fallido con razones.

Ahora el agente principal despacha ambos a la vez: el revisor lee el diff mientras el escritor de pruebas lee la especificación y escribe la cobertura. Dos especialistas, dos contextos aislados, ejecutándose en paralelo. El hilo principal permanece limpio y recibe dos resúmenes: un informe de revisión y un resultado de prueba.

Ese resultado de la prueba es la parte que hace que esto sea fiable. Un subagente que ejecuta tu suite de API es una puerta de verificación, la comprobación determinista que dice si el endpoint realmente funciona en lugar de si parece que está hecho. Esta es la idea central de los bucles de agente de codificación: la propia confianza del agente no cuenta, el veredicto de la puerta sí. Conecta el subagente de prueba a una plataforma de prueba de API real y la retroalimentación será más precisa. Los equipos que usan Apidog dirigen el subagente a un escenario de prueba de Apidog para que cada respuesta sea validada por el esquema, y enrutan las llamadas de endpoint en vivo del agente a través del depurador de agente de IA de Apidog para que inspeccione las solicitudes como lo haría un probador humano. Toma esa misma configuración, envuélvela en un bucle, y tendrás el flujo de trabajo desatendido que construimos en los flujos de trabajo de Claude que se ejecutan sin ti. Descarga Apidog si quieres que la puerta de prueba sea consciente del esquema de fábrica.

Mejores prácticas

Algunos hábitos mantienen a los subagentes útiles en lugar de caóticos.

• Una responsabilidad por subagente. Un revisor revisa. Un probador prueba. No construyas un subagente que lo haga todo; eso es solo el agente principal con pasos adicionales.
• Escribe descripciones para la delegación. El campo description es cómo Claude decide llamar a tu subagente. Que sea un disparador claro, no un título. "Usar después de editar código para revisar errores" es mejor que "Revisor de código".
• Concede el mínimo privilegio. Lista solo las herramientas que cada subagente necesita. Un revisor sin acceso de escritura no puede cambiar lo que está revisando. Esto importa más cuando las ejecuciones son desatendidas.
• Fija el modelo adecuado para cada tarea. Los subagentes mecánicos pueden ejecutarse en un modelo más rápido y barato. Guarda el modelo más potente para los subagentes que realizan razonamientos complejos. Esto controla tanto la velocidad como el costo.
• Devuelve resultados estructurados. Pide a los subagentes que informen en un formato consistente (un veredicto, una lista de problemas, un aprobado/fallido). La salida estructurada es más fácil de procesar para el agente principal y para ti.
• No anides demasiado. Que los subagentes llamen a subagentes que llamen a subagentes se vuelve difícil de seguir y costoso. Mantén la jerarquía superficial.

Estos reflejan los patrones de conexión que cubrimos en la conexión de herramientas de flujo de trabajo agéntico, y son válidos tanto si tienes dos subagentes como veinte.

Cuándo usar subagentes (y cuándo no)

Los subagentes son una herramienta, no un predeterminado. Saber cuándo omitirlos mantiene tu configuración rápida y económica.

Usa un subagente cuando una tarea sea acotada, independiente y ruidosa. Una revisión de código es acotada (tiene un final claro), independiente (no necesita el estado de ejecución del hilo principal) y ruidosa (genera mucha lectura intermedia que no quieres que obstruya el contexto principal). Lo mismo ocurre con escribir un conjunto de pruebas, reproducir un error o auditar un módulo en busca de problemas de seguridad. Estas son delegaciones perfectas: aíslan el trabajo, obtienen un veredicto.

Evita el subagente cuando la tarea sea pequeña, muy acoplada o secuencial con el trabajo principal. Renombrar una variable, corregir un error de una línea o cualquier cosa en la que el agente principal ya tenga el contexto necesario a la vista no se beneficia de un traspaso. Generar un subagente ahí solo añade latencia y un viaje de ida y vuelta de contexto sin ninguna ganancia. Si el agente principal tuviera que explicar la mitad de la conversación para instruir al subagente, mantenlo en el hilo principal.

La regla general: delega el trabajo que sea lo suficientemente autocontenido como para describirlo en un párrafo y lo suficientemente valioso como para ejecutarse en paralelo. Un nuevo endpoint para revisar y probar encaja. Una corrección de errata no. A medida que escalas a muchos subagentes concurrentes, los patrones de orquestación en los flujos de trabajo dinámicos toman el control, pero el mismo juicio se aplica: paraleliza lo independiente, mantén unido el trabajo acoplado.

Errores comunes

• Descripciones vagas. Si la description es una etiqueta, la delegación automática no se activará cuando lo esperes. Escríbela como un disparador de uso.
• Un subagente hinchado. Amontonar cada tarea en un solo subagente anula el beneficio de la especialización. Divide por responsabilidad.
• Heredar todas las herramientas por defecto. Dejar las tools sin configurar le da a un subagente todo lo que tiene el agente principal. Está bien para trabajos de confianza, pero arriesgado para cualquier cosa automatizada. Lista explícitamente.
• Ningún subagente de verificación. Una configuración de revisión y construcción sin una puerta de prueba envía código que parece correcto y se rompe en los bordes. Incluye siempre un subagente que realmente ejecute las pruebas.
• Tratar a los subagentes como el SDK. Los subagentes se despachan por modelo y están en sesión. Si necesitas un flujo de control determinista y programado, ese es el trabajo del SDK del Agente, no un montón de subagentes.

Haz esto bien y un puñado de subagentes bien definidos convierte a Claude Code de un único asistente ocupado en un equipo pequeño y enfocado. El artículo de Anthropic Building effective agents argumenta el caso más amplio: la estructura alrededor del modelo es mejor que un prompt más grande.

Preguntas frecuentes

¿Qué es un subagente de Claude Code? Es una instancia de agente separada a la que delega el agente principal de Claude Code. Cada subagente tiene su propia ventana de contexto, un prompt de sistema personalizado y un conjunto configurable de herramientas. Realiza una tarea enfocada y devuelve el resultado, manteniendo limpia la conversación principal y permitiéndote ejecutar especialistas en paralelo.

¿Cómo creo un subagente de Claude Code? Crea un archivo Markdown en .claude/agents/ (proyecto) o ~/.claude/agents/ (personal). Añade el frontmatter YAML con name, description, tools opcionales y model opcional, luego escribe el prompt del sistema en el cuerpo. La descripción le dice a Claude cuándo delegar automáticamente.

¿Cómo decide Claude qué subagente usar? Lee el campo description de cada subagente disponible y delega automáticamente cuando una tarea coincide. También puedes invocar uno explícitamente por su nombre, como "usa el subagente code-reviewer". Las descripciones claras, al estilo de un disparador, hacen que la delegación automática sea fiable.

¿Cuál es la diferencia entre los subagentes y el SDK de Agente de Claude? Los subagentes están en sesión y son despachados por el modelo: estás trabajando en Claude Code y este incorpora especialistas. El SDK de Agente es programático, donde escribes el flujo de control en código para ejecuciones deterministas o desatendidas. Usa subagentes para especialización interactiva, el SDK para bucles programados.

¿Pueden los subagentes ejecutarse en paralelo? Sí. El agente principal puede despachar varios subagentes a la vez para tareas independientes, de modo que la revisión, las pruebas y la documentación ocurren juntas en lugar de en secuencia. Para una expansión a gran escala, los flujos de trabajo dinámicos de Claude Code extienden esto a muchos subagentes paralelos en una sola sesión.

¿Cómo ayudan los subagentes con las pruebas de API? Define un subagente que escriba y ejecute tus pruebas de API contra la especificación OpenAPI. Se convierte en una puerta de verificación que comprueba si un endpoint realmente funciona, no solo si parece terminado. Apuntarlo a una plataforma como Apidog hace que la retroalimentación sea consciente del esquema, de modo que cada respuesta se valida contra el contrato.

La conclusión

Los subagentes de Claude Code resuelven el problema de que una ventana de contexto no puede contenerlo todo. Al dar a cada tarea su propio contexto, instrucciones y herramientas, cambias un único agente sobrecargado por un pequeño equipo de especialistas que trabajan en paralelo e informan de forma limpia. La configuración es solo un archivo Markdown, y la recompensa es el enfoque, la velocidad y la capacidad de asignar el modelo adecuado al trabajo adecuado.

Empieza con dos: un revisor y un probador. Escribe descripciones concisas para que Claude delegue por sí mismo, concede a cada uno solo las herramientas que necesita, y haz del probador una verdadera puerta de verificación apuntándolo a tu suite de API. Para cualquier cosa que afecte a los endpoints, Apidog le da a esa puerta un esquema contra el que comprobar; descárgalo y deja que un subagente de prueba demuestre que tu código funciona antes de que leas el diff.