Hay un límite que alcanzas en cualquier sesión de codificación con IA: la ventana de contexto. Después de una refactorización grande, varias rondas de pruebas y una revisión de código, el agente empieza a perder el hilo. Los subagentes de Claude Code solucionan esto dividiendo el trabajo en especialistas con su propia ventana de contexto, instrucciones y permisos de herramientas. Cada subagente hace una tarea, devuelve un resultado y mantiene limpio el hilo principal.
Esta guía se centra en la implementación: cómo crear un subagente personalizado como archivo de configuración, qué significa cada campo del frontmatter, cómo Claude decide delegar y cómo montar un flujo práctico donde un agente revisa código mientras otro escribe pruebas en paralelo. Si quieres la parte conceptual primero, consulta qué son los subagentes de Claude Code y por qué son importantes. Aquí nos enfocamos en construirlos y en convertir las pruebas de API en una puerta de verificación fiable.
En resumen
Creas un subagente de Claude Code escribiendo un archivo Markdown en .claude/agents/ con frontmatter YAML:
namedescription-
toolsopcional -
modelopcional
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. Esto te da:
- aislamiento de contexto
- paralelismo
- especialización
- control de permisos
Claude puede delegar automáticamente según la description, o puedes invocar un subagente por nombre. La referencia oficial está en los documentos de subagentes de Claude Code.
Subagentes en 60 segundos
Un subagente es una instancia separada a la que el agente principal de Claude Code le asigna una tarea.
Piensa en el agente principal como el ingeniero líder. Los subagentes son especialistas: revisión de código, pruebas de API, auditoría de seguridad, documentación, etc.
Tres propiedades hacen que valga la pena usarlos:
- Ventana de contexto propia. El subagente recibe la tarea y trabaja en su propio contexto. El hilo principal no se llena con lecturas de archivos, logs o resultados intermedios.
- Prompt de sistema personalizado. Puedes definir cómo debe comportarse: adversarial para revisión, estricto para pruebas, conservador para cambios de producción.
-
Herramientas configurables. Puedes dar a cada subagente solo las herramientas necesarias. Por ejemplo, un revisor puede tener
Read,GrepyGlob, pero noWrite.
La descripción general conceptual profundiza en el porqué. Esta guía aplica el mismo principio del marco de agente de Claude Code al nivel de tareas individuales.
Por qué usar subagentes
1. Aislamiento de contexto
Una sesión larga se degrada cuando el contexto se llena con:
- lecturas de archivos
- resultados de pruebas
- diffs grandes
- razonamientos intermedios
- logs de consola
Delegar una tarea voluminosa a un subagente mantiene ese ruido fuera del hilo principal. El agente principal recibe un resumen limpio en lugar de arrastrar miles de tokens adicionales.
Esto también ayuda con costos, porque no reutilizas un contexto hinchado en cada paso. Para más detalles, consulta las notas sobre cómo reducir costos de tokens del agente.
2. Paralelismo
Las tareas independientes no tienen que ejecutarse una tras otra.
Por ejemplo:
- revisar el módulo de pedidos
- escribir pruebas del endpoint
- actualizar documentación
- buscar regresiones en autenticación
Claude puede despachar varios subagentes al mismo tiempo. El tiempo total se acerca más a la duración de la tarea más lenta que a la suma de todas.
Los flujos de trabajo dinámicos llevan esta idea más lejos con muchos subagentes paralelos en una sola sesión.
3. Especialización
Un agente generalista puede hacer muchas cosas, pero un subagente bien configurado puede hacer una tarea de forma más consistente.
Ejemplos:
- Un revisor con instrucciones adversariales encuentra más errores.
- Un escritor de pruebas que conoce tus convenciones genera pruebas más útiles.
- Un auditor de seguridad con permisos de solo lectura reduce el riesgo de cambios accidentales.
La clave es crear especialistas pequeños, no un “superagente” que lo haga todo.
Cómo crear un subagente personalizado
Los subagentes son archivos Markdown.
Ubicación por proyecto:
.claude/agents/
Ubicación personal:
~/.claude/agents/
Cada archivo tiene:
- frontmatter YAML
- cuerpo con el prompt del sistema
Ejemplo: code-reviewer.md
---
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.
Campos del frontmatter
| Campo | Uso |
|---|---|
name |
Identificador del subagente. Lo usas para invocarlo explícitamente. |
description |
Texto que Claude lee para decidir cuándo delegar automáticamente. |
tools |
Lista de herramientas permitidas. Si lo omites, hereda herramientas del agente principal. |
model |
Modelo opcional para ese subagente. Útil para ajustar costo, velocidad y razonamiento. |
La description es especialmente importante. Escríbela como un disparador claro:
description: Usar después de editar código para revisar errores, seguridad y convenciones.
Mejor que:
description: Revisor de código.
El cuerpo del archivo es el prompt del sistema. Escríbelo como instrucciones operativas:
- qué debe hacer
- qué debe priorizar
- qué debe ignorar
- qué formato debe devolver
- qué nivel de confianza debe exigir
También puedes combinarlo con un design.md o AGENTS.md para que el subagente tenga acceso a convenciones del proyecto sin repetirlas en cada archivo.
Cómo invocar subagentes
Hay dos formas.
1. Delegación automática
Claude lee la description de los subagentes disponibles y decide cuándo usarlos.
Si acabas de editar código y tienes este subagente:
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.
Claude puede delegar al code-reviewer sin que lo pidas explícitamente.
2. Invocación explícita
También puedes nombrarlo directamente:
Usa el subagente code-reviewer para revisar los cambios del módulo de pedidos.
O:
Usa api-test-writer para generar pruebas del nuevo endpoint POST /orders.
Esto es útil cuando quieres forzar un especialista específico y no depender de la delegación automática.
En ambos casos, el subagente trabaja en su propio contexto y devuelve un resultado al hilo principal. Para flujos más deterministas, puedes combinar subagentes con comandos de barra o con el SDK. La descripción general de Claude Code cubre esa superficie de configuración.
Subagentes vs SDK de Agente vs flujos de trabajo dinámicos
Estos enfoques se solapan, pero no cumplen exactamente la misma función.
| Herramienta | Modelo de control | Mejor para |
|---|---|---|
| Subagentes | El modelo decide cuándo delegar, o tú nombras uno | Especialización en sesión y paralelismo ligero |
| Flujos de trabajo dinámicos | El modelo orquesta una gran expansión dentro de una sesión | Muchas tareas paralelas y barridos amplios |
| SDK de Agente | Tú escribes el flujo de control en código | Bucles deterministas, programados o desatendidos |
Usa subagentes cuando estés trabajando dentro de Claude Code y quieras añadir especialistas.
Usa el SDK de Agente de Claude cuando necesites control programático: ejecuciones programadas, loops deterministas o automatización sin intervención humana.
Si estás comparando una opción alojada con una propia, la comparación de agentes gestionados vs SDK de Agente resume las ventajas y desventajas.
Ejemplo práctico: revisión y pruebas en paralelo
Supón que el agente principal acaba de implementar un nuevo endpoint de pedidos.
Quieres dos cosas:
- Revisar el código.
- Generar y ejecutar pruebas de API.
No hay razón para hacerlo en secuencia. Define dos subagentes.
Ya tienes code-reviewer. Ahora crea api-test-writer.md:
---
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 é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 puedes pedir:
Revisa el nuevo endpoint de pedidos. Usa code-reviewer para revisar el diff y api-test-writer para escribir y ejecutar pruebas de API en paralelo.
El resultado esperado:
-
code-reviewerdevuelve problemas concretos con archivo, línea y gravedad. -
api-test-writerdevuelve pruebas generadas, resultado de ejecución y fallos. - El hilo principal recibe dos resúmenes, no todo el ruido intermedio.
Convertir el subagente de pruebas en una puerta de verificación
La parte importante no es solo que el subagente “escriba pruebas”. Lo importante es que ejecute una comprobación determinista.
Un buen subagente de pruebas debe devolver algo estructurado:
Resultado: FAILED
Pruebas ejecutadas:
- POST /orders con payload válido: PASSED
- POST /orders sin authentication: PASSED
- POST /orders con quantity negativa: FAILED
Fallo:
- Archivo: tests/orders.test.ts
- Caso: rechaza quantity negativa
- Esperado: 400
- Recibido: 201
Recomendación:
- Añadir validación de quantity > 0 en el handler de creación de pedidos.
Esto convierte el subagente en una puerta de verificación. La confianza del agente no cuenta; el resultado de la prueba sí.
Esta es la idea central de los bucles de agente de codificación: el agente implementa, ejecuta una verificación y corrige según el resultado.
Si conectas el subagente a una plataforma de pruebas de API, la retroalimentación mejora. Los equipos que usan Apidog pueden apuntar el subagente a escenarios de prueba para validar respuestas contra el esquema. También pueden enrutar llamadas de endpoint en vivo a través del depurador de agente de IA de Apidog para inspeccionar solicitudes como lo haría un tester humano.
La misma configuración puede envolverse en un loop desatendido, como en los flujos de trabajo de Claude que se ejecutan sin ti. Si quieres que la puerta de prueba sea consciente del esquema desde el inicio, descarga Apidog.
Mejores prácticas
Una responsabilidad por subagente
No crees un subagente que revise, pruebe, documente y despliegue.
Mejor:
code-reviewerapi-test-writersecurity-auditordocs-writer
Cada uno debe tener una tarea clara.
Escribe descripciones como disparadores
La description impulsa la delegación automática.
Malo:
description: Revisor.
Mejor:
description: Usar después de escribir o editar código para revisar errores, seguridad y convenciones del proyecto.
Concede el mínimo privilegio
No todos los subagentes necesitan escribir archivos o ejecutar comandos.
Ejemplo para un revisor:
tools: Read, Grep, Glob
Ejemplo para un escritor de pruebas:
tools: Read, Grep, Write, Bash
Si un subagente no necesita Write, no se lo des.
Usa el modelo adecuado
No todos los subagentes necesitan el modelo más potente.
- tareas mecánicas: modelo más rápido y barato
- razonamiento difícil: modelo más fuerte
- revisión crítica: modelo con mejor capacidad de análisis
Esto controla velocidad y costo.
Devuelve resultados estructurados
Pide formatos consistentes.
Ejemplo para revisión:
Resultado: ISSUES_FOUND | CLEAN
Problemas:
1. Severidad: alta
Archivo:
Línea:
Descripción:
Sugerencia:
Ejemplo para pruebas:
Resultado: PASSED | FAILED
Pruebas ejecutadas:
- Nombre:
- Estado:
- Motivo:
La salida estructurada es más fácil de leer, resumir y usar como entrada para el siguiente paso.
No anides demasiado
Evita subagentes que llamen a otros subagentes que llamen a otros subagentes. Se vuelve difícil de depurar y puede aumentar costo y latencia.
Mantén la jerarquía simple:
Agente principal
├── code-reviewer
├── api-test-writer
└── security-auditor
Estos patrones coinciden con los problemas de conexión descritos en la conexión de herramientas de flujo de trabajo agéntico.
Cuándo usar subagentes y cuándo no
Usa un subagente cuando la tarea sea:
- acotada
- independiente
- ruidosa
Buenos casos:
- revisar un diff grande
- escribir pruebas de un endpoint
- reproducir un bug
- auditar un módulo por problemas de seguridad
- validar una migración
- generar documentación desde código existente
Evítalo cuando la tarea sea:
- pequeña
- muy acoplada al contexto actual
- secuencial con el trabajo principal
Malos casos:
- renombrar una variable
- corregir una línea
- ajustar un import
- hacer una edición que el agente principal ya entiende completamente
Regla práctica:
Delega el trabajo que puedas describir en un párrafo y que tenga valor ejecutarlo en paralelo.
Un endpoint nuevo para revisar y probar encaja. Una errata no.
A medida que escalas a más subagentes concurrentes, los patrones de flujos de trabajo dinámicos se vuelven más relevantes.
Errores comunes
Descripciones vagas
Si la description es solo una etiqueta, Claude no sabrá cuándo delegar.
Usa disparadores explícitos.
description: Usar después de implementar o modificar endpoints para escribir y ejecutar pruebas de API.
Subagentes demasiado grandes
Un subagente que hace de todo pierde el beneficio de la especialización.
Divide por responsabilidad.
Heredar todas las herramientas
Si omites tools, el subagente puede heredar las herramientas del agente principal.
Eso puede estar bien para trabajo manual y de confianza, pero es arriesgado en flujos automatizados. Lista las herramientas explícitamente cuando puedas.
No tener subagente de verificación
Revisar código no sustituye ejecutar pruebas.
Incluye al menos un subagente que ejecute una verificación real:
- pruebas unitarias
- pruebas de API
- validación OpenAPI
- smoke tests
- checks de seguridad
Tratar subagentes como si fueran el SDK
Los subagentes son conversacionales y despachados por el modelo. Si necesitas un flujo determinista, programado o desatendido, usa el SDK de Agente.
El artículo de Anthropic Building effective agents explica la idea más amplia: la estructura alrededor del modelo suele ser más efectiva que simplemente usar 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, prompt de sistema y conjunto configurable de herramientas. Hace una tarea enfocada y devuelve un resultado.
¿Cómo creo un subagente de Claude Code?
Crea un archivo Markdown en:
.claude/agents/
o:
~/.claude/agents/
Añade frontmatter YAML con name, description, tools opcional y model opcional. Luego escribe el prompt del sistema en el cuerpo del archivo.
¿Cómo decide Claude qué subagente usar?
Claude lee la description de cada subagente disponible y delega cuando una tarea coincide. También puedes invocar uno explícitamente por nombre:
Usa el subagente code-reviewer.
Las descripciones claras hacen que la delegación automática sea más fiable.
¿Cuál es la diferencia entre subagentes y el SDK de Agente de Claude?
Los subagentes se usan dentro de una sesión de Claude Code y el modelo decide cuándo delegar.
El SDK de Agente es programático: tú defines el flujo de control en código para ejecuciones deterministas o desatendidas.
Usa subagentes para especialización interactiva. Usa el SDK para automatización.
¿Pueden los subagentes ejecutarse en paralelo?
Sí. El agente principal puede despachar varios subagentes al mismo tiempo para tareas independientes. Por ejemplo, revisión, pruebas y documentación pueden ocurrir en paralelo.
¿Cómo ayudan los subagentes con las pruebas de API?
Puedes definir un subagente que escriba y ejecute pruebas de API contra tu especificación OpenAPI. Así se convierte en una puerta de verificación que comprueba si un endpoint funciona realmente.
Apuntarlo a una plataforma como Apidog permite validar respuestas contra el contrato y obtener feedback consciente del esquema.
La conclusión
Los subagentes de Claude Code resuelven el problema de intentar meter todo en una sola ventana de contexto. Al dar a cada tarea su propio contexto, instrucciones y herramientas, conviertes un único asistente sobrecargado en un pequeño equipo de especialistas.
Empieza con dos:
- un revisor
- un probador
Escribe descripciones claras, concede solo las herramientas necesarias y haz que el subagente de pruebas ejecute una verificación real. Para endpoints, Apidog puede darle a esa puerta un esquema contra el que validar. Descárgalo y deja que un subagente demuestre que tu código funciona antes de que tú leas el diff.
Top comments (0)