Claude managed agents: guía completa

La diferencia con un prompt normal es que el subagente tiene su propio contexto. No contamina la conversación principal. Puede trabajar en paralelo con otros subagentes. Y puede operar en un worktree separado (una copia aislada del código).

Es la evolución natural de trabajar con Claude Code: en lugar de un agente que hace todo secuencialmente, tienes un coordinador que delega a especialistas.

Cuándo usarlos (y cuándo no)

Usa managed agents cuando:

• La tarea tiene subtareas independientes que pueden ejecutarse en paralelo
• Necesitas que una subtarea no afecte al código mientras otra subtarea trabaja
• La complejidad de la tarea desborda un solo agente (demasiado contexto)
• Quieres separar responsabilidades (uno investiga, otro implementa, otro testea)

No los uses cuando:

• La tarea es simple y lineal (un solo agente basta)
• Las subtareas son dependientes secuencialmente (no ganas nada en paralelo)
• Estás en el plan gratuito (cada subagente consume tokens de tu cuota)

Arquitectura: coordinator + workers

Los managed agents siguen un patrón de arquitectura bien conocido en sistemas distribuidos: coordinator + workers. Entenderlo te permite diseñar flujos más eficientes.

El Coordinator (agente principal):

• Recibe tu petición y la descompone en subtareas
• Decide qué subtareas pueden ejecutarse en paralelo y cuáles son secuenciales
• Asigna cada subtarea a un worker (subagente)
• Recopila resultados, detecta conflictos y consolida el output final
• Mantiene el "mapa mental" de todo el proyecto

Los Workers (subagentes):

• Reciben una tarea acotada con contexto suficiente
• Trabajan en aislamiento (su propio contexto, opcionalmente su propio worktree)
• No se comunican entre ellos directamente
• Reportan resultado (éxito o fallo) al coordinator
• No tienen visibilidad del trabajo de otros workers

# Flujo típico coordinator + workers

[TU PETICIÓN]
      ↓
[COORDINATOR] → Descompone en 3 tareas
      ↓
  ┌───┼───┐
  ↓   ↓   ↓
[W1] [W2] [W3]  ← Trabajan en paralelo
  ↓   ↓   ↓
  └───┼───┘
      ↓
[COORDINATOR] → Consolida y reporta resultado
      ↓
[OUTPUT FINAL]

Este patrón evita el antipattern del "agente monolítico" que intenta hacer todo: investigar, diseñar, implementar, testear y documentar en un solo contexto. Con 200K tokens de ventana, un agente monolítico se degrada en calidad a partir del minuto 30 de trabajo continuo.

Worktrees: cada agente con su copia

El concepto más potente de los managed agents es el worktree. Un worktree es una copia aislada de tu repositorio git. Cada subagente puede trabajar en su propio worktree sin afectar al código principal.

Imagina que necesitas implementar 3 features independientes. Sin worktrees, cada feature se hace secuencialmente y los cambios se mezclan. Con worktrees:

• Subagente A trabaja en feature-1 en worktree-A
• Subagente B trabaja en feature-2 en worktree-B
• Subagente C trabaja en feature-3 en worktree-C

Los tres trabajan en paralelo, cada uno en su copia del código. Cuando terminan, fusionas los cambios. Es como tener 3 desarrolladores trabajando en ramas distintas.

Cuándo usar worktrees vs cuándo no:

• Usa worktree: El subagente modifica archivos del proyecto (implementar código, editar config, crear tests)
• No uses worktree: El subagente solo analiza (code review, investigación, generar documentación que no es código)

Cómo crear un flujo multi-agente

No necesitas configuración especial. Claude Code crea subagentes automáticamente cuando la tarea lo requiere. Pero puedes solicitarlo explícitamente:

> Necesito implementar estas 3 mejoras en paralelo:
 1. Añadir validación de formularios (frontend)
 2. Crear endpoint de exportación CSV (backend)
 3. Escribir tests E2E para el flujo de checkout

 Usa subagentes separados para cada tarea.
 Cada uno en su propio worktree.
 Cuando terminen, muéstrame un resumen de los cambios.

Claude Code creará 3 subagentes, cada uno con su worktree, y coordinará el resultado. Tú solo ves el resumen final.

Ejemplo: pipeline de desarrollo

Un patrón potente es crear un pipeline donde cada subagente tiene un rol:

Coordinador (agente principal):

> Implementa la feature de notificaciones push.
 Usa este pipeline:
 1. Subagente ARCHITECT: diseña la estructura (esquema DB,
 endpoints, componentes). No escribe código.
 2. Subagente DEV: implementa basándose en el diseño.
 3. Subagente QA: escribe y ejecuta tests.
 4. Subagente DOCS: documenta los endpoints y componentes.

 Cada fase espera a que la anterior termine.
 Si QA encuentra bugs, DEV los corrige.

Este pipeline replica un flujo de desarrollo real: diseño, implementación, testing, documentación. Cada rol tiene su especialidad y su contexto separado.

Es el mismo patrón que usamos internamente para proyectos complejos. Si te interesa cómo se diseñan estos flujos, consulta nuestra guía de cadena de prompts para entender la lógica secuencial.

Workflows reales con managed agents

Más allá del pipeline básico, hay patrones de workflow que hemos validado en producción:

1. Refactoring masivo:

> Migra todos los componentes de Class Components a
 Functional Components con hooks. El proyecto tiene 47
 componentes. Asigna un subagente por módulo:
 - Subagente AUTH: /src/components/auth/ (8 componentes)
 - Subagente DASHBOARD: /src/components/dashboard/ (12 componentes)
 - Subagente FORMS: /src/components/forms/ (15 componentes)
 - Subagente COMMON: /src/components/common/ (12 componentes)
 Cada uno en su worktree. Tests deben pasar después de cada migración.

2. Code review distribuido:

> Revisa este PR desde 3 perspectivas:
 - Subagente SECURITY: busca vulnerabilidades (inyección SQL,
   XSS, secrets expuestos, permisos incorrectos)
 - Subagente PERFORMANCE: identifica N+1 queries, renders
   innecesarios, memory leaks potenciales
 - Subagente ARCHITECTURE: evalúa adherencia a clean architecture,
   separación de concerns, naming conventions

 Consolida en un solo reporte con prioridades (critical/high/medium/low).

3. Generación de contenido paralela:

> Genera la documentación completa del módulo de pagos:
 - Subagente API-DOCS: documenta los 8 endpoints (OpenAPI spec)
 - Subagente USER-GUIDE: escribe guía de usuario (cómo pagar,
   gestionar suscripción, facturas)
 - Subagente DEV-GUIDE: escribe guía de integración para
   desarrolladores (webhooks, testing, sandbox)

 Todos en paralelo. Resultado en /docs/payments/

Modelo de permisos

Los managed agents heredan los permisos del agente principal, pero con restricciones configurables:

Permisos por defecto:

• Leer cualquier archivo del proyecto
• Escribir archivos en su worktree (si tiene uno)
• Ejecutar comandos de terminal (con las mismas restricciones que el agente principal)
• Instalar dependencias (si está permitido en la configuración)

Restricciones recomendadas:

• Los subagentes de análisis (review, investigación) no deberían tener permiso de escritura
• Los subagentes de implementación no deberían poder pushear a remoto
• Ningún subagente debería poder modificar archivos de configuración críticos (.env, secrets)

Puedes controlar esto a través del fichero settings.json y las instrucciones específicas que das al coordinator.

Monitorización y observabilidad

Con múltiples agentes trabajando en paralelo, necesitas visibilidad sobre qué está pasando:

Lo que Claude Code te muestra:

• Estado de cada subagente (trabajando, completado, fallado)
• Resumen del output de cada subagente al terminar
• Conflictos de merge detectados al fusionar worktrees
• Consumo de tokens por subagente

Lo que deberías monitorizar tú:

• Tiempo total del flujo (para optimizar en iteraciones futuras)
• Ratio de éxito de subagentes (si uno falla frecuentemente, su tarea está mal definida)
• Calidad del output (¿el coordinator consolida bien? ¿se pierde información?)
• Tokens consumidos vs valor generado (¿merece la pena el coste de paralelizar?)

Para proyectos con agentes en producción, herramientas como OpenTelemetry, Langfuse o incluso un simple log estructurado te dan la visibilidad necesaria.

Manejo de errores y recuperación

Los subagentes pueden fallar. Un flujo robusto anticipa fallos y tiene estrategias de recuperación:

Tipos de fallo comunes:

• Timeout: El subagente tarda demasiado (tarea demasiado grande o ambigua)
• Error de contexto: El subagente no tiene suficiente información para completar la tarea
• Conflicto de merge: Dos subagentes modificaron el mismo archivo
• Tests fallidos: El código generado no pasa los tests existentes

Estrategias de recuperación:

1. Retry con más contexto: Si el subagente falló por falta de información, el coordinator le pasa contexto adicional y reintenta.
2. Subdivisión: Si la tarea era demasiado grande, el coordinator la divide en partes más pequeñas.
3. Fallback manual: Si el subagente falla dos veces, el coordinator te notifica para que decidas (intervención humana).
4. Merge manual: Si hay conflictos de worktree, el coordinator te muestra los conflictos y tú decides la resolución.

Escalado: de 2 a 10 agentes

Empezar con 2 subagentes es trivial. Escalar a 5 o 10 requiere pensar en coordinación:

2-3 subagentes: El coordinator gestiona todo directamente. Un prompt describe las tareas, el coordinator asigna y consolida. Simple y efectivo.

4-6 subagentes: Necesitas ser más explícito en las instrucciones al coordinator. Define orden de ejecución, dependencias entre tareas, y criterios de éxito por subagente.

7-10 subagentes: Considera un patrón de "sub-coordinators". Un coordinator principal que delega a 2-3 sub-coordinators, cada uno gestionando 3-4 workers. Esto replica la estructura de un equipo de desarrollo real (tech lead con senior devs que coordinan a juniors).

Más de 10: Probablemente no lo necesitas. Si tu tarea requiere 10+ agentes en paralelo, es mejor dividirla en 2-3 flujos secuenciales de 3-5 agentes cada uno.

Comparación con otros frameworks de agentes

Los managed agents de Claude Code no son la única opción. Cómo se comparan con alternativas:

Claude Code managed agents:

• Ventaja: zero-config, nativo, no requiere código
• Ventaja: worktrees integrados con git
• Limitación: solo funciona con Claude como modelo
• Limitación: menos control granular que frameworks de código
• Ideal para: equipos de desarrollo que usan Claude Code como herramienta principal

LangGraph (Python):

• Ventaja: control total sobre flujo, state y decisiones
• Ventaja: model-agnostic (funciona con cualquier LLM)
• Limitación: requiere Python y setup significativo
• Ideal para: sistemas de agentes en producción con lógica compleja

CrewAI:

• Ventaja: abstracción de alto nivel, fácil de empezar
• Ventaja: roles y goals predefinidos
• Limitación: menos flexible para flujos no estándar
• Ideal para: prototipos rápidos de flujos multi-agente

Autogen (Microsoft):

• Ventaja: conversación multi-agente natural
• Ventaja: integración con Azure y herramientas Microsoft
• Limitación: más orientado a chat que a ejecución de tareas
• Ideal para: flujos conversacionales donde agentes debaten

Buenas prácticas

• Tareas claras y acotadas: Cada subagente necesita un objetivo específico. "Implementa el backend" es vago. "Crea el endpoint POST /api/notifications con validación Pydantic" es claro.
• Worktrees para cambios de código: Si el subagente modifica archivos, usa worktree. Si solo analiza (code review, investigación), no hace falta.
• Limita el paralelismo: 3-5 subagentes en paralelo es manejable. Más de 5 genera conflictos de merge y complejidad innecesaria.
• El coordinador debe verificar: No confíes ciegamente en el resultado de los subagentes. El agente principal debe revisar y consolidar.
• Presupuesto de tokens: Cada subagente consume tokens. Un pipeline de 4 subagentes consume 4-5x más que hacerlo todo en el agente principal. Asegúrate de que la ganancia en velocidad y calidad justifica el coste.
• Contexto mínimo viable: Dale a cada subagente solo el contexto que necesita. Un subagente de tests no necesita saber la arquitectura completa del sistema; necesita saber qué testear y cómo.
• Define "done": Para cada subagente, define explícitamente qué significa "tarea completada". Sin criterios claros, un subagente puede reportar éxito cuando el resultado es incompleto.

Siguiente paso

Empieza con un caso simple: dos subagentes para una tarea que naturalmente se divide en dos partes independientes. Cuando domines el patrón, escala a pipelines más complejos.

Antes de usar managed agents, asegúrate de dominar los fundamentos: CLAUDE.md, settings.json y skills. Los managed agents son la capa avanzada que se construye sobre esas bases.

Una vez que tengas experiencia con flujos de 3-5 agentes, experimenta con patrones de sub-coordinators para proyectos más grandes. Y recuerda: la complejidad debe estar justificada por el resultado. Si un solo agente resuelve tu tarea con calidad suficiente, no añadas complejidad innecesaria.