¿Qué es un subagente?
Un subagente es un agente auxiliar que un agente de código principal pone en marcha para delegar una tarea concreta. Tiene su propia ventana de contexto, sus instrucciones y sus permisos de herramientas, y al terminar devuelve solo un resumen, de modo que la conversación principal no se llena de detalles.
Cómo funciona
El agente principal encarga un trabajo a un subagente, como buscar en el código, ejecutar pruebas y resumir los fallos, o revisar un cambio. El subagente arranca con un contexto limpio; los archivos que lee y la salida de comandos que ve se quedan en su propia ventana, y el agente principal recibe solo el resultado. Varios subagentes pueden ejecutarse al mismo tiempo.
Definir subagentes en Claude Code
En Claude Code, los subagentes son archivos Markdown con frontmatter YAML. Los subagentes del proyecto están en .claude/agents/ y los personales en ~/.claude/agents/; también puedes gestionarlos con el comando /agents.
- name y description: cómo se llama el subagente y cuándo usarlo. El agente principal decide según esta descripción.
- tools: qué herramientas puede usar, por ejemplo solo las de lectura para un revisor.
- model: opcionalmente, un modelo distinto para el subagente.
- El cuerpo del archivo es el system prompt del subagente.
Cuándo ayudan los subagentes
Los subagentes rinden más cuando quieres mantener limpia la conversación principal.
- Investigaciones que leen muchos archivos: el detalle se queda en el subagente y el contexto principal sigue pequeño.
- Roles especializados: revisión de seguridad, escritura de pruebas, documentación.
- Exploración en paralelo: varios subagentes analizan módulos distintos a la vez.
Límites
Un subagente no ve el historial de la conversación principal, así que la tarea que recibe tiene que bastarse por sí sola. Como cada subagente construye su contexto desde cero, el uso total de tokens puede subir. Los subagentes suelen trabajar en la misma carpeta que el agente principal, por lo que varios subagentes que editan archivos en paralelo pueden estorbarse.
Subagentes en AgentVera
AgentVera hace visibles los subagentes que lanza Claude Code. La vista “Subagents” de la ventana de recorrido del proyecto y mapa del código lista los subagentes que inició un agente de Claude Code.
- De cada uno: tipo, si se ejecutó en segundo plano, estado, número de herramientas y duración, además de una línea de tiempo de sus pasos.
- Lee las transcripciones locales y, por ahora, funciona con agentes locales de Claude Code.
- La línea de tareas, la vista de equipo y el equipo en paralelo usan agentes separados y visibles en lugar de subagentes: cada uno tiene su propio panel y su conversación, y puedes hablarle directamente.
- Recorrido del proyecto y mapa de códigoConoce un proyecto con un recorrido guiado, mira las dependencias entre módulos y los archivos que más fallan.
- Task linePon tareas en cola y deja que cada una pase por los agentes de Analysis, Plan, Build y Review en orden.
- Vista de equipoConvierte tus agentes abiertos en un equipo con jefe, roles y líneas de reporte, y míralo trabajar en directo.
Preguntas frecuentes
¿En qué se diferencia un subagente de una sesión de agente separada?
El agente principal inicia un subagente y recibe su resultado; normalmente solo ves el resumen. Una sesión separada funciona por su cuenta y hablas con ella directamente.
¿Los subagentes ahorran tokens?
Mantienen pequeño el contexto de la conversación principal, lo que ayuda en sesiones largas. Pero la lectura del propio subagente también cuesta tokens, así que el uso total puede subir.
¿Puede un subagente editar archivos?
Depende de las herramientas que permita su definición. Un subagente con solo Read, Grep y Glob puede leer código, pero no cambiarlo.
¿Dónde debo poner los archivos de subagentes?
Los que tu equipo debe compartir van en .claude/agents/ del proyecto; los que solo usas tú, en ~/.claude/agents/. Los archivos de la carpeta del proyecto llegan a tu equipo a través de git.