← Volver al listado de tecnologías ← Índice de Claude Code

Cap 3: Sub-Agents

2 de marzo de 2026 Por: Artiko

claude-codesub-agentsagentsagent-tool

Qué son los Sub-Agents

Los subagents son asistentes especializados que manejan tipos específicos de tareas. Usa uno cuando una tarea secundaria inundaría tu conversación principal con resultados de búsqueda, logs, o archivos que no vas a referenciar de nuevo: el subagente hace ese trabajo en su propio contexto y devuelve solo el resumen.

Cada subagente corre en su propia ventana de contexto, con system prompt custom, acceso a tools específico y su propia configuración de permisos.

Los subagents te ayudan a:

Preservar contexto manteniendo exploración e implementación fuera de la conversación principal
Imponer restricciones limitando qué tools puede usar el subagente
Reusar configuraciones entre proyectos con subagents user-level
Especializar comportamiento con system prompts enfocados
Controlar costos ruteando tareas a modelos más rápidos como Haiku

Un subagente NO es una frontera de seguridad: «subagents run in the same process as the parent session and use the same sandbox configuration». Recortar tools reduce lo que el subagente puede hacer, pero no lo aísla del proceso padre ni le aplica un sandbox distinto. Su valor real es el aislamiento de contexto y la restricción de herramientas, no la contención. Para límites duros usa permissions.deny y la configuración de sandbox.

Versión 2.1.63: el Task tool fue renombrado a Agent. Las referencias Task(...) aún funcionan como alias.

Subagents built-in

Agente	Modelo	Tools	Propósito
Explore	Haiku	Read-only	File discovery, code search, exploración rápida
Plan	Inherit	Read-only	Research durante plan mode
general-purpose	Inherit	Todos	Tareas complejas multi-paso con exploración + acción
statusline-setup	Sonnet	—	Cuando corrés `/statusline`
claude-code-guide	Haiku	—	Preguntas sobre features de Claude Code

Al invocar Explore, Claude especifica un nivel de thoroughness: quick, medium o very thorough.

Quickstart: crear un subagente

Desde v2.1.198 /agents ya no abre un asistente interactivo con pestañas Running / Library. El flujo de “Create new agent” y “Generate with Claude” dejó de existir.

Hoy hay tres formas de crear un subagente:

Archivo de proyecto: .claude/agents/<name>.md — compartible con el equipo vía VCS.
Archivo de usuario: ~/.claude/agents/<name>.md — disponible en todos tus proyectos.
Inline por CLI: claude --agents '<json>' — solo para la sesión actual.

En los tres casos la definición es la misma: frontmatter YAML con al menos name y description, y un cuerpo que se vuelve el system prompt.

Scopes de subagents

Ubicación	Scope	Prioridad
Managed settings	Organización	1 (más alta)
`--agents` CLI flag	Sesión actual	2
`.claude/agents/`	Proyecto	3
`~/.claude/agents/`	Usuario	4
Plugin `agents/`	Donde el plugin esté habilitado	5 (más baja)

Cuando hay nombres duplicados, gana el de mayor prioridad. La identidad viene SOLO del campo name del frontmatter, no del path. Mantené name únicos en todo el árbol.

Claude Code escanea .claude/agents/ y ~/.claude/agents/ recursivamente. Los plugin agents en subcarpetas reciben identificador scoped: my-plugin:review:security.

permissions.additionalDirectories concede solo acceso a archivos: no carga skills ni subagents, a diferencia de --add-dir.

Subagents via CLI flag

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

Crear un sub-agent manualmente

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

El cuerpo se vuelve el system prompt. Los subagents reciben SOLO ese system prompt (más detalles básicos del entorno como CWD), no el system prompt completo de Claude Code.

Si editas el archivo directamente en disco, reinicia la sesión para que la definición nueva se cargue.

Frontmatter completo

Solo name y description son requeridos.

Campo	Descripción
`name`	Identificador único en minúsculas con guiones. Los hooks lo reciben como `agent_type`
`description`	Cuándo debe Claude delegar a este subagent
`tools`	Tools permitidos. Hereda todos si se omite. Para precargar Skills usa `skills`, no `Skill` aquí
`disallowedTools`	Tools denegados, removidos de la lista heredada o especificada
`model`	`sonnet \| opus \| haiku \| fable`, un ID completo (`claude-opus-4-8`, `claude-sonnet-5`) o `inherit`. Default `inherit`
`permissionMode`	`default` (alias `manual` desde v2.1.200), `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`
`maxTurns`	Máximo de turnos agentic
`skills`	Skills a precargar (contenido completo inyectado al startup)
`mcpServers`	Servidores MCP scoped al subagent (inline o por referencia)
`hooks`	Hooks lifecycle scoped al subagent
`memory`	`user`, `project`, o `local`. Memoria persistente entre conversaciones
`background`	`true` para correr siempre en background
`effort`	`low`, `medium`, `high`, `xhigh`, `max`
`isolation`	`worktree` para correr en git worktree temporal
`color`	`red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`
`initialPrompt`	Auto-submitted como primer turno cuando corre como main session via `--agent`

Plugin subagents NO soportan hooks, mcpServers ni permissionMode (por seguridad).

Selección de modelo

Orden de resolución del modelo:

CLAUDE_CODE_SUBAGENT_MODEL env var
Parámetro model per-invocación
Frontmatter model
Modelo de la conversación principal

Los alias siguen a los modelos vigentes: opus resuelve a Opus 4.8 y sonnet a Sonnet 5. fable selecciona Fable 5.

Extended thinking: desde v2.1.198 los subagents heredan la configuración de extended thinking de la sesión principal. El nivel de esfuerzo se puede fijar aparte con el campo effort del frontmatter (low, medium, high, xhigh, max).

Tools disponibles

Por defecto los subagents heredan todos los tools, incluyendo MCP tools.

Allowlist con `tools`

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

Denylist con `disallowedTools`

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

Si ambos están seteados, disallowedTools se aplica primero.

Restringir qué subagents pueden spawnearse

Cuando un agente corre como main thread con claude --agent, puede spawnear subagents usando el Agent tool. Sintaxis Agent(agent_type):

tools: Agent(worker, researcher), Read, Bash

Solo worker y researcher pueden spawnearse. Agent sin paréntesis = sin restricciones. Omitir Agent completamente = no puede spawnear ningún subagent.

Permission modes

Modo	Comportamiento
`default`	Chequeo estándar con prompts. La UI lo etiqueta Manual; desde v2.1.200 `manual` se acepta como alias
`acceptEdits`	Auto-acepta edits y comandos comunes en working directory
`auto`	Classifier de background revisa cada comando
`dontAsk`	Auto-deny prompts (tools explícitamente allowed siguen funcionando)
`bypassPermissions`	Skip todos los prompts
`plan`	Plan mode (read-only)

Si el padre usa bypassPermissions o acceptEdits, eso tiene precedencia. Si el padre usa auto, el subagente hereda auto y su frontmatter es ignorado.

Preload skills en subagents

skills inyecta contenido completo de skills al startup del subagent. Es lo inverso a context: fork en un skill.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

Approach	System prompt	Task	También carga
Skill con `context: fork`	Del agent type	SKILL.md content	CLAUDE.md
Subagent con `skills` field	Cuerpo del subagent	Mensaje de delegación de Claude	Skills precargados + CLAUDE.md

No puedes precargar skills con disable-model-invocation: true. Para impedir invocación de skills, omite Skill de tools o agrégalo a disallowedTools.

Memoria persistente

memory da al subagent un directorio que sobrevive entre conversaciones.

Scope	Location	Cuándo usar
`user`	`~/.claude/agent-memory/<name>/`	Conocimiento aplica a todos los proyectos
`project`	`.claude/agent-memory/<name>/`	Conocimiento específico del proyecto, shareable via VCS
`local`	`.claude/agent-memory-local/<name>/`	Específico del proyecto, NO checked-in

Cuando memory está enabled:

El system prompt incluye instrucciones para leer/escribir al directorio
Incluye las primeras 200 líneas o 25KB de MEMORY.md, lo que llegue primero
Read, Write, y Edit tools se habilitan automáticamente

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

Tip: pedile al subagent que consulte su memoria antes de empezar y que la actualice al terminar.

No confundir con la auto memory del hilo principal. Las notas que Claude escribe en ~/.claude/projects/<project>/memory/ no se pasan a los subagents. El campo memory del frontmatter define un almacén propio del subagente, independiente de esa auto memory y de CLAUDE.md.

Hooks en frontmatter

Hooks scoped al subagent que solo corren mientras el subagent está activo.

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

Eventos comunes:

Evento	Cuándo dispara
`PreToolUse`	Antes de que el subagent use un tool
`PostToolUse`	Después de usar un tool
`Stop`	Cuando el subagent termina (convertido a `SubagentStop` en runtime)

Hooks del proyecto para eventos de subagent

En settings.json:

Evento	Cuándo dispara
`SubagentStart`	Cuando un subagent empieza
`SubagentStop`	Cuando un subagent completa

{
  "hooks": {
    "SubagentStart": [
      { "matcher": "db-agent", "hooks": [{ "type": "command", "command": "./scripts/setup-db.sh" }] }
    ],
    "SubagentStop": [
      { "hooks": [{ "type": "command", "command": "./scripts/cleanup-db.sh" }] }
    ]
  }
}

Scope MCP servers a un subagent

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline: solo para este subagent
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Por referencia: reusa servidor configurado
  - github
---

Los inline se conectan al inicio del subagent y desconectan al terminar. Útil para mantener un MCP server fuera de la conversación principal (sus tool descriptions consumen contexto).

Invocación

Delegación automática

Claude delega basándose en la description. Incluí frases como “use proactively” para fomentar delegación proactiva.

Lenguaje natural

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@-mention

Garantiza que ese subagent corra. Escribe @ y elige del typeahead:

@"code-reviewer (agent)" look at the auth changes

Manual: @agent-<name> para locales, @agent-<plugin>:<agent> para plugin.

Sesión completa como subagent

claude --agent code-reviewer

El system prompt del subagent reemplaza el default. Para plugins: claude --agent <plugin>:<agent>. Para hacerlo default del proyecto:

// .claude/settings.json
{ "agent": "code-reviewer" }

Foreground vs background

Foreground: bloquea la conversación principal, prompts de permisos pasan a vos
Background: corre concurrente, usa permisos ya concedidos, auto-deny cualquier prompt nuevo

Desde v2.1.198 los subagents corren en background POR DEFECTO, no por una decisión heurística de Claude. También puedes:

Forzarlo por definición con background: true en el frontmatter
Presionar Ctrl+B para enviar al background una tarea corriendo

Para deshabilitar background: CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1.

Deshabilitar subagents específicos

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

O via CLI: claude --disallowedTools "Agent(Explore)".

Resume y compactación de subagents

Cada invocación crea una instancia nueva. Para continuar el trabajo previo, pedile a Claude que resume:

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resume el subagent con full context]

Resume requiere CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

Los transcripts persisten en ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl. La compactación del main no afecta los transcripts de subagents.

Auto-compaction en subagents trigger a ~95%. Override con CLAUDE_AUTOCOMPACT_PCT_OVERRIDE.

Forked subagents (experimental)

Requiere CLAUDE_CODE_FORK_SUBAGENT=1, Claude Code 2.1.117+.

Un fork es un subagent que hereda toda la conversación en lugar de empezar fresh. Ve el mismo system prompt, tools, modelo e historial. Sus tool calls se mantienen fuera de tu conversación; solo el resultado final vuelve.

Cuándo fork mode está activo:

Claude spawnea un fork donde antes usaría general-purpose. Los named subagents (Explore, etc.) siguen igual
Cada spawn corre en background
/fork spawnea un fork en vez de ser alias de /branch

/fork draft unit tests for the parser changes so far

Panel debajo del prompt con keybindings: ↑↓ mover, Enter abrir transcript, x cerrar/detener, Esc volver al prompt.

	Fork	Named subagent
Contexto	Historial completo	Fresh con prompt pasado
System prompt	Igual al main	Del definition file
Modelo	Igual al main	Del campo `model`
Prompt cache	Compartido con main	Cache separado

Patrones comunes

Aislar operaciones de alto volumen

Use a subagent to run the test suite and report only the failing tests with their error messages

Research en paralelo

Research the authentication, database, and API modules in parallel using separate subagents

Hay un tope de 20 subagents concurrentes, ajustable con CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Para hechos simples suele alcanzar 1 agente con 3-10 llamadas a herramientas; 10+ subagents se reserva para investigación realmente compleja.

Revisión adversarial del diff

Antes de dar una tarea por terminada, un subagente en contexto fresco revisa el diff contra el plan (o corre la skill incluida /code-review). El contexto fresco no está sesgado hacia el código que se acaba de escribir.

Use a subagent to review the diff against the plan. Only flag gaps that affect
correctness or the stated requirements.

Advertencia de la guía oficial: «A reviewer prompted to find gaps will usually report some, even when the work is sound… Chasing every finding leads to over-engineering». Por eso conviene indicarle explícitamente que solo marque lo que afecte corrección o requisitos declarados.

Encadenar subagents

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

Por defecto (v2.1.217) los subagents no generan subagents anidados: la profundidad de spawn es 1 y se sube con CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. Sin cambiar esa variable, la delegación anidada se resuelve con Skills o encadenando desde la main conversation.

Cuándo usar subagents vs main conversation

Usa main cuando:

La tarea necesita ida y vuelta frecuente
Múltiples fases comparten contexto significativo
Cambio rápido y dirigido
Latencia importa (subagents arrancan fresh)

Usa subagents cuando:

La tarea produce output verboso que no necesitás en el main
Quieres imponer restricciones de tools/permisos específicas
El trabajo es self-contained y puede devolver un resumen
La tarea se paraleliza en direcciones independientes y los requisitos de información exceden una sola ventana de contexto

Antipatrón documentado: usar múltiples agentes cuando todos necesitan el mismo contexto o hay fuertes interdependencias entre las subtareas — es el caso de la mayoría de las tareas de código. Los agentes tienen dificultad para coordinarse y delegar en tiempo real.

También pesa la economía: los sistemas multi-agente consumen alrededor de 15x más tokens que una interacción de chat (un agente único, ~4x). Conviene delegar solo cuando el valor de la tarea paga ese sobrecosto; subir de modelo suele rendir más que duplicar el presupuesto de tokens.

Un subagente bien usado devuelve al coordinador un resumen condensado de típicamente 1.000-2.000 tokens, no su transcript completo.

Para preguntas rápidas sobre algo ya en tu conversación, usa /btw en vez de un subagent.

Ejemplo: Code Reviewer

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Ejemplo: Debugger

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

Best practices

Diseñá subagents enfocados: cada uno debe excelar en una tarea
Escribe descriptions detalladas: Claude las usa para decidir cuándo delegar
Delega con instrucciones completas: cada subagente debe recibir objetivo, formato de salida esperado, guía sobre qué herramientas y fuentes usar, y límites claros. Las instrucciones vagas («investiga el módulo de auth») producen trabajo duplicado, huecos y fallos
Espera un resumen, no un volcado: el retorno útil ronda los 1.000-2.000 tokens
Limita el tool access: solo lo necesario — recordando que es reducción de superficie, no una frontera de seguridad
No delegues cuando todos comparten contexto: si las subtareas dependen fuerte entre sí, el main thread rinde más
Checkeá a version control: project subagents en .claude/agents/ shareables con el equipo

Siguiente: Skills