Claude Code — Subagentes · Agentes de IA para programar

Los subagentes son agentes especializados a los que Claude Code delega trabajo. Cada uno corre con su propia ventana de contexto, su propio juego de herramientas y (opcionalmente) su propio modelo — así una tarea de investigación pesada no contamina la conversación principal.

Dónde viven

Origen	Ubicación	Ámbito
Flag del CLI	`--agents '<json>'`	Sólo esa sesión (máxima prioridad)
Proyecto	`.claude/agents/*.md`	Se sube a git, compartido con el equipo
Usuario	`~/.claude/agents/*.md`	Personal, para todos tus proyectos
Plugin	`<plugin>/agents/`	Viene dentro de un plugin

Prioridad ante conflictos de nombre: flag --agents > proyecto > usuario > plugin.

Definir un subagente

Un subagente es un archivo Markdown con frontmatter YAML:

---
name: api-reviewer
description: Revisa los handlers de rutas de la API buscando errores, mal manejo de excepciones e inconsistencias con la especificación OpenAPI. Úsalo de forma proactiva tras cambios en app/api/.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Eres el revisor de la API de este código. Cuando te invoquen:

1. Lee todos los archivos modificados bajo `app/api/`.
2. Comprueba que las respuestas de error coinciden con las formas de `openapi.yaml`.
3. Verifica que existe validación de entrada para todos los parámetros de query y body.
4. Reporta los hallazgos en una lista numerada, etiquetados por severidad (bloqueante / aviso / detalle).

No modifiques archivos — sólo reporta.

Campos del frontmatter (verificados)

Campo	Obligatorio	Para qué sirve
`name`	sí	En minúsculas y con guiones; es cómo se referencia al agente
`description`	sí	Se usa para la delegación automática — Claude decide cuándo invocar al agente a partir de este texto
`tools`	no	Lista blanca de herramientas; si se omite hereda todas (MCP incluido); admite `Task(agent_type)` para limitar qué subagentes puede lanzar
`disallowedTools`	no	Herramientas que se le retiran
`model`	no	`sonnet` / `opus` / `haiku` / `inherit` (`inherit` por defecto)
`permissionMode`	no	`default` / `acceptEdits` / `dontAsk` / `bypassPermissions` / `plan`
`maxTurns`	no	Tope de turnos agénticos
`skills`	no	Skills que se precargan al arrancar
`mcpServers`	no	Servidores MCP disponibles para el agente
`hooks`	no	Hooks propios del agente
`memory`	no	`user` / `project` / `local` — memoria persistente en `~/.claude/agent-memory/<nombre>/` y similares; se inyectan las primeras 200 líneas de `MEMORY.md`
`background`	no	Ejecutarlo siempre en segundo plano
`isolation`	no	`worktree` — lo ejecuta en un worktree de git temporal

Subagentes integrados

Explore — búsqueda en el código en solo lectura (Haiku), con niveles de profundidad: quick / medium / very thorough.
Plan — investigación en solo lectura durante el modo plan.
general-purpose — todas las herramientas, hereda el modelo.
Auxiliares: Bash, statusline-setup (Sonnet) y Claude Code Guide (Haiku).

Cómo invocarlos

Automáticamente — Claude delega según el description de cada agente; escribir “Úsalo de forma proactiva…” en la descripción empuja a que delegue antes.
Explícitamente — simplemente pídelo: “usa el subagente api-reviewer para revisar mis cambios”.
/agents — gestiona los subagentes (desde la v2.1.198 te recuerda que se lo pidas a Claude o edites .claude/agents/ directamente; las versiones anteriores abren una interfaz interactiva).
claude agents — lista todos los subagentes configurados desde el shell, sin abrir sesión.
claude --agent <nombre> — ejecuta la sesión entera como ese agente (pasa a ser el hilo principal y puede lanzar subagentes con Task).

Casos de uso

Explorar en solo lectura sin quemar tokens del contexto principal (Explore).
Líneas de trabajo paralelas e independientes (desde la W27 de 2026 los agentes corren en segundo plano por defecto).
Especialistas con herramientas muy acotadas: un revisor que sólo puede leer, un agente de migración con un prompt fijo.

Limitaciones

La referencia de subagentes dice que los subagentes no pueden lanzar otros subagentes (para evitar el anidamiento infinito). Una entrada de “Novedades” de junio de 2026 dice que sí pueden — la documentación se contradice; comportamiento actual: ? No se ha podido verificar.
Los subagentes en segundo plano deniegan automáticamente cualquier permiso no aprobado de antemano y no pueden hacer preguntas aclaratorias.
Las transcripciones se guardan en ~/.claude/projects/{proyecto}/{sessionId}/subagents/agent-{agentId}.jsonl y se pueden retomar por ID de agente.
La compactación automática también se aplica a los subagentes (~95% del contexto por defecto; CLAUDE_AUTOCOMPACT_PCT_OVERRIDE).

Desactivar un subagente

{
  "permissions": {
    "deny": ["Task(Explore)"]
  }
}

o sólo para una sesión:

claude --disallowedTools "Task(Explore)"

Última verificación: 2026-09-07

Fuentes oficiales:

Las herramientas de IA para programar evolucionan rápido. Si encuentras información desactualizada, abre un issue o un pull request.