# Subagentes de Claude Code: cómo crearlos y usarlos

URL: https://agentvera.dev/es/blog/claude-code-subagents/ · Publicado: 2026-10-23

Qué son los subagentes de Claude Code, cómo crear uno en .claude/agents, qué hacen los campos tools y model y cuándo conviene usar agentes paralelos separados.

**En resumen:**

- Un subagente se ejecuta en su propia ventana de contexto, con su propio prompt, herramientas y modelo, y solo su respuesta final vuelve a la conversación principal.
- Los subagentes son archivos Markdown en .claude/agents/ donde solo name y description son obligatorios; si omites tools, el subagente recibe todas las herramientas de la sesión principal.
- Los subagentes encajan en trabajos cortos como buscar y revisar; los agentes paralelos separados encajan en funcionalidades y tareas largas que acaban en su propia rama.

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](https://code.claude.com/docs/en/sub-agents "Documentación de subagentes de Claude Code"). Para la versión de un párrafo, consulta la [entrada del glosario sobre subagentes](/es/glossary/subagent/ "Subagente").

## 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:

| Subagente | Herramientas | Uso típico |
| --- | --- | --- |
| Explore | Solo lectura | Buscar y leer por toda la base de código, con profundidad quick, medium o very thorough |
| Plan | Solo lectura | Investigar mientras estás en modo plan |
| General-purpose | Todas las herramientas | Tareas de varios pasos que necesitan investigar y hacer cambios |

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:

| Ubicación | Ámbito |
| --- | --- |
| Managed settings | Toda la organización, definido por los administradores |
| Flag `--agents` (JSON) | Una sesión |
| `.claude/agents/` | Un proyecto, compartido mediante git |
| `~/.claude/agents/` | Todos tus proyectos |
| La carpeta `agents/` de un plugin | Dondequiera que esté instalado el plugin |

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.

```markdown
---
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

| Campo | Qué hace |
| --- | --- |
| `permissionMode` | Modo de permisos del subagente, por ejemplo plan o acceptEdits |
| `skills` | Skills que se cargan en el contexto del subagente al empezar |
| `mcpServers` | Servidores MCP que puede usar el subagente |
| `hooks` | Hooks que se aplican mientras se ejecuta este subagente |
| `memory` | Memoria persistente con ámbito de usuario, proyecto o local |
| `maxTurns` | Límite superior de turnos del subagente |
| `background` | Ejecutar en segundo plano por defecto |
| `isolation: worktree` | Ejecutar en un git worktree temporal |
| `effort` | Esfuerzo de razonamiento del subagente |

## 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:

```bash
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.

| | Subagentes | Agentes paralelos separados |
| --- | --- | --- |
| Quién los inicia | La sesión principal de Claude | Tú |
| Qué ves | El resultado final, dentro del chat principal | La sesión completa de cada agente |
| Contexto | Nuevo en cada tarea, se descarta después | De larga duración, uno por agente |
| Archivos | La misma carpeta de trabajo, salvo con `isolation: worktree` | Normalmente un git worktree cada uno |
| Tu intervención a mitad de tarea | Ninguna, habla con él el agente principal | Puedes guiar a cada uno |
| Ideal para | Búsqueda, revisión, investigación, trabajos cortos y concretos | Funcionalidades, refactors, tareas largas que acaban en una rama |

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](/es/blog/parallel-coding-agents/ "Agentes de programación en paralelo") y en [ejecutar varios agentes de Claude Code](/es/blog/run-multiple-claude-code-agents/ "Ejecutar varios agentes de Claude Code"), con cada agente en su propio [git worktree](/es/blog/git-worktree-parallel-agents/ "Git worktree para agentes en paralelo").

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](/es/features/project-tour-and-code-map/ "Visita guiada y 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](/es/features/team-view/ "Vista de equipo") muestra hasta 24 agentes a la vez. [Parallel team](/es/features/parallel-team/ "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)](/es/glossary/subagent/ "Subagente")
- [Agentes de programación en paralelo](/es/blog/parallel-coding-agents/ "Agentes de programación en paralelo")
- [Visita guiada del proyecto y mapa del código](/es/features/project-tour-and-code-map/ "Visita guiada y mapa del código")
- [Parallel team](/es/features/parallel-team/ "Parallel team")
- [Agente Claude Code](/es/agents/claude-code/ "Claude Code en AgentVera")

Para probar AgentVera, empieza en la [página de inicio](/es/ "AgentVera").

## Preguntas frecuentes

**¿Qué es un subagente en Claude Code?** Un subagente es un ayudante que la sesión principal de Claude Code inicia para una sola tarea. Se ejecuta en su propia ventana de contexto, con su propio system prompt, herramientas y modelo, y solo su resultado final vuelve a la conversación principal.

**¿Cómo creo un subagente de Claude Code?** Añade un archivo Markdown a .claude/agents/ en tu proyecto, o a ~/.claude/agents/ para todos los proyectos. El frontmatter YAML necesita un name y una description; el cuerpo es el system prompt. Entre los campos opcionales están tools, model, permissionMode e isolation.

**¿Qué modelo usa un subagente?** El campo model acepta un alias como sonnet, opus o haiku, un ID de modelo completo o inherit. Si no se define, el subagente usa el modelo de la sesión principal, salvo que la variable de entorno CLAUDE_CODE_SUBAGENT_MODEL indique otra cosa.

**¿Los subagentes ahorran tokens?** Mantienen limpio el contexto principal, porque las lecturas de archivos y los resultados de búsqueda se quedan en el subagente. No hacen que el trabajo sea gratis: las peticiones de los subagentes cuentan para los mismos límites de uso, así que lo que más ahorra es enviar las búsquedas amplias a un modelo más barato como Haiku.

**¿Cuándo debo usar agentes separados en lugar de subagentes?** Cuando las tareas son largas, editan muchos archivos, necesitan tu revisión por el camino o deben acabar en ramas separadas. Los agentes separados, cada uno en su propio git worktree, te dan eso; los subagentes encajan en trabajos cortos y concretos cuyo resultado necesita el agente principal.

---

**Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/