Subagentes de Claude Code
En Claude Code, puedes crearsubagentes de IA especializados, que se utilizan para manejar tipos específicos de tareas, logrando así un mejor aislamiento de contexto, un control de restricciones más estricto y una mayor eficiencia de ejecución.
Los subagentes se ejecutan enventanas de contexto independientes. Cada subagente puede tener su propio prompt de sistema, un modelo designado, permisos de acceso a herramientas explícitos, un modo de permisos independiente y memoria persistente entre sesiones. Cuando Claude determina que tu solicitud coincide con la descripción de un subagente, delega automáticamente la tarea en él, y el subagente la completa de forma independiente y devuelve el resultado.
Los subagentes solo reciben su propio prompt de sistema e información básica del entorno (como el directorio de trabajo),no heredan el prompt de sistema completo de Claude Code, lo que garantiza un comportamiento puro y controlable.
¿Por qué usar subagentes?
El valor central de los subagentes reside enaislamiento + especialización, y se refleja principalmente en los siguientes aspectos:
Preservar el contexto de la conversación principal:Coloca tareas "pesadas" como exploración y análisis de registros en los subagentes; la conversación principal solo recibe resúmenes de conclusiones, sin verse inundada por grandes cantidades de salida intermedia. Los estudios muestran que ejecutar tres subagentes en paralelo para analizar un proyecto de 50 000 líneas tarda unos 45 segundos, mientras que la ejecución en serie requiere 3 minutos.
Aplicar restricciones de forma forzosa:Limita las capacidades de los subagentes mediante listas blancas o negras de herramientas, por ejemplo, análisis de solo lectura o prohibición de comandos peligrosos.
Especialización del comportamiento:Diseña IA dedicada para dominios específicos (revisión de código, depuración, análisis de datos) e indica claramente los límites de capacidades del agente en el prompt de sistema, evitando invocaciones innecesarias.
Control de costos:Asigna tareas simples a Haiku y análisis complejos a Sonnet, y mediante variables de entornoCLAUDE_CODE_SUBAGENT_MODELestablece de forma unificada el modelo utilizado por todos los subagentes.
Reutilización entre proyectos:Los subagentes de nivel de usuario se configuran una vez y están disponibles en todos los proyectos.
Subagente vs multiagente
Estos dos conceptos se confunden fácilmente; la diferencia radica en la granularidad de la tarea y el alcance de ejecución:
| Elemento de comparación | Subagente | Multiagente |
|---|---|---|
| Alcance de ejecución | Se inicia dentro de una sola sesión de Claude Code, procesa la subtarea y devuelve el resultado | Múltiples sesiones de Claude Code se ejecutan en paralelo o en serie, generalmente gestionadas por un orquestador |
| Contexto | Ventana de contexto independiente, aislada de la conversación principal | El contexto de cada sesión es totalmente independiente |
| Anidamiento | Los subagentes no pueden crear subagentes (para anidamiento se usan Skills) | El orquestador puede coordinar tareas de múltiples niveles |
| Escenarios aplicables | Subtareas focalizadas, aislamiento de grandes volúmenes de salida, análisis especializado | Canalización de desarrollo con todas las funciones (diseño → implementación → pruebas → publicación) |
Subagentes integrados
Claude Code ya incluye varios subagentes integrados que generalmente se usan automáticamente, sin necesidad de configuración manual.
1. Explore (agente de exploración)
Se utiliza para la búsqueda de solo lectura y el análisis del código base. El modelo usa Haiku por defecto (rápido y de baja latencia) y solo abre herramientas de solo lectura (no puede Edit/Write). Cuando Claude necesita ver código sin modificarlo, usa automáticamente el agente Explore. Admite diferentes profundidades de exploración:quick、medium、very thorough。
2. Plan (agente de planificación)
Recopila información del código base en modo de planificación, ayuda a Claude a comprender la estructura del proyecto y acumula contexto para la formulación de planes posteriores. Solo abre herramientas de solo lectura y recopila de forma segura la información necesaria para la planificación sin generar agentes anidados.
3. General-purpose (agente de propósito general)
Se utiliza para tareas complejas y de múltiples pasos, abre todas las herramientas y hereda el modelo de la conversación principal. Es adecuado para escenarios integrales de "ver + modificar + razonar", así como para tareas que requieren modificaciones de código en varios pasos.
4. Otros agentes internos
| Nombre del agente | Descripción |
|---|---|
| Bash | Ejecutar comandos Shell en un contexto independiente |
| statusline-setup | Configurar la visualización de la barra de estado del terminal |
| Claude Code Guide | Responder preguntas relacionadas con el uso de Claude Code |
Crea tu primer subagente
1. Abrir la interfaz de gestión de subagentes
En Claude Code, ejecuta el siguiente comando para abrir la interfaz completa de gestión de subagentes:
/agents
Esta interfaz ofrece todas las capacidades de gestión de subagentes: ver todos los agentes disponibles (integrados / nivel de usuario / nivel de proyecto / plugins), crear nuevos agentes, editar agentes existentes y ver qué versión está realmente activa cuando hay conflictos de nombre.
2. Elegir crear un subagente de nivel de usuario
En la interfaz, seleccionaCreate new agent:

y luego seleccionaProject (.claude/agents/)El archivo del agente se guardará en el directorio .claude/agents/ del directorio actual. Si seleccionas el directorio~/.claude/agents/, se aplicará a todos los proyectos:

Usa la recomendación de Claude:

3. Describir las responsabilidades del agente
Podemos decirle directamente a Claude en lenguaje natural qué debe hacer este agente, y Claude generará automáticamente el prompt de sistema y la configuración inicial. Por ejemplo:
Un agente de mejora de código que escanea los archivos del proyecto, sugiere mejoras en cuanto a legibilidad, rendimiento y mejores prácticas, y proporciona ejemplos de mejora.

Después de la generación, presionaepara editar manualmente todo el contenido de configuración.
4. Configurar permisos de herramientas y modelo
- Solo revisión de código → marca únicamente herramientas de solo lectura (Read / Grep / Glob)
- Se necesita modificar código → conserva las herramientas Edit / Write
- Para el modelo, se recomienda elegirSonnet, con un equilibrio entre capacidad de análisis y velocidad de ejecución.
Selecciona directamente "Continue" y luego presiona Enter:

En los siguientes pasos, elige la opción predeterminada y presiona Enter.
5. Elegir el alcance de memoria (opcional)
- SeleccionaUser: en
~/.claude/agent-memory/establecer memoria persistente y acumular experiencia entre todos los proyectos - SeleccionaNone: no conserva el aprendizaje y cada tarea comienza desde cero.

6. Usar el agente recién creado
使用 code-improver 子代理为此项目提出改进建议

El agente se ejecuta en un contexto independiente y, al finalizar, devuelve un resumen del resultado a la conversación principal.
Alcance de los subagentes
Los subagentes son esencialmente archivos Markdown con frontmatter YAML; su ubicación determina su alcance y prioridad:
| Ubicación | Alcance | Prioridad |
|---|---|---|
CLI --agentsIndicador |
Solo la sesión actual | Máxima |
.claude/agents/ |
Proyecto actual | Alto |
~/.claude/agents/ |
Todos los proyectos (global) | Medio |
| Agentes de plugins | Ámbito del plugin | Mínima |
Cuando existen subagentes del mismo nombre en diferentes ubicaciones, el de mayor prioridad sobrescribe al de menor prioridad. Puedes usar el comando/agentspara ver qué versión está realmente activa.
Recomendación para elegir la ubicación: agente de proyecto (.claude/agents/)puede confirmarse junto con el código para compartirlo con el equipo; el agente de usuario(~/.claude/agents/)almacena hábitos personales y herramientas comunes, y aplica entre proyectos; el agente CLI(--agents)se utiliza para pruebas temporales o scripts de automatización, y no se guarda en el disco.
Estructura del archivo de configuración
Cada archivo de configuración de subagente consta de dos partes: frontmatter YAML (metadatos y configuración) y cuerpo en Markdown (prompt del sistema).
Ejemplo
name: code-reviewer # Obligatorio: identificador único, letras minúsculas + guiones
description: Reviews code for quality, best practices, and security issues.
Invoke when the user asks to review, audit, or check code quality.
# Obligatorio: determina cuándo Claude invoca automáticamente a este agente; se recomienda escribirlo como "cuándo invocar + qué puede hacer"
tools: Read, Grep, Glob # Lista blanca de herramientas (solo puede usar estas herramientas)
model: sonnet # Especificar modelo: haiku / sonnet / opus / inherit
permissionMode: default # Modo de permisos (ver la sección de modos de permisos más abajo)
memory: project # Alcance de memoria persistente (ver la sección de memoria más abajo)
---
You are a senior code reviewer.
Analyze code and provide actionable feedback organized by severity: Critical / Major / Minor.
Update your agent memory with recurring patterns, conventions, and known issues you discover.
Descripción completa de los campos
| Campo | Obligatorio | Descripción |
|---|---|---|
name |
Obligatorio | Identificador único, también es el nombre usado en la invocación explícita. Formato: letras minúsculas + guiones, por ejemplocode-reviewer |
description |
Obligatorio | El campo más importante, de esto depende por completo si Claude invoca automáticamente a este agente y cuándo; asegúrese de indicar claramente los escenarios de uso |
tools |
Opcional | Lista blanca de herramientas; una vez configurada, solo se pueden usar las herramientas listadas; las herramientas de MCP también quedan excluidas |
disallowedTools |
Opcional | Lista negra de herramientas; hereda todas las herramientas del diálogo principal, pero excluye las herramientas listadas (las herramientas de MCP se conservan) |
model |
Opcional | Especifica el modelo; puede serhaiku、sonnet、opus, un ID de modelo completo, oinherit(predeterminado, hereda del diálogo principal) |
permissionMode |
Opcional | Control del comportamiento de permisos; ver la sección de modos de permisos más abajo |
memory |
Opcional | Alcance de memoria persistente:user / project / local, ver la sección de memoria más abajo |
background |
Opcional | Si se establece comotrue, el agente siempre se ejecuta en segundo plano (sin bloquear el diálogo principal) |
isolation |
Opcional | Si se establece comoworktree, se ejecuta en un worktree temporal de git, completamente aislado del repositorio principal |
skills |
Opcional | Lista de Skills que se cargan automáticamente al iniciar este agente |
hooks |
Opcional | Ganchos (hooks) del ciclo de vida:SubagentStart / SubagentStop / PreToolUse / PostToolUse |
Diferencia entre tools y disallowedTools
| Forma de configuración | Comportamiento | Caso típico |
|---|---|---|
| Ninguno configurado | Hereda todas las herramientas del diálogo principal, incluidas las herramientas MCP | Agente de propósito general, sin necesidad de restricciones |
Solo se configuratools |
Solo se pueden usar las herramientas de la lista blanca; las herramientas MCP quedan excluidas | Agente de análisis de solo lectura, escenarios con restricciones estrictas |
Solo se configuradisallowedTools |
Hereda todas las herramientas, excluye las de la lista negra; las herramientas MCP se conservan | Conserva la capacidad de MCP pero prohíbe operaciones de escritura |
| Ambos configurados al mismo tiempo | Primero se aplicadisallowedTools, y luego, de las herramientas restantes, portoolsse filtra |
Control preciso del acceso a las herramientas |
Ejemplo
---
name: safe-researcher
description: Research agent with read-only access. Use when analyzing code without making changes.
tools: Read, Grep, Glob, Bash # Solo se habilitan estas cuatro herramientas; Write y Edit no están en la lista blanca, por lo que no se pueden usar
---
Ejemplo
---
name: no-writes
description: Analysis agent that inherits all tools except file writes.
disallowedTools: Write, Edit # Se conservan las herramientas MCP; solo se excluyen Write y Edit
---
Modo de permisos
A través delpermissionModecampo se controla el comportamiento de permisos cuando el subagente ejecuta operaciones:
| Modo | Comportamiento | Escenario aplicable |
|---|---|---|
default |
Solicitud de permiso normal, pregunta al usuario antes de cada operación | Escenario general, valor predeterminado recomendado |
acceptEdits |
Acepta automáticamente las ediciones de archivos, sin necesidad de confirmar cada vez | Agentes que modifican archivos con frecuencia; reduce las interrupciones de interacción |
dontAsk |
Rechaza automáticamente las operaciones no autorizadas, sin interrumpir el flujo de ejecución | Escenarios estrictos de solo lectura; si una operación falla, se omite silenciosamente |
bypassPermissions |
Omite todas las comprobaciones de permisos y ejecuta directamente | Solo para entornos de automatización totalmente confiables y controlados |
plan |
Modo de planificación de solo lectura; no ejecuta ninguna operación de escritura | Elaboración de planes, análisis de arquitectura |
bypassPermissionsSolo es adecuado para subagentes totalmente confiables. Además, los subagentesheredan el modo de permisos de la sesión principal—si la sesión principal tiene activado bypass, todos los subagentes también harán bypass; tenga especial cuidado al usarlo.
Memoria persistente
Mediante elmemorycampo, los subagentes pueden acumular conocimiento entre sesiones, como patrones del código base, experiencia de depuración, decisiones de arquitectura, etc., sin tener que volver a explorar cada vez.
| Valor de alcance | Ubicación de almacenamiento | Escenario aplicable |
|---|---|---|
user |
~/.claude/agent-memory/<name>/ |
El conocimiento del agente aplica a todos los proyectos, como estándares generales de revisión de código |
project |
.claude/agent-memory/<name>/ |
El conocimiento está vinculado al proyecto y se puede compartir en el equipo mediante git (valor predeterminado recomendado) |
local |
.claude/agent-memory-local/<name>/ |
El conocimiento está vinculado al proyecto pero no se confirma en git; solo almacena experiencia personal local |
Ejemplo
name: code-reviewer
description: Reviews code for quality and best practices. Invoke when reviewing code changes.
memory: user # Memoria a nivel de usuario: acumula experiencia de revisión entre proyectos
---
You are a code reviewer.
As you review code, update your agent memory with patterns, conventions,
and recurring issues you discover in this codebase.
Cómo controlar el uso de la memoria en la conversación:
- Antes de comenzar la tarea:
Por favor, consulta primero tu memoria antes de comenzar la revisión.(para que el agente aproveche la experiencia existente) - Después de finalizar la tarea:
Una vez completada la tarea, guarda en la memoria los patrones que hayas encontrado.(para seguir acumulando) - También se puede escribir directamente en el prompt del sistema la instrucción de "mantener la memoria activamente" para que el agente lo ejecute automáticamente, sin necesidad de recordarlo manualmente cada vez.
Modo de aislamiento worktree
Al configurarisolation: worktree, el subagente se ejecuta en un worktree temporal de git, completamente aislado del repositorio principal. Es adecuado para los siguientes escenarios:
- Tareas exploratorias que requieren muchas modificaciones de archivos pero cuyo resultado es incierto
- Ejecutar varios esquemas en paralelo para compararlos, sin interferencias mutuas
- Operaciones que requieren un entorno limpio, como pruebas automatizadas o verificación de CI
Ejemplo
name: experimental-refactor
description: Tries refactoring approaches in an isolated worktree.
Use when exploring risky refactoring that shouldn't affect main branch.
isolation: worktree # Se ejecuta en un worktree temporal; las modificaciones no afectan al repositorio principal
tools: Read, Write, Edit, Bash
---
You are a refactoring agent working in an isolated environment.
Feel free to make changes—they won't affect the main branch.
Summarize what you changed and whether the approach was successful.
Ejecución en segundo plano (Background)
Los subagentes admiten dos modos de ejecución: primer plano y segundo plano, con comportamientos diferentes:
| Modo de ejecución | Comportamiento | Limitaciones |
|---|---|---|
| Primer plano (Foreground) | Bloquea el diálogo principal hasta completar; las solicitudes de permiso y las preguntas de aclaración se transmiten al usuario en tiempo real | Sin limitaciones especiales |
| Segundo plano (Background) | Se ejecuta en paralelo sin interrumpir el diálogo principal; antes de iniciar se confirman los permisos necesarios | No se puede usar MCP ni hacer aclaraciones interactivas; si los permisos son insuficientes, la tarea falla en lugar de pausarse en espera |
Claude decide automáticamente si usa primer plano o segundo plano según las características de la tarea. También puedes controlarlo manualmente:
Ctrl + B: cambia el subagente en ejecución a segundo planoCtrl + F(presiona dos veces para confirmar): termina todos los agentes en segundo plano- Configurar en el frontmatter
background: true: este agente siempre se ejecuta en segundo plano - Añade al inicio del mensaje
&: envía la tarea como tarea en segundo plano al cliente web de claude.ai - A través del
/taskscomando puedes ver el progreso de las tareas en segundo plano en cualquier momento
Si deseas deshabilitar por completo la función de tareas en segundo plano, configura la siguiente variable de entorno:
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
Si deseas configurar de manera uniforme el modelo que usan todos los subagentes (por ejemplo, Opus en el diálogo principal para razonamiento complejo y Sonnet en los subagentes para ahorrar costos):
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6"
Hooks de ciclo de vida
Los subagentes admiten los siguientes eventos de gancho, que pueden usarse en escenarios de automatización como registro de logs, verificación de operaciones y notificación de resultados:
| Evento de gancho | Momento de activación | Uso típico |
|---|---|---|
SubagentStart |
Al iniciar el subagente | Registrar el log de inicio, inicializar el entorno |
SubagentStop |
Al completar la tarea del subagente | Registrar el resultado, disparar tareas posteriores, enviar notificaciones. Incluye elagent_idyagent_transcript_pathcampo |
PreToolUse |
Antes de la llamada a la herramienta | Valida la legalidad de la operación; si el script devuelve el código de salida 2, se puede bloquear la llamada a esa herramienta |
PostToolUse |
Después de la llamada a la herramienta | Formatear la salida, generar registro de cambios |
Uso avanzado: mediantePreToolUselos ganchos controlan dinámicamente el comportamiento de las herramientas. Por ejemplo, hacer que el agente de base de datos solo permita consultas SQL de solo lectura; cualquier operación de escritura es interceptada por el script:
Ejemplo
name: db-analyst
description: Read-only database analysis agent. Use for querying and reporting, never for writes.
tools: Bash
# Configurar los ganchos en .claude/settings.json:
# PreToolUse on Bash -> validate-readonly-query.sh
# Cuando el script detecta una operación distinta de SELECT, devuelve el código de salida 2 para bloquear la ejecución del comando
---
You are a database analyst. Only run SELECT queries.
Never run INSERT, UPDATE, DELETE, DROP, or any DDL statements.
Deshabilitar subagentes específicos
Si no deseas que Claude invoque automáticamente a algún subagente integrado, puedes, en.claude/settings.jsonagregarlo a la lista de deshabilitados:
Ejemplo
"subagents": {
"deny": ["explore", "plan"] // Deshabilitar los agentes integrados explore y plan
// Una vez deshabilitados, Claude no los invocará automáticamente, pero aún puedes invocarlos explícitamente de forma manual
}
}
Cómo invocar subagentes
1. Delegación automática
Claude, basándose endescriptionel campo, determinará automáticamente si una tarea es adecuada para un subagente, sin necesidad de especificarlo manualmente en el prompt:
Ayúdame a revisar la calidad de los cambios de código recientes.
2. Invocación explícita
Especificar explícitamente en el prompt qué agente usar:
让 code-reviewer 子代理检查最近的改动
Patrones de uso típicos
1. Aislar tareas de alta salida
Colocar tareas que generan grandes cantidades de salida intermedia (como ejecutar pruebas, escanear registros) en subagentes, de modo que el diálogo principal solo reciba conclusiones resumidas:
Ejecuta todas las pruebas con subagentes y devuelve únicamente las pruebas fallidas y el análisis de la causa raíz.
2. Investigación en paralelo
Iniciar varios subagentes simultáneamente para manejar diferentes módulos, reduciendo significativamente el tiempo de análisis:
并行使用子代理分别分析认证模块、数据库模块和 API 模块,汇总后给出整体架构建议
3. Canalización de subagentes en serie
Dividir flujos de trabajo complejos en múltiples agentes especializados y pasar los resultados en orden:
先用 code-reviewer 找出问题,再用 optimizer 子代理修复这些问题
Principio de diseño del flujo de trabajo en serie: cada agente hace solo una cosa y define su interfaz mediante una clara señal de "entrada → procesamiento → salida → traspaso". A continuación se muestra un ejemplo de un pipeline de tres etapas en la práctica de producción:
- pm-spec: leer los requisitos, generar la especificación de trabajo y marcarla tras la confirmación
READY_FOR_ARCH - architect-review: verificar las restricciones de diseño, producir el registro de decisiones de arquitectura (ADR) y marcarlo
READY_FOR_BUILD - implementer-tester: implementar código y pruebas, actualizar la documentación y marcarlo
DONE
MedianteSubagentStopun hook que observa el archivo de estado y activa automáticamente el siguiente agente, sin intervención manual.
4. Revisión de código en paralelo
同时启动 style-checker、security-scanner、test-coverage 三个子代理并行审查, 将审查时间从数分钟压缩到数十秒
Cuándo usar subagentes
Escenarios adecuados para subagentes:
- Tareas autocontenidas, con entradas y salidas esperadas claramente definidas
- Salidas muy grandes que ocuparían significativamente el contexto del diálogo principal
- Requieren restricciones estrictas (solo lectura, worktree aislado, etc.)
- Tareas similares que se repiten y merecen convertirse en agentes fijos
- Implican múltiples subdominios independientes que pueden procesarse en paralelo
Escenarios adecuados para el diálogo principal:
- Requieren ajustes frecuentes de ida y vuelta, con alta interactividad
- Tareas de múltiples etapas con fuertes dependencias, donde el contexto debe ser continuo
- Cambios rápidos y pequeños donde el costo de iniciar un agente no vale la pena
- Experiencia práctica: después de más de 3-4 subagentes, el costo de gestión puede reducir la eficiencia general
Los subagentes no pueden crear más subagentes (para evitar anidamiento infinito). Si se necesita lógica anidada, useSkills。
Mejores prácticas
Cómo escribir la descripción
- Use descripciones basadas en acciones:
Se invoca cuando el usuario solicita revisar / analizar / verificar la calidad del código. - Indique las condiciones previas:
Se utiliza después de la confirmación del documento de especificaciones para generar el registro de decisiones de arquitectura. - Defina claramente los límites del agente y los escenarios en los que no es competente, para evitar invocaciones erróneas
Diseño de permisos de herramientas (principio de mínimo privilegio)
- Agentes de solo lectura (revisión, auditoría):
Read, Grep, Glob - Agentes de investigación (recopilación de información):
Read, Grep, Glob, WebFetch, WebSearch - Agentes de implementación (escribir código):
Read, Write, Edit, Bash, Glob, Grep
Responsabilidad única
- Cada agente hace solo una cosa, con reglas claras de entrada / salida / traspaso
- No intente que un solo agente se encargue de todo
Recomendaciones para el system prompt
- Defina claramente la personalidad del agente en el system prompt:
Mantén una actitud crítica, no te limites a decir cosas positivas. - Señale las debilidades y limitaciones del agente para evitar un exceso de confianza
- Si la memoria está habilitada, incluya en el system prompt la instrucción de "mantenimiento activo de la memoria" para que el agente la ejecute automáticamente
Elección entre paralelo y serie
- Subdominios independientes entre sí → priorizar el paralelismo para ahorrar tiempo
- El siguiente paso depende del resultado anterior → debe ser en serie para garantizar la calidad
- Evite el paralelismo por el paralelismo: 10 agentes en paralelo para tareas simples desperdician tokens y costos de coordinación