Agentes built-in

Qué son los subagentes

Cuando Claude Code recibe una tarea compleja que requiere explorar decenas de archivos, analizar múltiples módulos o ejecutar varias operaciones independientes, puede delegar trabajo en subagentes. Un subagente es una instancia especializada que se ejecuta en su propia ventana de contexto, con su propio prompt de sistema, acceso a herramientas específico y permisos independientes.

La ventaja principal de los subagentes es el aislamiento de contexto. Cada subagente trabaja en un espacio separado: los archivos que lee, las búsquedas que ejecuta y el razonamiento que genera no se acumulan en la conversación principal. Cuando el subagente termina, devuelve un resumen conciso de sus hallazgos al agente principal.

Los subagentes no son procesos independientes ni sesiones separadas. Son instancias del modelo que comparten la misma sesión pero operan en ventanas de contexto aisladas. El agente principal los invoca mediante la herramienta Agent y recibe sus resultados como cualquier otra llamada a herramienta.

Este mecanismo resuelve un problema fundamental: sin subagentes, una instrucción como "investiga cómo funciona la autenticación y luego refactoriza el módulo de pagos" llenaría la ventana de contexto con toda la exploración del módulo de autenticación, dejando poco espacio para la refactorización. Con subagentes, la exploración queda contenida y solo el resumen relevante pasa al contexto principal.

flowchart TD
    A["Agente principal<br>Contexto limpio"] --> B["Subagente 1<br>Contexto aislado"]
    A --> C["Subagente 2<br>Contexto aislado"]
    B --> D["Resumen"]
    C --> E["Resumen"]
    D --> A
    E --> A

El agente Explore

Explore es un subagente optimizado para búsqueda y análisis de código. Utiliza el modelo Haiku, que es significativamente más rápido y barato que Sonnet u Opus, lo que lo convierte en la opción ideal para operaciones de lectura masiva donde la velocidad importa más que la profundidad de razonamiento.

Explore tiene acceso exclusivamente a herramientas de lectura: Read, Grep, Glob y LS. No puede modificar archivos ni ejecutar comandos, lo que lo hace completamente seguro. Claude delega a Explore automáticamente cuando necesita entender la estructura de un proyecto, localizar archivos o buscar patrones sin realizar cambios.

Al invocar Explore, Claude especifica un nivel de exhaustividad según la complejidad de la búsqueda:

| Nivel | Cuándo se usa | Ejemplo | |---|---|---| | quick | Búsquedas puntuales y directas | Localizar dónde se define una función concreta | | medium | Exploración moderada | Entender cómo se organizan los controladores de una API | | very thorough | Análisis exhaustivo | Mapear todas las dependencias y relaciones de un módulo |

En la práctica, no es necesario indicar a Claude qué nivel usar. El agente selecciona el nivel adecuado en función de la complejidad de la petición. Si se le pide "busca dónde se define la clase UserService", usará quick. Si se le pide "analiza la estructura completa del módulo de autenticación", usará very thorough.

investiga la estructura del directorio src/api/ y resume
como estan organizados los endpoints

En este caso, Claude lanzaría un subagente Explore que leería los archivos del directorio, analizaría los patrones de nomenclatura y devolvería un resumen estructurado. Todo ese proceso (potencialmente decenas de archivos leídos) queda contenido en el contexto del subagente.

Explore es la primera opción para cualquier tarea de lectura en el codebase. Al usar Haiku, es rápido y barato, y al estar restringido a herramientas de solo lectura, no introduce riesgos de modificación accidental.

El agente Plan

Plan es el subagente que se activa cuando Claude Code opera en modo plan (activado con Shift+Tab o con el flag --permission-mode plan). Su función es recopilar contexto e investigar el codebase antes de que Claude presente un plan de implementación al usuario.

Plan hereda el modelo de la conversación principal (no usa Haiku como Explore) y tiene acceso a herramientas de solo lectura. La diferencia clave con Explore es su propósito: Plan no busca información puntual, sino que investiga el codebase de forma orientada a la planificación de una tarea concreta.

Existe una restricción importante en la arquitectura de subagentes: un subagente no puede lanzar otros subagentes. Plan resuelve este problema en el modo plan, donde el agente principal necesita investigar antes de planificar pero no puede lanzar subagentes de forma anidada. El subagente Plan actúa como investigador delegado sin crear ciclos de delegación infinitos.

[modo plan activado con Shift+Tab]

quiero anadir autenticacion con OAuth a la aplicacion.
que archivos habria que modificar?

En este escenario, Claude lanza el subagente Plan para explorar los archivos relevantes del proyecto, identificar los puntos de integración y recopilar la información necesaria para elaborar un plan de implementación coherente.

El agente generalPurpose

generalPurpose es el subagente más versátil. A diferencia de Explore y Plan, tiene acceso completo a todas las herramientas: puede leer y escribir archivos, ejecutar comandos Bash, buscar en la web y modificar código. Hereda el modelo de la conversación principal.

Claude delega a generalPurpose cuando la tarea requiere tanto exploración como modificación, razonamiento complejo para interpretar resultados, o múltiples pasos dependientes entre sí. Es el subagente adecuado para tareas autónomas que van más allá de la simple lectura.

usa un subagente para refactorizar el modulo de validaciones:
extrae las funciones de validacion de email y telefono a un
archivo independiente y actualiza los imports

En este caso, generalPurpose leería el código actual, identificaría las funciones a extraer, crearía el nuevo archivo, movería las funciones y actualizaría las importaciones en todos los archivos afectados. Todo el proceso ocurre en su propio contexto.

Comparativa de agentes built-in

| Característica | Explore | Plan | generalPurpose | |---|---|---|---| | Modelo | Haiku | Hereda del principal | Hereda del principal | | Herramientas | Solo lectura | Solo lectura | Todas | | Velocidad | Muy rápida | Normal | Normal | | Coste | Bajo | Normal | Normal | | Puede modificar archivos | No | No | Sí | | Caso de uso | Búsqueda y análisis | Investigación para planificar | Tareas complejas y autónomas |

La elección entre subagentes no es manual. Claude decide automáticamente qué subagente usar según la naturaleza de la tarea. Si se pide "busca dónde se usa esta función", delegará a Explore. Si se pide "refactoriza este módulo", delegará a generalPurpose.

Otros agentes auxiliares

Además de los tres subagentes principales, Claude Code incluye agentes auxiliares que se invocan automáticamente en situaciones específicas:

• Bash: ejecuta comandos de terminal en un contexto separado, aislando salidas extensas del contexto principal.
• statusline-setup: se activa al ejecutar /statusline para configurar la barra de estado personalizada.
• Claude Code Guide: utiliza Haiku para responder preguntas sobre las funcionalidades de Claude Code.

Estos agentes son transparentes para el usuario: se activan y devuelven resultados sin requerir intervención.

Delegación automática y explícita

Claude Code utiliza la descripción de cada subagente para decidir cuándo delegar. Cuando la tarea coincide con el perfil de un subagente, Claude lo invoca automáticamente sin que el usuario lo solicite. Esta delegación automática es uno de los comportamientos que distinguen a Claude Code de un chatbot convencional.

También es posible solicitar la delegación de forma explícita, mencionando directamente que se quiere usar un subagente:

usa un subagente para investigar como funciona el sistema
de autenticacion del proyecto

investiga con un subagente los tests existentes del modulo
de pagos y resume que cubren

Cuándo conviene delegar

La delegación a subagentes aporta valor en escenarios concretos:

• Exploración extensiva: cuando la tarea requiere leer muchos archivos y el contexto principal debe mantenerse limpio para la implementación posterior.
• Verificación posterior: tras implementar un cambio, un subagente puede revisar el código en busca de problemas sin consumir contexto principal.
• Tareas con salida voluminosa: ejecutar una suite de tests completa o procesar logs extensos genera mucha salida. Un subagente la procesa y devuelve solo el resumen relevante.
• Investigación independiente: cuando se necesita recopilar información de distintas partes del proyecto que no dependen entre sí.

Por otro lado, hay situaciones donde la delegación no aporta valor:

• Cambios rápidos y directos: renombrar una variable o añadir un log no justifica lanzar un subagente.
• Tareas iterativas: si se necesita feedback constante del usuario entre pasos, la conversación principal es más adecuada.
• Fases que comparten contexto: cuando la planificación y la implementación necesitan compartir información detallada, mantenerlas en el mismo contexto puede ser más eficiente.

Los subagentes brillan cuando la tarea es autónoma y produce resultados que pueden resumirse. Si la tarea requiere ida y vuelta constante con el usuario, el contexto principal es más apropiado.