Subagentes - Guía de referencia completa

Los subagentes son asistentes especializados en IA a los que Claude Code puede delegar tareas. Cada subagente tiene un propósito específico, utiliza su propia ventana de contexto separada de la conversación principal y se puede configurar con herramientas específicas y un sistema personalizado.

Índice

1. Introducción
2. Principales beneficios
3. Ubicaciones de archivos
4. Configuración
5. Subagentes incorporados
6. Gestión de subagentes
7. Uso de subagentes
8. Agentes de reposición
9. Subagentes de encadenamiento
10. Memoria persistente para subagentes
11. Subagentes de fondo
12. Aislamiento de árboles de trabajo
13. Subagentes forzados
14. Restringir los subagentes valvibles
15. claude agents Comando CLI
16. Equipos de agentes (experimentales)
17. Seguridad de los subagentes de complementos
18. Arquitectura
19. Gestión del contexto
20. Cuándo usar los subagentes
21. Mejores prácticas
22. Ejemplo de subagentes en esta carpeta
23. Instrucciones de instalación
24. Estructura del archivo
25. Conceptos relacionados
26. Observabilidad
27. Recursos adicionales

Introducción

Los subagentes permiten la ejecución de tareas delegadas en Claude Code por:

• Creando Ayudantes de IA aislados con ventanas de contexto separadas
• Provisión avisos personalizados del sistema de expertos especializados
• Aplicación control de acceso a la herramienta para limitar las capacidades
• Prevención contaminación del contexto de tareas complejas
• Habilitación ejecución paralela de múltiples tareas especializadas

Cada subagente opera independientemente con una pizarra limpia, recibiendo sólo el contexto específico necesario para su tarea, y luego devuelve los resultados al agente principal para la síntesis.

Inicio rápido: Pídale a Claude que cree un subagente para usted ("cree un subagente que revise la seguridad"), o agregue un .claude/agents/<name>.md archivo directamente — ver Gestión de subagentes abajo.

Nota: A partir del v2.1.198, la /agents el comando ya no abre un asistente de creación interactivo. Cree y administre subagentes preguntando a Claude o editando .claude/agents/ archivos directamente.

Principales beneficios

Ubicaciones de archivos

Los archivos de subagent se pueden almacenar en múltiples ubicaciones con diferentes alcances:

Cuando existen nombres duplicados, las fuentes de mayor prioridad tienen prioridad.

Anidado .claude/ Precedente (v2.1.178): Cuando el mismo nombre de agente se define en múltiples anidados .claude/agents/ directorios (por ejemplo, un monorepo con el nivel de paquete .claude/ carpetas), la definición gana el directorio de trabajo más cercano. La misma regla de resultados más cercanos se aplica a las definiciones de flujo de trabajo y estilo de salida.

Configuración

Formato de archivo

Los subagentes se definen en YAML frontmatter seguido por el indicador del sistema en Markdown:

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
disallowedTools: tool4  # Optional - explicitly disallowed tools
model: sonnet  # Optional - sonnet, opus, haiku, or inherit
permissionMode: default  # Optional - permission mode
maxTurns: 20  # Optional - limit agentic turns
skills: skill1, skill2  # Optional - skills to preload into context
mcpServers: server1  # Optional - MCP servers to make available
memory: user  # Optional - persistent memory scope (user, project, local)
background: false  # Optional - run as background task
effort: high  # Optional - reasoning effort (low, medium, high, xhigh, max)
isolation: worktree  # Optional - git worktree isolation
initialPrompt: "Start by analyzing the codebase"  # Optional - auto-submitted first turn
experimental:  # Optional - experimental settings block
  cacheTtl: "1h"  # Cache TTL for this subagent: "5m" or "1h" (v2.1.248+)
hooks:  # Optional - component-scoped hooks
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

Campos de configuración

Variables de entorno del modelo de subagente

Dos variables de entorno afectan al modelo en el que se ejecuta un subagente:

Cambio de precedencia en v2.1.251: antes de esa liberación, CLAUDE_CODE_SUBAGENT_MODEL fue el primero y se sobrepasó la prioridad del agente, incluyendo model: inherit. De v2.1.251 en adelante, el propio subagente model: frontmatter gana. CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (v2.1.257+) cuando se desea que la variable de entorno vuelva a anular frontmatter, por ejemplo, para fijar una evaluación completa a un modelo.

Agente de discusión principal de Frontmatter Honrando (v2.1.117+/v2.1.119+)

Cuando un agente es invocado como el agente de hilo principal (a través claude --agent <name> o --print modo), estos campos de frontmatter son honrados:

Ejemplo — agente con mcpServers y permissionMode:

---
name: secure-researcher
description: Research agent with scoped MCP access and restricted permissions
permissionMode: acceptEdits
mcpServers:
  notion:
    type: http
    url: https://mcp.notion.com/mcp
  github:
    type: http
    url: https://api.githubcopilot.com/mcp/
    headers:
      Authorization: "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
tools: Read, Grep, Glob
---

You are a research agent. You may query Notion and GitHub through the
configured MCP servers, and read local files, but you cannot write or
execute commands outside of accepted edits.

Ejecutar con:

claude --agent secure-researcher

Opciones de configuración de la herramienta

Opción 1: Herencia de todas las herramientas (omita el campo)

---
name: full-access-agent
description: Agent with all available tools
---

Opción 2: Especificar herramientas individuales

---
name: limited-agent
description: Agent with specific tools only
tools: Read, Grep, Glob, Bash
---

Nota sobre Glob/Grep (v2.1.113+): En las construcciones nativas de macOS/Linux, Glob y Grep se proporcionan como bfs/ugrep a través de la herramienta Bash en lugar de como herramientas separadas. Windows y npm-JS construye todavía exponerlos como herramientas independientes. allowedTools; la sustitución del motor es transparente.

Opción 3: Acceso condicional a las herramientas

---
name: conditional-agent
description: Agent with filtered tool access
tools: Read, Bash(npm:*), Bash(test:*)
---

Configuración basada en CLI

Definir subagentes para una sola sesión utilizando el --agents bandera con formato JSON:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Formato JSON para --agents bandera:

{
  "agent-name": {
    "description": "Required: when to invoke this agent",
    "prompt": "Required: system prompt for the agent",
    "tools": ["Optional", "array", "of", "tools"],
    "model": "optional: sonnet|opus|haiku"
  }
}

Nota: Desde el v2.1.243 --agents ya no ignora silenciosamente las definiciones de agente inválido JSON o no válido — Claude Code sale con un error claro, emparejando el comportamiento de --mcp-config.

Prioridad de las definiciones de agente:

Las definiciones de agente se cargan con este orden de prioridad (primer partido gana): 1. Administrado - ajustes gestionados (a nivel de toda la organización) 2. CLI-definido - --agents bandera (sólo sesión, JSON) 3. Nivel del proyecto - .claude/agents/ (proyecto actual) 4. Nivel de usuario - ~/.claude/agents/ (todos los proyectos) 5. Nivel de complemento - Complemento agents/ directorio

Esto permite que las definiciones CLI sobrepasen las definiciones de proyecto, usuario y plugin para una sola sesión; las definiciones administradas siguen teniendo prioridad.

Subagentes incorporados

Claude Code incluye varios subagentes incorporados que siempre están disponibles:

Subagente de propósito general

Cuando se utiliza: Tareas que requieren exploración y modificación con razonamiento complejo.

Subagente del plan

Cuando se utiliza: Cuando Claude necesita entender la base de código antes de presentar un plan.

Explorar el subagente

Cuando se utiliza: Al buscar/entender código sin hacer cambios.

Niveles de agudeza - Especifique la profundidad de la exploración: - "rápido" - Búsquedas rápidas con exploración mínima, buenas para encontrar patrones específicos - "Medio" - Exploración moderada, velocidad y profundidad equilibradas, enfoque por defecto "muy minucioso" - Análisis integral en múltiples ubicaciones y convenciones de nombres, puede tomar más tiempo

Claude Subagent

Cuando se utiliza: Cuando una tarea no coincide con un agente integrado más especializado. También es el agente predeterminado para una sesión de fondo enviada; el modo de permiso en el que se inicia depende de cómo se inició esa sesión.

Subagente de configuración de la línea de estado

Cuando se utiliza: Al configurar o personalizar la línea de estado.

Subagente de guía de Claude Code (claude-code-guide)

Cuando se utiliza: Cuando los usuarios hacen preguntas sobre cómo funciona Claude Code o cómo utilizar características específicas.

Gestión de subagentes

Pregunta a Claude (recomendado)

La forma más simple de crear o administrar un subagente es preguntarle directamente a Claude:

Create a subagent that reviews code for security vulnerabilities.

Claude escribe el .claude/agents/<name>.md file for you, eligiendo sensible frontmatter (herramientas, modelo, descripción). A continuación, puede refinar el archivo a mano o pedir Claude para ajustarlo.

Nota: El /agents el comando ya no abre un asistente de creación interactivo (eliminado en v2.1.198). Ahora le indica que debe preguntar a Claude o editar .claude/agents/ archivos directamente.

Gestión directa de archivos

# Create a project subagent
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: Use proactively to run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively
run the appropriate tests. If tests fail, analyze the failures and fix
them while preserving the original test intent.
EOF

# Create a user subagent (available in all projects)
mkdir -p ~/.claude/agents

Uso de subagentes

Delegación automática

Claude delega de forma proactiva tareas basadas en: - Descripción de tareas en su solicitud - La description campo en configuraciones de subagentes - Contexto actual y herramientas disponibles

Para fomentar el uso proactivo, incluya "usar PROACTIVAMENTE" o "USAR MÚSICA" en su description campo:

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after writing or modifying code.
---

Invocación explícita

Puede solicitar explícitamente un subagente específico:

> Use the test-runner subagent to fix failing tests
> Have the code-reviewer subagent look at my recent changes
> Ask the debugger subagent to investigate this error

Insensible al caso y al separador subagent_type emparejamiento (v2.1.140): subagent_type (en Agent llamadas de herramientas o --agent flags) es igualado caso-sin sensibilidad e ignora el estilo separador — code-reviewer, Code Reviewer, y code_reviewer todo resolver al mismo agente. Esto elimina una pistola de larga data donde diferencias menores de capitalización silenciosamente cayó de nuevo al agente por defecto.

@-Mention Invocation

Usar la @ se invoca el prefijo para garantizar un subagente específico (pasa automáticamente la heurística de delegación):

> @"code-reviewer (agent)" review the auth module

Agente a lo largo de la sesión

Ejecute una sesión completa usando un agente específico como el agente principal:

# Via CLI flag
claude --agent code-reviewer

# Via settings.json
{
  "agent": "code-reviewer"
}

Lista de agentes disponibles

Para ver qué subagentes están configurados, pregunte a Claude o explore .claude/agents/ y ~/.claude/agents/. (claude agents no tiene relación: abre la vista de agente para las sesiones de fondo — véase CLI.)

Agentes de reposición

Los subagentes pueden continuar conversaciones anteriores con contexto completo preservado:

# Initial invocation
> Use the code-analyzer agent to start reviewing the authentication module
# Returns agentId: "abc123"

# Resume the agent later
> Resume agent abc123 and now analyze the authorization logic as well

Casos de uso: - Investigación a largo plazo en múltiples sesiones - Refinamiento iterativo sin perder contexto - Flujos de trabajo de varios pasos manteniendo el contexto

Subagentes de encadenamiento

Ejecutar múltiples subagentes en secuencia:

> First use the code-analyzer subagent to find performance issues,
  then use the optimizer subagent to fix them

Esto permite flujos de trabajo complejos donde la salida de un subagente se alimenta en otro.

Memoria persistente para subagentes

Los memory El campo proporciona a los subagentes un directorio persistente que sobrevive a través de las conversaciones. Esto permite a los subagentes acumular conocimiento a lo largo del tiempo, almacenando notas, hallazgos y contexto que persisten entre sesiones.

Alcances de memoria

Cómo funciona

• Las primeras 200 líneas de MEMORY.md en el directorio de memoria se cargan automáticamente en el sistema del subagente prompt
• Los Read, Write, y Edit las herramientas se habilitan automáticamente para que el subagente administre sus archivos de memoria
• El subagente puede crear archivos adicionales en su directorio de memoria según sea necesario

Configuración del ejemplo

---
name: researcher
description: Research assistant that keeps findings in persistent memory across sessions
memory: user
---

You are a research assistant. Use your memory directory to store findings,
track progress across sessions, and build up knowledge over time.

Check your MEMORY.md file at the start of each session to recall previous context.

graph LR
    A["Subagente<br/>Sesión 1"] -->|writes| M["Memory.md<br/>(persistente)"]
    M -->|cargas en| B["Subagente<br/>Sesión 2"]
    B -->|updates| M
    M -->|cargas en| C["Subagente<br/>Sesión 3"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#e1f5fe,stroke:#333,color:#333
    style M fill:#f3e5f5,stroke:#333,color:#333

Subagentes de fondo

Los subagentes se ejecutan en segundo plano por defecto (v2.1.198). Desde v2.1.302 los subagentes de la conversación principal en la aplicación de escritorio y el código VS también comienzan en segundo plano. Mientras el modo tenedor está activado (el predeterminado), Claude no puede esperar por ellos. claude -p, el agente SDK, la aplicación de escritorio y el código VS se ejecutan en primer plano por defecto. Claude sigue trabajando en la conversación principal mientras un subagente se ejecuta y se le notifica cuando termina, por lo que ya no espera a que un subagente regrese antes de continuar. En el código VS (v2.1.304+), un subagente de fondo se muestra como una línea de estado bajo su tarjeta Agent en lugar de transmitir cada paso en el chat; /tasks y haga clic en él para ver sus llamadas de la herramienta y transcripción.

Configuración

Debido a que el fondo ya es el predeterminado, background: true en la materia frontal fuerzas armadas el subagente que siempre se ejecuta en segundo plano y evita que se ejecute en línea:

---
name: long-runner
background: true
description: Performs long-running analysis tasks in the background
---

Accesos rápidos del teclado

Desactivar tareas de fondo

Establezca la variable de entorno para desactivar completamente el soporte de tareas de fondo:

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Deja que Claude espere a un subagente

Con nada configurado, un subagente Claude desove de la conversación principal comienza en el fondo. claude -p y el agente SDK, Claude todavía puede esperar a uno en su propio juicio o cuando usted pide. En un terminal interactivo, código VS o sesión de escritorio, Claude puede esperar sólo después de que se apague el modo de horquilla (v2.1.302+):

{
  "env": {
    "CLAUDE_CODE_FORK_SUBAGENT": "0"
  }
}

Comienzo claude de nuevo (o abrir una nueva conversación de código VS), a continuación, pregunte, por ejemplo, "ejecutar el subagente revisor y esperar a su informe". Ctrl+B todavía mueve una espera al fondo. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 en su lugar hace que Claude espere por cada subagente, y también desactiva los comandos de fondo.

Aislamiento de árboles de trabajo

Los isolation: worktree el ajuste da a un subagente su propio árbol de trabajo git, permitiéndole hacer cambios independientemente sin afectar al árbol de trabajo principal.

Configuración

---
name: feature-builder
isolation: worktree
description: Implements features in an isolated git worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

Cómo funciona

graph TB
    Main["Árbol de trabajo principal"] -->|spawns| Sub["Subagente con<br/>Árbol de trabajo aislado"]
    Sub -->|hace cambios en| WT["Git separado<br/>Worktree + Branch"]
    WT -->|sin cambios| Clean["Auto-cleaned"]
    WT -->|tiene cambios| Return["Devuelve worktree<br/>ruta y rama"]

    style Main fill:#e1f5fe,stroke:#333,color:#333
    style Sub fill:#f3e5f5,stroke:#333,color:#333
    style WT fill:#e8f5e9,stroke:#333,color:#333
    style Clean fill:#fff3e0,stroke:#333,color:#333
    style Return fill:#fff3e0,stroke:#333,color:#333

• El subagente opera en su propio git worktree en una sucursal separada
• Si el subagente no hace cambios, el árbol de trabajo se limpia automáticamente
• Si existen cambios, la ruta de árbol de trabajo y el nombre de la rama se devuelven al agente principal para su revisión o fusión.

Subagentes forzados

Un subagente bifurcado hereda toda la conversación del padre en el momento de la bifurcación —pronto del sistema, herramientas, modelo, historial de mensajes y caché de mensajes— en lugar de comenzar con una pizarra limpia. Esto es útil para explorar rutas alternativas sin perder el trabajo realizado hasta ahora.

Disponibilidad: GA en v.2.117. Desde v2.1.232, el modo de horquilla está activado por defecto en sesiones interactivas — en cada construcción, primera o no. Ya que v2.1.302 también está activado por defecto en modo no interactivo (claude -p), el agente SDK, la aplicación de escritorio y el código VS; claude mcp serve nunca ofrece subagentes de horquilla. En Claude Code más antiguo que v2.1.232, set CLAUDE_CODE_FORK_SUBAGENT=1 para encenderlo.

Los subagentes de modo tenedor se ejecutan en segundo plano. Donde el modo tenedor está activado, como por defecto en todas partes, ya que v2.1.302 — Claude Code ejecuta el subagente en segundo plano, bifurcado y no forzado por igual. En un terminal interactivo, código VS o sesión de escritorio Claude entonces no puede esperar a un subagente; para dejarlo esperar, apagar el modo tenedor (ver Deja que Claude espere a un subagente).

Configuración

No se define un tenedor en un archivo de agente. Claude comienza uno a través de la herramienta de Agente con subagent_type: "fork", o empiezas uno con /subtask <task> (v2.1.212+):

/subtask Explore an alternative implementation path and report the trade-offs

Un tenedor no puede generar más tenedores. Para bloquear tenedores, agregue la regla de denegación Agent(fork):

{
  "permissions": {
    "deny": ["Agent(fork)"]
  }
}

Nota: context: fork es una habilidad campo de materia frontal (véase SkillsClaude Code ignora silenciosamente los campos que no reconoce en una definición de agente.

Activar el modo de horquilla explícitamente

Establecer CLAUDE_CODE_FORK_SUBAGENT=0 para apagar el modo de la horquilla en todas partes. En las versiones antes de v2.1.302, configurarlo a 1 para encender las horquillas claude -p y el agente SDK.

export CLAUDE_CODE_FORK_SUBAGENT=0
claude

Cuándo usar tenedor frente a contexto limpio

Restringir los subagentes valvibles

Puede controlar qué subagentes ejecuta un agente como hilo principal con claude --agent se permite desovar utilizando el Agent(agent_type) sintaxis en la ventana tools campo. Esto proporciona una manera de permitir listar subagentes específicos para la delegación. En una definición de subagente, cualquier lista de tipo dentro de los paréntesis se ignora.

Nota: En el apartado 2.1.63, la Task se cambió el nombre de la herramienta Agent2. Existentes Task(...) las referencias todavía funcionan como alias.

Ejemplo

---
name: coordinator
description: Coordinates work between specialized agents
tools: Agent(worker, researcher), Read, Bash
---

You are a coordinator agent. You can delegate work to the "worker" and
"researcher" subagents only. Use Read and Bash for your own exploration.

En este ejemplo, cuando se ejecuta claude --agent coordinator, el hilo principal sólo puede desovar la worker y researcher subagentes. No puede desovar ningún otro subagente, incluso si se definen en otra parte. Si coordinator se ejecuta como un subagente en su lugar, la lista de tipos se ignora.

claude agents Comando CLI

claude agents abre vista de agente (v2.1.139+): una lista completa de sus sesiones de fondo agrupadas por estado. No lista definiciones de subagentes configuradas; use claude agents --json a script contra estado de sesión.

claude agents
claude agents --json

Los subagentes configurados viven en .claude/agents/ (proyecto) y ~/.claude/agents/ (usuario).

Equipos de agentes (experimentales)

Los equipos de agentes coordinan múltiples instancias de Claude Code trabajando juntos en tareas complejas. A diferencia de los subagentes (que son subtareas delegadas que devuelven resultados), los compañeros de equipo trabajan independientemente con sus propias ventanas de contexto y pueden comunicarse directamente a través de un sistema de buzón compartido.

Documentación oficial: code.claude.com/docs/en/agent-teams

Nota: Agent Teams es experimental y está desactivado por defecto. Requiere Claude Code v2.1.32+. Habilitarlo antes de su uso.

Equipos de subagentes contra agentes

Equipos de agentes habilitados

Establezca la variable de entorno o añádala a su settings.json:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

O en settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Iniciando un equipo

Una vez habilitado, pídale a Claude que trabaje con sus compañeros de equipo en su solicitud:

User: Build the authentication module. Use a team — one teammate for the API endpoints,
      one for the database schema, and one for the test suite.

Claude creará el equipo, asignará tareas y coordinará el trabajo automáticamente.

Modos de visualización

Controle cómo se muestra la actividad de los compañeros de equipo:

claude --teammate-mode tmux

También puede configurar el modo de visualización en settings.json:

{
  "teammateMode": "tmux"
}

Nota: El modo Split-pane requiere tmux o iTerm2. No está disponible en terminal de código VS, terminal de Windows o Ghostty.

Navegación

Para moverse entre compañeros de equipo, utilice las teclas de flecha hacia arriba y hacia abajo en el panel de agentes y pulse Intro (modo en proceso), o haga clic en el panel de un compañero de equipo (modo split-pane).

Configuración del equipo

Las configuraciones de equipo se almacenan en ~/.claude/teams/{team-name}/config.json.

Selección de modelos de compañeros de equipo

A partir de v2.1.234, el "modelo de compañero de equipo predeterminado" /config Los compañeros de equipo ahora heredan el modelo del líder del equipo por defecto, a menos que la llamada de desove especifique un modelo diferente explícitamente.

Arquitectura

graph TB
    Lead["Jefe de equipo<br/>(Coordinador)"]
    TaskList["Lista de tareas compartida<br/>(Dependencias)"]
    Mailbox["Buzón<br/>(Mensajes)"]
    T1["Compañero de equipo 1<br/>(Contexto propio)"]
    T2["Compañero de equipo 2<br/>(Contexto propio)"]
    T3["Compañero de equipo 3<br/>(Contexto propio)"]

    Lead -->|asigna tareas| TaskList
    Lead -->|envía mensajes| Mailbox
    TaskList -->|recoge el trabajo| T1
    TaskList -->|recoge el trabajo| T2
    TaskList -->|recoge el trabajo| T3
    T1 -->|reads/writes| Mailbox
    T2 -->|reads/writes| Mailbox
    T3 -->|reads/writes| Mailbox
    T1 -->|estado de las actualizaciones| TaskList
    T2 -->|estado de las actualizaciones| TaskList
    T3 -->|estado de las actualizaciones| TaskList

    style Lead fill:#e1f5fe,stroke:#333,color:#333
    style TaskList fill:#fff9c4,stroke:#333,color:#333
    style Mailbox fill:#f3e5f5,stroke:#333,color:#333
    style T1 fill:#e8f5e9,stroke:#333,color:#333
    style T2 fill:#e8f5e9,stroke:#333,color:#333
    style T3 fill:#e8f5e9,stroke:#333,color:#333

Componentes principales:

• Jefe de equipo: La sesión principal de Claude Code que crea el equipo, asigna tareas y coordina
• Lista de tareas compartida: Una lista sincronizada de tareas con seguimiento automático de dependencias
• Buzón: Un sistema de mensajería inter-agente para que los compañeros de equipo comuniquen el estado y coordinen
• Compañeros: Casos de Claude Code independiente, cada uno con su propia ventana de contexto

Asignación de tareas y mensajería

El líder del equipo rompe el trabajo en tareas y las asigna a compañeros de equipo. La lista de tareas compartidas maneja:

• Gestión automática de las dependencias — las tareas esperan a que se completen sus dependencias
• Seguimiento de la situación — los compañeros de equipo actualizan el estado de la tarea mientras trabajan
• Mensajería entre agentes — los compañeros de equipo envían mensajes a través del buzón para la coordinación (por ejemplo, "el esquema de base de datos está listo, puede empezar a escribir consultas")

Flujo de trabajo de aprobación del plan

Para tareas complejas o riesgosas, cambie el lead al modo plan antes de preguntar por un compañero de equipo: un compañero de equipo engendró mientras el lead está en el modo plan funciona sólo lectura hasta que su plan esté listo, luego envía una solicitud de aprobación del plan al lead. Si no ha cambiado el modo de permiso de ese compañero de equipo desde que se generó, Claude Code aprueba el plan tan pronto como llega la petición (no se le pide), y las ediciones y comandos del compañero de equipo siguen pasando por las indicaciones de permisos normales. Shift+Tab, el director revisa ese plan en su lugar.

Eventos de hook para equipos

Equipos de Agentes introducen dos adicionales eventos de hook:

Prácticas óptimas

• Tamaño del equipo: Mantenga equipos a 3-5 compañeros de equipo para una coordinación óptima
• Tamaño de tareas: Romper el trabajo en tareas que tardan 5-15 minutos cada una — lo suficientemente pequeño para paralelizar, lo suficientemente grande como para ser significativo
• Evitar conflictos de archivos: Asignar diferentes archivos o directorios a diferentes compañeros de equipo para evitar conflictos de fusión
• Inicio simple: Utilice el modo en proceso para su primer equipo; cambie a paneles separados una vez que sea cómodo
• Descripción clara de las tareas: Proporcionar descripciones de tareas específicas y accionables para que los compañeros de equipo puedan trabajar de forma independiente

Limitaciones

• Experimental: El comportamiento de las características puede cambiar en futuras versiones
• Continuación del período de sesiones: Los compañeros en proceso no pueden reanudarse después de que finalice una sesión
• Un equipo por sesión: No se pueden crear equipos anidados o múltiples equipos en una sola sesión
• Liderazgo fijo: El papel principal del equipo no puede transferirse a un compañero de equipo
• Restricciones del panel de división: tmux/iTerm2 requerido; no disponible en terminal de código VS, terminal de Windows o Ghostty
• Permisos de panel dividido: un compañero de equipo de dos paneles comienza con la ventaja --disallowedTools y --tools (v2.1.309+) pero no --allowedTools; para pre-aprobar las acciones allí, iniciar el plomo con claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}'. Los compañeros de equipo en proceso usan las reglas vivas del líder
• No hay equipos entre períodos de sesiones: Los compañeros de equipo sólo existen en el actual período de sesiones

Aviso: Agent Teams es experimental. Prueba con trabajo no crítico primero y monitoriza la coordinación de compañeros de equipo para un comportamiento inesperado.

Seguridad de los subagentes de complementos

Los subagentes provistos de complementos tienen capacidades de frontmatter restringidas para la seguridad. no permitido en las definiciones de subagentes del complemento:

• hooks - No se pueden definir los hooks del ciclo de vida
• mcpServers - No se pueden configurar los servidores MCP
• permissionMode - No se puede anular la configuración del permiso

Esto evita que los plugins aumenten los privilegios o ejecuten comandos arbitrarios a través de hooks de subagente.

Escaneo de salida de subagente (v2.1.210+)

A partir de v2.1.210, Claude Code escanea el informe final de cada subagente en busca de texto que imita el propio formato de salida del arnés — falso <system-reminder>-etiquetas de estilo, fabricadas Human:/Assistant: se convierte, o menciona banderas de bypass de permisos y rutas de configuración de archivos. Esto se defiende contra la inyección rápida llevada en salida de subagente, como un subagente que obtuvo una página web maliciosa que contiene fichas de control falsas diseñadas para manipular la sesión padre.

Cuando el escaneo marca algo, Claude Code lo neutraliza — insertando una barra inversa o un marcador en línea como [harness: subagent output matched instruction-shaped pattern(s): ...] nombre lo que desencadenó el escaneo — y se espera que la sesión padre trate el texto marcado como un hallazgo para transmitir, no una instrucción a seguir. El escaneo está activado por defecto sin opt-out documentado. Se equivoca hacia el etiquetado: un informe legítimo de subagente que cita un nombre de bandera real (por ejemplo, --dangerously-skip-permissions) literal puede desencadenar un marcador a pesar de que no ocurrió nada malicioso — un falso positivo es preferible a una inyección perdida.

Condición de subagente y límites de profundidad

La tapa de desove por sesión se ha ido. Claude Code tapa los subagentes desove a 200 por sesión de v2.1.212, pero v2.1.224 retirar ese tapón — las sesiones de larga duración ya no rechazan nuevos agentes, y la referencia oficial a los subagentes ahora indica claramente que no hay límite en el número total de subagentes que Claude puede desovar durante una sesión. CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION Variable que se sobrepone se ha ido con él.

Todavía se aplican dos límites al ventilador de subagent, ambos establecidos por variable de entorno:

• CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (v2.1.217) - Número máximo de subagentes en ejecución simultáneamente Predeterminado: 20.
• CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (v2.1.217) - Máximo profundidad de anidación para los subagentes que desoven sus propios subagentes. Predeterminado: 3 desde v2.1.219 (fue 1 en v2.1.217–v2.1.218). 1 para desactivar la anidación (ver Comportamientos clave).

export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20
export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=5

Arquitectura

Arquitectura de alto nivel

graph TB
    User["User"]
    Main["Agente principal<br/>(Coordinador)"]
    Reviewer["Revisor de códigos<br/>Subagente"]
    Tester["Ingeniero de pruebas<br/>Subagente"]
    Docs["Documentación<br/>Subagente"]

    User -->|asks| Main
    Main -->|delegates| Reviewer
    Main -->|delegates| Tester
    Main -->|delegates| Docs
    Reviewer -->|devuelve el resultado| Main
    Tester -->|devuelve el resultado| Main
    Docs -->|devuelve el resultado| Main
    Main -->|synthesizes| User

Ciclo de vida del subagente

sequenceDiagram
    participant User
    participant MainAgent as Main Agent
    participant CodeReviewer as Code Reviewer<br/>Subagent
    participant Context as Separate<br/>Context Window

    User->>MainAgent: "Construir nueva característica de autenticación"
    MainAgent->>MainAgent: Analyze task
    MainAgent->>CodeReviewer: "Revise este código"
    CodeReviewer->>Context: Initialize clean context
    Context->>CodeReviewer: Load reviewer instructions
    CodeReviewer->>CodeReviewer: Perform review
    CodeReviewer-->>MainAgent: Return findings
    MainAgent->>MainAgent: Incorporate results
    MainAgent-->>User: Provide synthesis

Gestión del contexto

graph TB
    A["Contexto del agente principal<br/>50.000 fichas"]
    B["Contexto del subagente 1<br/>20.000 fichas"]
    C["Contexto del subagente 2<br/>20.000 fichas"]
    D["Contexto del subagente 3<br/>20.000 fichas"]

    A -->|Limpiar pizarra| B
    A -->|Limpiar pizarra| C
    A -->|Limpiar pizarra| D

    B -->|Sólo resultados| A
    C -->|Sólo resultados| A
    D -->|Sólo resultados| A

    style A fill:#e1f5fe
    style B fill:#fff9c4
    style C fill:#fff9c4
    style D fill:#fff9c4

Puntos clave

• Cada subagente obtiene un ventana de contexto fresca sin la historia principal de la conversación
• Sólo el contexto pertinente se pasa al subagente para su tarea específica
• Resultados destilados volver al agente principal
• Esto previene agotamiento de la muestra de contexto sobre proyectos de larga duración

Consideraciones sobre el desempeño

• Eficiencia del contexto - Los agentes preservan el contexto principal, permitiendo sesiones más largas
• Latencia - Los subagentes comienzan con pizarra limpia y pueden agregar contexto inicial de recolección de latencia

Comportamientos clave

• Desove anidado por defecto, profundidad 3 (v2.1.219) - Los subagentes pueden generar sus propios subagentes hasta tres capas debajo de la conversación principal. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH para cambiar el límite, o 1 En el límite de profundidad, Claude Code retiene la Agent (Historia: v2.1.172–v2.1.216 anidado de forma predeterminada hasta 5 capas sin ninguna forma de cambiarlo; v2.1.217 hizo anidar opt-in en profundidad 1; v2.1.219 estableció el valor predeterminado a 3.) Utilice la herramienta Agent(agent_type) sintaxis de restricción (ver Restringir los subagentes valvibles) para controlar qué subagentes un agente de hilo principal (claude --agent) puede desovar; dentro de un subagente se ignora la lista de tipos
• Permisos de fondo - Cuando un subagente de fondo necesita un permiso que no está pre-aprobado, el prompt aparece en su sesión principal y nombra al subagente que está pidiendo
• Antecedentes - Prensa Ctrl+B para preparar una tarea en curso
• Transcripción - Las transcripciones de los subagentes se almacenan en ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl
• Autocompactación - Contexto de subagente autocompacta a una capacidad de ~95% (sobrecargar con CLAUDE_AUTOCOMPACT_PCT_OVERRIDE variable de entorno)
• Pensamiento extendido heredado (v.2.198) - Los subagentes y la compactación del contexto ahora heredan la configuración de pensamiento extendido de la sesión (anteriormente siempre deshabilitada).

Controles adicionales

• Desactivar agentes de exploración/planificación integrados - Set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 para eliminar los agentes de exploración y planificación integrados (v2.1.198)
• Añadir a cada indicador de subagente - En no-interactivo / --print modo, --append-subagent-system-prompt "<text>" añade texto al prompt de cada subagente del sistema (v2.1.205)
• Añadir desde un archivo - --append-subagent-system-prompt-file ./subagent-rules.txt lee el mismo texto adjunto de un archivo, para indicaciones demasiado largas para pasar en la línea de comandos. -p-sólo, y no se puede combinar con --append-subagent-system-prompt (v2.1.261)

Cuándo usar los subagentes

Mejores prácticas

Principios de diseño

Hacer: - Comenzar con agentes generados por Claude - Generar subagente inicial con Claude, luego iterar para personalizar - Diseñar subagentes enfocados - Responsabilidades simples y claras en lugar de hacer todo - Escribir indicaciones detalladas - Incluir instrucciones específicas, ejemplos y restricciones - Limitar el acceso a herramientas - Conceder solo las herramientas necesarias para el propósito del subagente - Control de versiones - Revisar los subagentes del proyecto en el control de versiones para la colaboración del equipo

No: - Crear subagentes superpuestos con los mismos roles - Dar acceso innecesario a las herramientas de subagents - Usar subagents para tareas simples de un solo paso - Mezclar preocupaciones en el prompt de un subagent - Olvidar pasar el contexto necesario

Mejores prácticas del sistema rápido

1. Sea específico sobre el papel You are an expert code reviewer specializing in [specific areas]

2. Definir claramente las prioridades • Revisar las prioridades (en orden):

3. Cuestiones de seguridad
4. Problemas de rendimiento

5. Calidad del código •

6. Especificar el formato de salida For each issue provide: Severity, Category, Location, Description, Fix, Impact

7. Incluir medidas de acción • Cuando se invoque:

8. Ejecute git diff para ver los cambios recientes
9. Centrarse en los archivos modificados
10. Comenzar la revisión de inmediato

Estrategia de acceso a las herramientas

1. Iniciar Restrictivo: Comience con sólo herramientas esenciales
2. Expandir sólo cuando se necesite: Añadir herramientas como demanda de requisitos
3. Sólo lectura cuando sea posible: Usar Read/Grep para agentes de análisis
4. Ejecución arenosa: Limite los comandos de Bash a patrones específicos

Ejemplo de subagentes en esta carpeta

Esta carpeta contiene subagentes de ejemplo listos para usar:

1. Revisor de códigos (code-reviewer.md)

Finalidad: Análisis integral de la calidad y mantenimiento del código

Herramientas: Lee, Grep, Glob, Bash

Especialización: - Detección de vulnerabilidad de seguridad - Identificación de optimización de rendimiento - Evaluación de mantenimiento de código - Análisis de la cobertura de pruebas

Usar cuando: Usted necesita revisiones de código automatizadas con enfoque en la calidad y seguridad

2. Ingeniero de pruebas (test-engineer.md)

Finalidad: Estrategia de prueba, análisis de cobertura y pruebas automatizadas

Herramientas: leer, escribir, Bash, Grep

Especialización: - Creación de pruebas de unidad - Diseño de pruebas de integración - Identificación de casos de borde - Análisis de cobertura (objetivo > 80%)

Usar cuando: Usted necesita creación completa de la suite de pruebas o análisis de cobertura

3. Escritor de documentación (documentation-writer.md)

Finalidad: Documentación técnica, documentos API y guías de usuario

Herramientas: Leer, Escribir, Grep

Especialización: - Documentación de endpoint API - Creación de guías de usuario - Documentación de arquitectura - Mejora de comentarios de código

Usar cuando: Necesita crear o actualizar la documentación del proyecto

4. Revisor seguro (secure-reviewer.md)

Finalidad: Revisión de código centrada en la seguridad con permisos mínimos

Herramientas: Lee, Grep

Especialización: - Detección de vulnerabilidad de seguridad - Autenticación/autorización de problemas - Riesgos de exposición a los datos - Identificación de ataques por inyección

Usar cuando: Usted necesita auditorías de seguridad sin capacidades de modificación

5. Agente encargado de la aplicación (implementation-agent.md)

Finalidad: Capacidad de implementación plena para el desarrollo de características

Herramientas: Leer, Escribir, Editar, Bash, Grep, Glob

Especialización: - Implementación de funciones - Generación de código - Ejecución de construcción y prueba - Modificación de base de código

Usar cuando: Necesita un subagente para implementar características de extremo a extremo

6. Depurador (debugger.md)

Finalidad: Especialista en depuración de errores, fallas de pruebas y comportamiento inesperado

Herramientas: Leer, Editar, Bash, Grep, Glob

Especialización: - Análisis de la causa raíz - Investigación de errores - Resolución de fallas de prueba - Implementación de corrección mínima

Usar cuando: Usted encuentra errores, errores, o comportamiento inesperado

7. Científico de datos (data-scientist.md)

Finalidad: Experto en análisis de datos para consultas SQL e información de datos

Herramientas: Bash, leer, escribir

Especialización: - Optimización de consultas SQL - Operaciones BigQuery - Análisis y visualización de datos - Perspectivas estadísticas

Usar cuando: Necesita análisis de datos, consultas SQL o operaciones BigQuery

8. Revisor de código limpio (clean-code-reviewer.md)

Finalidad: Revisión de legibilidad y mantenibilidad contra principios de código limpio

Herramientas: Lee, Grep, Glob, Bash

Especialización: - Nombre, longitud de la función, y el recuento de argumentos - Duplicación y código muerto - Calidad e intención de comentario - claridad estructural sobre la inteligencia

Usar cuando: Usted quiere un estilo y la mantenibilidad pasan diferente de la revisión de corrección

9. Optimizador del rendimiento (performance-optimizer.md)

Finalidad: Identificar y remediar los cuellos de botella de rendimiento

Herramientas: Leer, Editar, Bash, Grep, Glob

Especialización: - Complejidad algorítmica y rutas calientes - Asignación de memoria y fugas - Caché y optimización de consultas - Condition y E/S

Usar cuando: El código es mensurablemente lento y usted necesita optimización dirigida

Instrucciones de instalación

Método 1: Pregunte a Claude (recomendado)

Describa el subagente que desea y deje que Claude cree el archivo:

Create a project-level subagent that runs tests and fixes failures.
Give it access to Bash, Read, Edit, and Grep.

Claude escribe .claude/agents/<name>.md con frontmatter apropiado. Revise el archivo generado, luego utilícelo. /agents El asistente de creación interactiva fue eliminado en v2.1.198 — pregunte a Claude o edite el archivo directamente.)

Método 2: Copiar al proyecto

Copiar los archivos del agente a su proyecto .claude/agents/ directorio:

# Navigate to your project
cd /path/to/your/project

# Create agents directory if it doesn't exist
mkdir -p .claude/agents

# Copy all agent files from this folder
cp /path/to/04-subagents/*.md .claude/agents/

# Remove the README (not needed in .claude/agents)
rm .claude/agents/README.md

Método 3: Copiar al directorio de usuario

Para los agentes disponibles en todos sus proyectos:

# Create user agents directory
mkdir -p ~/.claude/agents

# Copy agents
cp /path/to/04-subagents/code-reviewer.md ~/.claude/agents/
cp /path/to/04-subagents/debugger.md ~/.claude/agents/
# ... copy others as needed

Verificación

Después de la instalación, verifique que los agentes son reconocidos al enumerar el directorio:

ls .claude/agents/

También puede preguntar a Claude qué subagentes están disponibles en la sesión actual, y se informará de los agentes incorporados y personalizados a los que puede delegar.

Estructura del archivo

project/
├── .claude/
│   └── agents/
│       ├── code-reviewer.md
│       ├── test-engineer.md
│       ├── documentation-writer.md
│       ├── secure-reviewer.md
│       ├── implementation-agent.md
│       ├── debugger.md
│       ├── data-scientist.md
│       ├── clean-code-reviewer.md
│       └── performance-optimizer.md
└── ...

Conceptos relacionados

Características relacionadas

• Comandos de barra - Accesos directos rápidos por encargo del usuario
• Memoria - Contexto persistente entre períodos de sesiones
• Skills - Capacidades autónomas reutilizables
• Protocolo MCP - Acceso externo a datos en tiempo real
• Hooks - Automatización de comandos de shell impulsada por eventos
• Plugins - Paquetes de extensión agrupados

Comparación con otras características

Patrón de integración

graph TD
    User["Solicitud del usuario"] --> Main["Agente principal"]
    Main -->|Uses| Memory["Memoria<br/>(Contexto)"]
    Main -->|Queries| MCP["MCP<br/>(Datos vivos)"]
    Main -->|Invokes| Skills["Skills<br/>(Herramientas automáticas)"]
    Main -->|Delegates| Subagents["Subagentes<br/>(Especialistas)"]

    Subagents -->|Use| Memory
    Subagents -->|Query| MCP
    Subagents -->|Isolated| Context["Contexto limpio<br/>Ventana"]

Observabilidad

Añadido en v2.1.139.

Las solicitudes de API procedentes de un subagente llevan dos encabezados HTTP adicionales para que los rastros y registros se puedan correlacionar con la sesión de envío:

Los mismos identificadores están expuestos en claude_code.llm_request OpenTelemetry se extiende como los atributos claude.code.agent.id y claude.code.agent.parent_id. Úsalos para:

• Atribuir gasto API a un tipo de subagente específico en lugar de la sesión padre
• Reconstruir una cadena de invocaciones de agentes después del hecho (parent_id forma un árbol)
• Alerta sobre subagentes fugitivos (por ejemplo, uno agent.id > 50% de los gastos de sesión)

Vea la sección de OpenTelemetría en Características avanzadas → Telemetría para la instalación de exportador de extremo a extremo.

Recursos adicionales

• Documentación de los subagentes oficiales
• Referencia de la CLI - --agents bandera y otras opciones CLI
• Guía de complementos - Para mezclar agentes con otras características
• Guía de skills - Para capacidades de auto-invocación
• Guía de memoria - Por contexto persistente
• Guía de hooks - Para la automatización basada en eventos

Última actualización: 26 de octubre de 2026 Versión de Claude Code: 2.1.310 Fuentes: - https://code.claude.com/docs/en/sub-agents - https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md - https://code.claude.com/docs/en/cli-reference - https://code.claude.com/docs/en/agent-teams - https://code.claude.com/docs/en/changelog#2-1-172 - https://code.claude.com/docs/en/changelog - https://github.com/anthropics/claude-code/releases/tag/v2.1.117 - https://github.com/anthropics/claude-code/releases/tag/v2.1.131 - https://github.com/anthropics/claude-code/releases/tag/v2.1.138 - https://github.com/anthropics/claude-code/releases/tag/v2.1.139 - https://github.com/anthropics/claude-code/releases/tag/v2.1.140 - https://code.claude.com/docs/en/model-config - https://code.claude.com/docs/en/interactive-mode - https://github.com/anthropics/claude-code/releases/tag/v2.1.296 - https://code.claude.com/docs/en/hooks - https://code.claude.com/docs/en/agent-view - https://code.claude.com/docs/en/sub-agents#permission-modes - https://code.claude.com/docs/en/sub-agents#available-tools - https://code.claude.com/docs/en/mcp - https://code.claude.com/docs/en/changelog#2-1-302 - https://code.claude.com/docs/en/sub-agents#turn-fork-mode-on-or-off - https://code.claude.com/docs/en/sub-agents#which-subagents-run-in-the-background - https://code.claude.com/docs/en/agent-teams#have-teammates-plan-before-implementing - https://code.claude.com/docs/en/sub-agents#let-claude-wait-for-a-subagent - https://code.claude.com/docs/en/sub-agents#mcp-server-names-that-contain-a-double-underscore - https://code.claude.com/docs/en/agent-teams#permissions - https://code.claude.com/docs/en/changelog#2-1-309 - https://code.claude.com/docs/en/changelog#2-1-304 - https://code.claude.com/docs/en/vs-code#see-a-background-subagents-tool-calls Modelos compatibles: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5