Subagentes de Claude Code: cómo crearlos y usarlos

Los subagentes de Claude Code son ayudantes a los que la sesión principal de Claude Code encarga una única tarea. Cada uno se ejecuta en su propia ventana de contexto, con su propio system prompt, lista de herramientas y modelo, y solo su respuesta final vuelve a la conversación principal. Defines un subagente como un archivo Markdown en .claude/agents/, y Claude lo usa automáticamente cuando la tarea coincide con su descripción, o cuando lo pides por su nombre.

Este artículo explica cómo funcionan los subagentes, el formato del archivo, los campos tools y model, cómo llamarlos y la diferencia entre un subagente y un agente separado que se ejecuta junto al primero. Los datos proceden de la documentación oficial de subagentes. Para la versión de un párrafo, consulta la entrada del glosario sobre subagentes.

Cómo funcionan los subagentes

Cuando Claude decide delegar, llama a la herramienta Agent (que se llamaba Task antes de la versión 2.1.63) con un breve encargo. El subagente empieza con un contexto nuevo. Recibe su propio system prompt, el mensaje de delegación, tu CLAUDE.md, el estado de git y las skills que le hayas precargado. No ve el historial de la conversación principal.

Después trabaja en la tarea con las herramientas que tiene permitidas y devuelve un único resultado. Todo lo que leyó por el camino, como decenas de archivos, salidas largas de grep o logs de tests, se queda en su propio contexto. Ese es el motivo principal para usar subagentes: la conversación principal recibe un resumen, no el ruido.

Algunos límites que conviene conocer:

• Los subagentes pueden iniciar sus propios subagentes, hasta tres niveles de profundidad por defecto.
• Por defecto pueden ejecutarse hasta 20 a la vez.
• Sus peticiones cuentan para los mismos límites de uso que la sesión principal.
• Un subagente puede ejecutarse en primer plano, donde el agente principal espera, o en segundo plano mientras el agente principal sigue trabajando.

Subagentes integrados

Claude Code incluye algunos subagentes que puedes usar sin escribir nada:

Explore es el que verás con más frecuencia. Cuando Claude necesita encontrar dónde se define algo o cómo funciona una funcionalidad a través de varios archivos, a menudo se lo encarga a Explore para que los volcados de archivos no acaben en tu contexto principal.

Dónde viven los archivos de subagente

Los subagentes son archivos Markdown con frontmatter YAML. Claude Code los carga desde varios sitios y, cuando dos tienen el mismo nombre, gana el que está más arriba en esta lista:

Los subagentes de proyecto en .claude/agents/ son los que conviene incluir en el repositorio, para que todo el equipo comparta el mismo revisor o el mismo ejecutor de tests.

El formato del archivo de subagente

Solo name y description son obligatorios. El cuerpo que sigue al frontmatter es el system prompt del subagente.

---
name: code-reviewer
description: Reviews code changes for bugs, security issues and readability. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When called:

1. Run git diff to see the recent changes.
2. Read the changed files and the code around them.
3. Report problems by priority: bugs, security, then readability.
4. For each problem, give the file, the line and a concrete fix.

Do not edit files. Report only.

La description importa más de lo que parece. Es lo que lee Claude para decidir si delega, así que di qué hace el subagente y cuándo usarlo. Frases como «use after writing code» ayudan a Claude a elegirlo por su cuenta.

El campo tools

tools es una lista de permitidas. Con tools: Read, Grep, Glob, Bash, el revisor de arriba puede leer y ejecutar comandos, pero no puede editar archivos. Si omites tools, el subagente hereda todas las herramientas de la sesión principal, incluidas las herramientas MCP. También existe disallowedTools para cuando es más fácil decir qué quitar que qué conservar.

Mantén la lista tan corta como permita el trabajo. Un revisor no necesita Edit. Un investigador no necesita Bash. Menos herramientas significa menos sorpresas y una tarea más clara.

El campo model

model acepta un alias (sonnet, opus, haiku), un ID de modelo completo o inherit para usar el modelo de la sesión principal. Cuando se llama al subagente, Claude Code elige el modelo en este orden: un modelo pasado en esa llamada, después el campo model del archivo, después la variable de entorno CLAUDE_CODE_SUBAGENT_MODEL y por último el modelo de la sesión principal.

Aquí es donde los subagentes pueden ahorrar dinero de verdad. Las búsquedas amplias en archivos y la lectura de logs rara vez necesitan el modelo más potente. Ponlos en Haiku y deja la sesión principal con el modelo más grande para las decisiones. El artículo sobre el uso de tokens de Claude Code explica más formas de reducir el gasto.

Otros campos útiles

Cómo llamar a un subagente

Hay tres formas:

1. Deja que Claude decida. Si la petición coincide con la descripción de un subagente, Claude delega por su cuenta.
2. Pídelo por su nombre. «Use the code-reviewer subagent to check my last commit.» También puedes mencionarlo con @ desde el menú.
3. Ejecuta una sesión entera como uno. claude --agent code-reviewer inicia una sesión que usa el prompt, las herramientas y el modelo de ese subagente.

Para una sesión puntual puedes pasar subagentes como JSON sin crear archivos:

claude --agents '{
  "code-reviewer": {
    "description": "Reviews code changes. Use after edits.",
    "prompt": "You are a senior code reviewer. Report bugs and fixes, do not edit.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Para evitar que Claude use un subagente concreto, añádelo a la lista deny de tus permisos, por ejemplo Agent(Explore).

Subagentes frente a agentes paralelos separados

Los subagentes y los agentes paralelos reparten el trabajo, pero resuelven problemas distintos.

Usa un subagente cuando el agente principal necesita una respuesta para seguir: «encuentra todos los llamadores de esta función», «revisa este diff», «resume estos logs». El trabajo es corto, lo que importa es su resultado y no necesitas verlo.

Usa agentes separados cuando cada parte es trabajo de verdad por sí sola: una funcionalidad, una migración, una suite de tests. Quieres ver qué hace cada uno, responder a sus preguntas y revisar sus cambios como una rama. Esa es la configuración que se describe en agentes de programación en paralelo y en ejecutar varios agentes de Claude Code, con cada agente en su propio git worktree.

Los dos se combinan bien. Un agente separado puede seguir usando subagentes para sus propias búsquedas y revisiones. Una buena regla por defecto: agentes separados para el trabajo que asignarías a una persona y subagentes para los recados que esos agentes hacen. Para equipos más grandes, el artículo sobre equipos de agentes de IA explica los roles y los traspasos, y la entrada sobre orquestación multiagente cubre la idea general.

Claude Code también tiene una función aparte llamada agent teams, en la que varias sesiones de Claude trabajan juntas. No es lo mismo que los subagentes y queda fuera de este artículo.

Consejos para subagentes que funcionan

• Un trabajo por subagente. «Reviewer» y «test runner» funcionan mejor que «helper».
• Escribe la descripción para Claude. Di cuándo usarlo, no solo qué es.
• Limita las herramientas. Subagentes de solo lectura para investigar y revisar, herramientas de edición solo donde hagan falta.
• Elige el modelo a propósito. Haiku para búsquedas y resúmenes, un modelo más potente para diseño y arreglos difíciles.
• Pide un informe corto. El resultado va al contexto principal, así que dile al subagente que devuelva hallazgos, no volcados de archivos.
• Incluye tus subagentes de proyecto en el repositorio. .claude/agents/ en git significa que todos tienen los mismos ayudantes.

Cómo muestra AgentVera los subagentes

AgentVera es una app de escritorio para ejecutar muchos agentes de programación, Claude Code, Codex y otros, uno junto a otro. Gestiona los subagentes de dos maneras.

Puedes verlos. En el panel de un agente de Claude Code, el botón «Subagents» abre una vista en vivo de los subagentes que ese agente inició y de lo que hacen ahora. Cada uno muestra su estado (Running, Done, Error, Stopped), si se ejecuta «in background», la «Assigned task» que recibió y su «Report». Mientras algunos están trabajando, aparece una línea «{count} subagents running — show» para que no se te pasen. La visita guiada del proyecto y el mapa del código también tiene una línea de tiempo de subagentes con tipo, estado, número de herramientas y duración. Ambas leen transcripciones locales y por ahora son para agentes de Claude Code.

Un Explore más barato. En Settings → «Token saving», la opción «Explorer subagent» da a los agentes de Claude un explorador de solo lectura para búsquedas amplias. El escaneo de archivos se ejecuta en un modelo más barato, Haiku por defecto, y a la conversación principal solo vuelve el resultado. Si ya tienes tu propio archivo de subagente Explore, AgentVera deja el tuyo donde está. Está junto a las smart tools, en la misma sección.

Agentes separados cuando el trabajo es mayor. La vista de equipo muestra hasta 24 agentes a la vez. Parallel team (planes Pro y Team) divide un objetivo en partes, ejecuta cada una en su propio worktree y las fusiona en una sola PR. La mensajería entre agentes permite que se hagan preguntas, incluso entre CLI distintas, y la coordinación de agentes avisa cuando dos agentes tocan el mismo archivo. Eso te da el lado de agentes separados de la tabla de arriba, con los subagentes todavía disponibles dentro de cada agente de Claude.

Para terminar

Los subagentes son la herramienta adecuada cuando el agente principal necesita una respuesta y tú no necesitas ver el trabajo: buscar, revisar, investigar. Escribe un archivo Markdown con una descripción clara, una lista corta de herramientas y un modelo elegido con intención. Cuando el trabajo es lo bastante grande como para merecer su propia rama y tu atención, ejecuta un agente separado.

Para seguir leyendo:

• Subagente (glosario)
• Agentes de programación en paralelo
• Visita guiada del proyecto y mapa del código
• Parallel team
• Agente Claude Code

Para probar AgentVera, empieza en la página de inicio.