Subagentes — Delegación de Tareas — Dominando Claude Code

Qué Son los Subagentes

Los subagentes son agentes de IA especializados que Claude Code puede generar para manejar tareas específicas de forma independiente. En lugar de hacer todo en un solo hilo de conversación, Claude puede delegar trabajo a uno o más subagentes que operan en paralelo, cada uno enfocado en un objetivo específico. Cuando un subagente termina, reporta sus hallazgos de vuelta a la sesión principal.

Así es como trabajan los ingenieros senior en la práctica. No haces todo tú mismo -- delegas investigación a un miembro del equipo, testing a otro y documentación a un tercero, luego sintetizas los resultados. Los subagentes traen este mismo patrón al desarrollo asistido por IA.

Los beneficios clave son paralelismo, aislamiento y protección del contexto. Los subagentes pueden explorar enfoques riesgosos sin contaminar el contexto de tu conversación principal. Pueden investigar múltiples temas simultáneamente. Y mantienen la ventana de contexto de tu sesión principal enfocada en la tarea primaria en lugar de llenarla con callejones sin salida exploratorios.

Tipos de Agentes Integrados

Claude Code viene con varios tipos de agentes integrados optimizados para tareas comunes:

Agente de propósito general -- El tipo de agente por defecto. Tiene acceso a las mismas herramientas que la sesión principal y puede manejar cualquier tarea que le darías a Claude directamente.

Agente Explore -- Optimizado para exploración de bases de código. Lee archivos, busca a través del código y construye una comprensión de la estructura del proyecto sin hacer ningún cambio. Usa esto cuando necesites que Claude investigue una pregunta sobre tu base de código sin arriesgar modificaciones accidentales.

Agente Plan -- Crea planes de implementación detallados. Analiza requisitos, revisa código existente y produce planes paso a paso con cambios de archivos, archivos nuevos y comandos a ejecutar. Usa esto antes de comenzar tareas complejas para obtener una hoja de ruta.

Agente Code-reviewer -- Especializado en revisión de código. Examina diffs, busca bugs y problemas de seguridad, evalúa cobertura de tests y produce feedback de revisión estructurado.

Agentes integrados adicionales pueden estar disponibles dependiendo de tu versión de Claude Code. Inicia una sesión y pregúntale a Claude qué agentes están disponibles para ver la lista actual.

Cuándo Usar Subagentes

Los subagentes brillan en escenarios específicos:

Investigación en paralelo. Necesitas entender tres enfoques diferentes para implementar una funcionalidad. En lugar de investigarlos secuencialmente en tu sesión principal, genera tres subagentes y déjalos explorar en paralelo. Obtienes resultados más rápido y mantienes tu contexto principal limpio.

claude
> Necesito agregar notificaciones en tiempo real a nuestra app. Investiga tres enfoques en paralelo:
> 1. Implementacion WebSocket con Socket.io
> 2. Server-Sent Events con APIs nativas del navegador
> 3. Un enfoque basado en polling con long polling
> Para cada uno, analiza los trade-offs para nuestro stack Next.js + PostgreSQL.

Claude delegará cada pista de investigación a un subagente separado, luego sintetizará los hallazgos.

Exploración aislada. Quieres que Claude intente un enfoque de refactorización riesgoso pero no quieres arruinar tu sesión principal si sale mal. Un subagente puede explorar el enfoque de forma aislada, y solo aplicas los resultados si se ven bien.

Proteger el contexto principal. Tu sesión principal está profundamente metida en una tarea compleja y la ventana de contexto se está llenando. En lugar de arriesgar pérdida de contexto agregando más trabajo exploratorio, delega preguntas laterales a subagentes. Ellos usan sus propias ventanas de contexto, dejando la tuya intacta.

Tareas especializadas. Algunas tareas se benefician de atención enfocada. La revisión de código, generación de documentación y escritura de tests son todas tareas donde un agente dedicado con instrucciones claras produce mejores resultados que meterlas en una sesión principal ocupada.

La Herramienta Agent

Internamente, Claude usa la herramienta Agent para lanzar subagentes. No necesitas invocar esta herramienta directamente -- Claude decide cuándo usarla basándose en tu solicitud. Sin embargo, entender cómo funciona te ayuda a escribir mejores prompts.

Cuando Claude lanza un subagente, le proporciona:

Un prompt específico describiendo la tarea
Un conjunto de herramientas permitidas (que puede ser un subconjunto de las herramientas de la sesión principal)
Cualquier contexto relevante de la conversación actual

El subagente se ejecuta independientemente, usando su propia ventana de contexto y haciendo sus propias llamadas a herramientas. Cuando termina, retorna un resumen de su trabajo a la sesión principal.

Puedes influir en el comportamiento del subagente a través de tus prompts. Si le pides a Claude que "investigue esto cuidadosamente y reporte con ejemplos de código," el subagente será más exhaustivo que si dices "verifica rápidamente si esto es factible."

Creando Subagentes Personalizados

Para patrones de delegación recurrentes, puedes definir agentes personalizados como archivos markdown en el directorio .claude/agents/:

<!-- Archivo: .claude/agents/test-writer.md -->
---
name: Test Writer
description: Writes comprehensive unit and integration tests for TypeScript code. Specializes in Vitest with React Testing Library.
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
---

## Instrucciones

Al escribir tests, sigue estas reglas:

### Configuracion
- Usar Vitest como test runner
- Usar React Testing Library para tests de componentes
- Usar MSW (Mock Service Worker) para mocking de API
- Colocar archivos de test en directorios __tests__/ junto al codigo fuente

### Estructura de Tests
- Agrupar tests relacionados con bloques describe
- Usar nombres de test claros: "should [comportamiento esperado] when [condicion]"
- Seguir el patron Arrange-Act-Assert
- Probar tanto caminos felices como casos de error

### Requisitos de Cobertura
- Cada funcion exportada debe tener al menos un test
- Casos limite: entradas null, arrays vacios, valores limite
- Funciones async: probar estados tanto resueltos como rechazados
- Componentes: probar renderizado, interacciones de usuario y accesibilidad

### Salida
- Crear el archivo de test con todos los tests
- Ejecutar los tests para verificar que pasan
- Reportar resumen de cobertura

Ahora cuando le pidas a Claude que escriba tests, puede delegar a este agente especializado que conoce tus convenciones exactas de testing, herramientas y requisitos.

Anatomía del Agente: Campos del Frontmatter

Los archivos de agentes personalizados soportan estos campos de frontmatter:

---
name: Nombre del Agente       # Nombre para mostrar
description: Que hace este agente  # Usado para coincidir tareas con agentes
tools:                        # Herramientas permitidas (restringir por seguridad)
  - Read
  - Write
  - Bash
  - Glob
  - Grep
---

La lista de tools es importante para la seguridad. Un agente de documentación no necesita la herramienta Bash. Un agente de exploración no necesita la herramienta Write. Restringir las herramientas a lo que el agente realmente necesita previene modificaciones accidentales y reduce el riesgo.

Otro Ejemplo: Agente de Documentación

<!-- Archivo: .claude/agents/doc-writer.md -->
---
name: Documentation Writer
description: Generates and updates project documentation including API references, guides, and inline code comments.
tools:
  - Read
  - Write
  - Glob
  - Grep
---

## Instrucciones

Al generar documentacion:

### Proceso
1. Leer el codigo fuente exhaustivamente antes de escribir nada
2. Identificar todas las APIs publicas, funciones exportadas e interfaces
3. Generar documentacion que coincida con el estilo existente en el proyecto
4. Actualizar cualquier archivo de documentacion relacionado (README, docs de API, etc.)

### Estandares
- Usar JSDoc para TypeScript/JavaScript
- Incluir descripciones de parametros, tipos de retorno y ejemplos
- Agregar anotaciones @throws para funciones que pueden lanzar errores
- Mantener descripciones concisas pero completas
- Cada ejemplo de codigo debe ser valido y ejecutable

### NO hacer
- Modificar ningun codigo fuente (solo documentacion y comentarios)
- Generar documentacion para funciones privadas/internas
- Agregar documentacion que duplique lo que los tipos TypeScript ya expresan

Observa que este agente no tiene la herramienta Bash. Solo puede leer y escribir archivos, que es todo lo que necesita para trabajo de documentación. Esta restricción previene que accidentalmente ejecute comandos mientras se enfoca en su tarea de escritura.

Equipos de Agentes

Para proyectos complejos que se benefician de colaboración multi-agente, Claude Code soporta equipos de agentes. Cuando están habilitados, múltiples agentes pueden trabajar juntos en diferentes aspectos de una tarea, coordinándose a través de la sesión principal.

Habilita los equipos de agentes con la variable de entorno:

export CLAUDE_AGENT_TEAMS=1
claude

Con equipos de agentes activos, Claude puede orquestar flujos de trabajo como: un agente investiga el esquema de base de datos, otro revisa el código de API existente, un tercero redacta el nuevo endpoint, y la sesión principal sintetiza todo en una implementación final.

Esta funcionalidad es más útil para tareas grandes de múltiples pasos donde diferentes aspectos requieren diferentes especializaciones.

Aislamiento con Worktrees

Para máxima seguridad, los subagentes pueden ejecutarse en worktrees de git aislados. Un worktree es un directorio de trabajo separado que comparte el mismo historial de git pero tiene su propio estado de archivos. Los cambios hechos en un worktree no afectan tu directorio de trabajo principal hasta que los fusiones explícitamente.

claude
> Crea una nueva rama de feature en un worktree e implementa el endpoint de API de perfil de usuario.
> No modifiques mi directorio de trabajo actual.

Claude crea un worktree, ejecuta el subagente dentro de él y reporta de vuelta. Si te gusta el resultado, fusionas la rama del worktree. Si no, la eliminas sin impacto en tu rama principal.

Esto es especialmente valioso para trabajo experimental donde quieres probar algo sin ningún riesgo para tu estado actual.

Agentes en Segundo Plano

Algunas tareas de subagentes toman mucho tiempo -- ejecutar una suite completa de tests, realizar una auditoría comprensiva de código o generar documentación para un proyecto entero. Para estos casos, puedes pedirle a Claude que ejecute el agente en segundo plano:

claude
> Ejecuta una auditoria de seguridad comprensiva de toda la base de codigo en segundo plano.
> Continuare trabajando en la refactorizacion de auth mientras eso se ejecuta.

El agente en segundo plano trabaja independientemente mientras tú continúas con tu tarea principal. Cuando termina, recibes una notificación con los resultados.

Cuándo NO Usar Subagentes

Los subagentes agregan overhead. Cada uno consume tokens, toma tiempo para iniciarse y requiere que Claude sintetice los resultados. Para tareas simples y directas, usar la sesión principal es más rápido y barato.

No uses subagentes para:

Lecturas simples de archivos. Si solo necesitas ver qué hay en un archivo, pregunta directamente.
Búsquedas dirigidas. Si sabes dónde buscar, señala a Claude ahí en lugar de generar un explorador.
Ediciones triviales. Cambiar el nombre de una variable o corregir un error tipográfico no necesita un agente dedicado.
Tareas secuenciales. Si el paso 2 depende del paso 1, ejecutarlos en agentes separados desperdicia tiempo porque no pueden paralelizarse.

La regla general: si la tarea toma menos de 3-4 llamadas a herramientas para completarse, hazla en la sesión principal. Si requiere exploración significativa, podría beneficiarse de paralelismo o necesita aislamiento de tu trabajo principal, usa un subagente.

Mejores Prácticas

Dale a los agentes prompts claros y específicos. En lugar de "revisa la base de código," intenta "analiza el flujo de autenticación comenzando desde src/auth/login.ts, traza la lógica de validación de tokens a través de todas las capas de middleware e identifica cualquier ruta donde un token expirado podría evadir la validación." La especificidad produce resultados dramáticamente mejores de los subagentes.

Usa restricciones de herramientas para imponer límites de seguridad. Un agente de exploración no debería tener acceso de Write. Un agente de documentación no debería tener acceso a Bash. Relaciona las herramientas con la tarea.

Revisa los resultados de los subagentes antes de actuar sobre ellos. Los subagentes son poderosos pero no infalibles. Cuando un subagente reporta hallazgos o propone cambios, revísalos en la sesión principal antes de hacer commit de cualquier cosa.

Prueba este ejercicio: crea un agente test-writer personalizado y un agente doc-writer personalizado para tu proyecto. Dale a cada uno el conjunto mínimo de herramientas que necesita. Luego inicia una sesión de Claude Code y pide a Claude que escriba tests para una función compleja y genere documentación para un módulo, simultáneamente. Observa cómo Claude delega a ambos agentes en paralelo y sintetiza los resultados. Compara la calidad de la salida contra lo que obtienes cuando le pides a la sesión principal que haga ambas tareas secuencialmente.