Guía completa de Claude Subagent

Introducción

Al trabajar con Claude Code en tareas complejas, es posible que haya enfrentado este dilema: el contexto de la conversación principal crece cada vez más, la IA comienza a "olvidar" información importante anterior y la calidad de las respuestas se degrada gradualmente.

Los Subagents (subagentes) fueron diseñados precisamente para resolver este problema.

Si los Skills son los "manuales de trabajo" de Claude, entonces los Subagents son los "empleados especializados" que usted contrata: tienen su propio espacio de trabajo (contexto), se enfocan en tipos específicos de tareas y le reportan los resultados cuando terminan.

Comprender los Subagents

Imagine que usted es el CEO de una empresa. Cuando la empresa es pequeña, se encarga de todo personalmente. Pero a medida que el negocio crece, comienza a contratar especialistas: un contador para las finanzas, recursos humanos para la contratación, ingenieros para el desarrollo. Cada empleado trabaja en su propio escritorio, completa sus tareas y le reporta a usted.

Los Subagents desempeñan exactamente este rol en Claude Code.

Desde una perspectiva técnica, los Subagents son asistentes de IA especializados con las siguientes características:

Por qué es importante el contexto aislado

Este es el principio de diseño más fundamental de los Subagents, y vale la pena comprenderlo en profundidad.

En una conversación normal, toda la información se acumula en el mismo contexto. Cuando le pide a Claude que busque en la base de código, analice archivos y luego realice modificaciones, todos esos pasos intermedios consumen espacio de contexto. A medida que la conversación avanza, el contexto se llena cada vez más y Claude puede comenzar a "olvidar" información importante del inicio.

Los Subagents cambian esta dinámica:

Conversación principal (enfocada en objetivos de alto nivel)
│
├── Usuario: Ayúdame a optimizar el rendimiento de este módulo
│
├── Claude: Voy a analizarlo...
│   │
│   └── [Llama al Explore Subagent]
│       │ En contexto aislado:
│       ├── Buscar archivos relevantes
│       ├── Analizar estructura del código
│       ├── Identificar cuellos de botella de rendimiento
│       └── Retorna: Encontré 3 puntos de optimización...
│
└── Claude: Según el análisis, encontré 3 puntos de optimización...

El proceso de análisis del Subagent no contamina la conversación principal. La conversación principal solo recibe resultados destilados, manteniendo claridad y enfoque.

Como recomienda Anthropic en sus mejores prácticas:

Tipos de Subagent integrados

Claude Code viene con tres Subagents integrados de uso frecuente, listos para usar de inmediato:

Estos agentes integrados se invocan automáticamente según el tipo de tarea.

Mi comprensión y práctica

Si observa detenidamente los tres Subagents integrados oficiales, notará un punto en común: todos son tareas de investigación y planificación. Explore se encarga de explorar la base de código, Plan se encarga de crear planes, e incluso General-purpose se usa principalmente para investigación y análisis. Ninguno está diseñado específicamente para escribir código.

Esto confirma mi comprensión de los Subagents: el valor central de los Subagents no es "un contexto limpio", sino permitir que el agente principal se concentre en hacer el trabajo.

División del trabajo

Mi patrón de uso es sencillo: los Subagents se encargan de la investigación, la planificación y la revisión (el trabajo de "recopilación de información"), mientras que el agente principal se encarga de la ejecución real.

Subagent (Investigador)        Agente principal (Ejecutor)
     │                              │
     ├── Explorar estructura         │
     │   del código                  │
     ├── Analizar dependencias       │
     ├── Crear plan de               │
     │   implementación              │
     └── Retornar contexto ─────────→ Ejecutar tareas basándose
         destilado                   │ en el contexto
                                     │
                                     ├── Escribir código
                                     ├── Modificar archivos
                                     └── Ejecutar pruebas

Por qué no dejo que los Subagents escriban código

Algunas personas prefieren que el agente principal delegue la escritura de código a múltiples subagents. En mi opinión, esto no funciona bien. La razón es simple: déficit severo de contexto.

El contexto de un Subagent es aislado: no sabe qué se discutió en la conversación principal, qué decisiones se tomaron ni qué restricciones existen. Pedirle que escriba código es como pedirle a un empleado recién contratado que complete una tarea de forma independiente sin ninguna información de contexto: es muy probable que el resultado no cumpla con sus expectativas.

Posicionar a los Subagents como "investigadores" tiene mucho más sentido:

• Las tareas de investigación inherentemente requieren menos contexto
• Devuelven información en lugar de código, que el agente principal puede usar con el contexto completo
• Incluso si los resultados de la investigación no son del todo precisos, el agente principal puede corregir el rumbo

Mi flujo de trabajo diario

1. Antes de iniciar una nueva tarea: El agente Explore comprende rápidamente la estructura del código relevante
2. Planificación de tareas complejas: El agente Plan analiza los requisitos y crea los pasos de implementación
3. Revisión de código: Un agente de Review verifica la calidad del código y los problemas de seguridad
4. Codificación real: El agente principal escribe código basándose en el contexto recopilado

Esta es mi lista actual de agentes:

El beneficio de este enfoque es que la ventana de contexto del agente principal se mantiene limpia: solo contiene "la información que necesito saber", y no "un montón de resultados intermedios del proceso de búsqueda del Subagent".

Cómo usar los Subagents

Ver agentes disponibles

Utilice el comando /agents para ver todos los Subagents disponibles en su entorno actual:

/agents

Esto listará tanto los agentes integrados como sus agentes personalizados.

Delegación automática

En la mayoría de los casos, no necesita especificar manualmente qué Subagent usar. Claude seleccionará automáticamente el agente apropiado según el tipo de tarea:

• Tareas de exploración de código → Explore Subagent
• Necesidad de crear un plan → Plan Subagent
• Tareas complejas de múltiples pasos → General-purpose Subagent

Invocación explícita

Si desea usar explícitamente un agente específico, puede indicarlo directamente en su prompt:

Usa el agente Explore para buscar todos los archivos que contengan authentication

O bien:

Inicia un subagente para analizar el grafo de dependencias de este módulo

Dónde encontrar Subagents

Agentes integrados

Los tres agentes integrados que vienen con Claude Code (Explore, Plan, General-purpose) funcionan de inmediato sin necesidad de configuración.

Recursos de la comunidad

wshobson/agents — Un repositorio de plantillas de Subagent de alta calidad que incluye agentes comunes para revisión de código, ejecución de pruebas y más:

Visitar

Claude Plugin Hub — Un marketplace de plugins donde puede encontrar diversos agentes y plugins:

Visitar

Crear Subagents personalizados

Además de usar los agentes integrados y los recursos de la comunidad, puede crear sus propios Subagents.

Ubicación del archivo de configuración

Formato de configuración

Cada Subagent es un archivo Markdown que contiene frontmatter YAML y un prompt de sistema:

---
name: code-reviewer
description: Reviews code for security and style issues. Use PROACTIVELY after code changes.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer focusing on:
- Security vulnerability detection
- Code style and best practices
- Performance optimization

## Review Output
1. **Critical Issues**: Security, correctness
2. **Warnings**: Style, performance
3. **Suggestions**: Refactoring opportunities

Referencia de campos

Permisos de herramientas

Configure los permisos mínimos necesarios según el rol del agente:

Capacidades avanzadas

Como entidades independientes, los Subagents pueden acceder a la mayoría de las capacidades del agente principal:

Acceso a herramientas MCP

Omitir el campo tools hereda automáticamente todas las herramientas MCP. Para especificarlas explícitamente, use este formato:

tools: Read, Grep, mcp__github__create_issue, mcp__linear__list_issues

Conocimiento de Skills

Si necesita que un Subagent utilice el conocimiento de un Skill específico, haga referencia a él en el cuerpo del prompt de sistema:

---
name: code-reviewer
description: Reviews code for quality issues
tools: Read, Grep, Glob
---

You are a code reviewer. Follow the guidelines in the code-standards skill.

When reviewing:
- Apply project coding standards
- Check for security issues

De esta manera, el Subagent consultará las directrices del Skill relevante durante la ejecución.

Modos de permisos

Limitaciones

• No puede llamar a otros Subagents (para prevenir recursión infinita)
• No admite planificación paso a paso

Mejores prácticas

• Responsabilidad única: Cada agente se enfoca en un objetivo claro
• Privilegio mínimo: Otorgue solo las herramientas necesarias
• Descripción clara: El campo description determina la calidad de la invocación automática — indique claramente "cuándo usarlo"
• Control de versiones: Haga commit de las configuraciones a nivel de proyecto en Git para facilitar el uso compartido en equipo

Reflexiones finales

El valor central de los Subagents es mantener al agente principal enfocado en el trabajo. Posicione a los Subagents como investigadores en lugar de ejecutores, y verá un aumento significativo en la eficiencia de Claude Code.

Si aún no está familiarizado con los conceptos básicos de Claude Code, le recomiendo leer primero Mis mejores prácticas con Claude Code para comprender los comandos principales y los flujos de trabajo.

Lecturas adicionales

• Arquitectura del sistema Claude explicada — La posición de los Subagents en el sistema general de Claude
• ¿Qué son los Claude Skills? — La diferencia y la relación complementaria entre Skills y Subagents