Subagentes — Delegacion de Tareas — Dominando Claude Code

Que Son los Subagentes

Los subagentes son agentes de IA especializados que Claude Code puede generar para manejar tareas especificas de forma independiente. En lugar de hacer todo en un solo hilo de conversacion, Claude puede delegar trabajo a uno o mas subagentes que operan en paralelo, cada uno enfocado en un objetivo especifico. Cuando un subagente termina, reporta sus hallazgos de vuelta a la sesion principal.

Asi es como trabajan los ingenieros senior en la practica. No haces todo tu mismo -- delegas investigacion a un miembro del equipo, testing a otro y documentacion a un tercero, luego sintetizas los resultados. Los subagentes traen este mismo patron al desarrollo asistido por IA.

Los beneficios clave son paralelismo, aislamiento y proteccion del contexto. Los subagentes pueden explorar enfoques riesgosos sin contaminar el contexto de tu conversacion principal. Pueden investigar multiples temas simultaneamente. Y mantienen la ventana de contexto de tu sesion 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 proposito general -- El tipo de agente por defecto. Tiene acceso a las mismas herramientas que la sesion principal y puede manejar cualquier tarea que le darias a Claude directamente.

Agente Explore -- Optimizado para exploracion de bases de codigo. Lee archivos, busca a traves del codigo y construye una comprension de la estructura del proyecto sin hacer ningun cambio. Usa esto cuando necesites que Claude investigue una pregunta sobre tu base de codigo sin arriesgar modificaciones accidentales.

Agente Plan -- Crea planes de implementacion detallados. Analiza requisitos, revisa codigo 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 revision de codigo. Examina diffs, busca bugs y problemas de seguridad, evalua cobertura de tests y produce feedback de revision estructurado.

Agentes integrados adicionales pueden estar disponibles dependiendo de tu version de Claude Code. Inicia una sesion y preguntale a Claude que agentes estan disponibles para ver la lista actual.

Cuando Usar Subagentes

Los subagentes brillan en escenarios especificos:

Investigacion en paralelo. Necesitas entender tres enfoques diferentes para implementar una funcionalidad. En lugar de investigarlos secuencialmente en tu sesion principal, genera tres subagentes y dejalos explorar en paralelo. Obtienes resultados mas rapido 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 delegara cada pista de investigacion a un subagente separado, luego sintetizara los hallazgos.

Exploracion aislada. Quieres que Claude intente un enfoque de refactorizacion riesgoso pero no quieres arruinar tu sesion 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 sesion principal esta profundamente metida en una tarea compleja y la ventana de contexto se esta llenando. En lugar de arriesgar perdida de contexto agregando mas 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 atencion enfocada. La revision de codigo, generacion de documentacion y escritura de tests son todas tareas donde un agente dedicado con instrucciones claras produce mejores resultados que meterlas en una sesion principal ocupada.

La Herramienta Agent

Internamente, Claude usa la herramienta Agent para lanzar subagentes. No necesitas invocar esta herramienta directamente -- Claude decide cuando usarla basandose en tu solicitud. Sin embargo, entender como funciona te ayuda a escribir mejores prompts.

Cuando Claude lanza un subagente, le proporciona:

Un prompt especifico describiendo la tarea
Un conjunto de herramientas permitidas (que puede ser un subconjunto de las herramientas de la sesion principal)
Cualquier contexto relevante de la conversacion 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 sesion principal.

Puedes influir en el comportamiento del subagente a traves de tus prompts. Si le pides a Claude que "investigue esto cuidadosamente y reporte con ejemplos de codigo," el subagente sera mas exhaustivo que si dices "verifica rapidamente si esto es factible."

Creando Subagentes Personalizados

Para patrones de delegacion 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.

Anatomia 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 documentacion no necesita la herramienta Bash. Un agente de exploracion 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 Documentacion

<!-- 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 documentacion. Esta restriccion previene que accidentalmente ejecute comandos mientras se enfoca en su tarea de escritura.

Equipos de Agentes

Para proyectos complejos que se benefician de colaboracion multi-agente, Claude Code soporta equipos de agentes. Cuando estan habilitados, multiples agentes pueden trabajar juntos en diferentes aspectos de una tarea, coordinandose a traves de la sesion 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 codigo de API existente, un tercero redacta el nuevo endpoint, y la sesion principal sintetiza todo en una implementacion final.

Esta funcionalidad es mas util para tareas grandes de multiples pasos donde diferentes aspectos requieren diferentes especializaciones.

Aislamiento con Worktrees

Para maxima 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 explicitamente.

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 el 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 ningun riesgo para tu estado actual.

Agentes en Segundo Plano

Algunas tareas de subagentes toman mucho tiempo -- ejecutar una suite completa de tests, realizar una auditoria comprensiva de codigo o generar documentacion 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 tu continuas con tu tarea principal. Cuando termina, recibes una notificacion con los resultados.

Cuando 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 sesion principal es mas rapido y barato.

No uses subagentes para:

Lecturas simples de archivos. Si solo necesitas ver que hay en un archivo, pregunta directamente.
Busquedas dirigidas. Si sabes donde buscar, senala a Claude ahi en lugar de generar un explorador.
Ediciones triviales. Cambiar el nombre de una variable o corregir un error tipografico 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 sesion principal. Si requiere exploracion significativa, podria beneficiarse de paralelismo o necesita aislamiento de tu trabajo principal, usa un subagente.

Mejores Practicas

Dale a los agentes prompts claros y especificos. En lugar de "revisa la base de codigo," intenta "analiza el flujo de autenticacion comenzando desde src/auth/login.ts, traza la logica de validacion de tokens a traves de todas las capas de middleware e identifica cualquier ruta donde un token expirado podria evadir la validacion." La especificidad produce resultados dramaticamente mejores de los subagentes.

Usa restricciones de herramientas para imponer limites de seguridad. Un agente de exploracion no deberia tener acceso de Write. Un agente de documentacion no deberia 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, revisalos en la sesion 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 minimo de herramientas que necesita. Luego inicia una sesion de Claude Code y pide a Claude que escriba tests para una funcion compleja y genere documentacion para un modulo, simultaneamente. Observa como 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 sesion principal que haga ambas tareas secuencialmente.