Patrones de orquestación en Claude Code

La mayoría de los tutoriales sobre agentes de IA muestran un agente haciendo todo. Eso funciona para demos, pero no para producción.

Cuando el problema se vuelve complejo, un solo agente se confunde, pierde contexto o produce resultados inconsistentes.

La solución es orquestar múltiples agentes con roles específicos. Claude Code tiene las herramientas para hacerlo directamente desde archivos .md. Sin frameworks externos. Sin código.

Hoy repasaremos 5 patrones fundamentales con ejemplos reales.

Cómo funciona la orquestación en Claude Code

Antes de los patrones, el mecanismo base:

Un skill es un archivo .md en .claude/commands/. Cuando escribes /mi-skill argumento, Claude lee ese archivo, reemplaza $ARGUMENTS con tu input y lo ejecuta como prompt.
La herramienta Agent permite que Claude spawne una instancia nueva de sí mismo con un prompt específico. Esa instancia retorna un resultado y termina.
El orquestador es el agente principal que coordina a los demás. También es un skill .md.

# .claude/commands/mi-orquestador.md

Eres el orquestador. Tu trabajo es $ARGUMENTS.

Paso 1: Usa la herramienta Agent con este prompt:
"Busca información sobre $ARGUMENTS en la web."

Paso 2: Con los resultados del paso 1, usa la herramienta Agent:
"Resume esto en 3 puntos clave: [resultado del paso 1]"

Eso es todo. El resto es saber qué patrón aplicar según el problema.

Source: Anthropic — Build with Claude: Tool use and agents

Patrón 1: Pipeline

Qué es

Una cadena lineal donde cada agente toma el output del anterior. El más simple y el más común.

Agente A → Agente B → Agente C → Resultado

Cuándo usarlo

Cuando las tareas son secuenciales y dependientes. El paso 2 necesita el resultado del paso 1 para funcionar.

Ejemplo

Un sistema que investiga una empresa y genera un reporte:

# .claude/commands/company-researcher.md
# company-researcher

Orquestador para investigar una empresa: $ARGUMENTS

Paso 1 — Búsqueda general
Usa la herramienta Agent:
"Busca en la web información general sobre la empresa $ARGUMENTS.
Retorna: nombre, industria, tamaño, sitio web, qué hace."

Paso 2 — Descubrimiento de contactos
Usa la herramienta Agent con el resultado del paso 1:
"Busca personas clave en $ARGUMENTS: CEO, CTO, Head of Partnerships.
Retorna: nombre, rol, dónde fue encontrado."

Paso 3 — Reporte final
Usa la herramienta Agent con todos los resultados anteriores:
"Compila un reporte en Markdown con la información de la empresa y sus contactos."

Riesgo principal

Si un paso retorna datos mal formateados, el siguiente puede interpretarlos incorrectamente. La solución es ser explícito en el formato de output de cada skill.

Patrón 2: Fan-out / Fan-in

Qué es

El orquestador divide el trabajo en tareas independientes, las ejecuta en paralelo y luego combina los resultados.

             ┌─ Agente A ─┐
Orquestador ─┤─ Agente B ─├─ Orquestador (combina)
             └─ Agente C ─┘

Cuándo usarlo

Cuando tienes múltiples ítems del mismo tipo que procesar y no dependen entre sí. Perfecto para reducir tiempo de ejecución.

Ejemplo

Investigar 3 contactos de una empresa al mismo tiempo:

# .claude/commands/profile-all-contacts.md
# profile-all-contacts

Recibe una lista de contactos como $ARGUMENTS.
Formato esperado: "Nombre1, Rol1 | Nombre2, Rol2 | Nombre3, Rol3"

Fan-out: lanza estos agentes EN PARALELO (son independientes entre sí):

- Agente 1: "Investiga el perfil profesional de [Nombre1], [Rol1].
  Retorna: background, intereses públicos, canal de contacto recomendado."

- Agente 2: "Investiga el perfil profesional de [Nombre2], [Rol2].
  Retorna: background, intereses públicos, canal de contacto recomendado."

- Agente 3: "Investiga el perfil profesional de [Nombre3], [Rol3].
  Retorna: background, intereses públicos, canal de contacto recomendado."

Fan-in: cuando los tres terminen, combina los perfiles en una sola lista Markdown.

La clave está en escribir "EN PARALELO (son independientes entre sí)". Claude interpreta esa instrucción y lanza los Agent calls en una sola respuesta en lugar de esperar uno por uno.

Source: Anthropic — Multi-agent systems

Patrón 3: Critic (Crítico)

Qué es

Un agente genera. Otro agente revisa. El primero corrige. Puede iterar N veces.

Agente Generador → Agente Crítico → Agente Generador (revisión) → Resultado

Cuándo usarlo

Cuando la calidad del output importa más que la velocidad. Mensajes de outreach, código que será revisado por humanos, documentos formales.

Ejemplo

Generar y revisar un mensaje de contacto:

# .claude/commands/message-with-review.md
# message-with-review

Genera y revisa un mensaje de outreach para: $ARGUMENTS
Formato: "Nombre | Rol | Empresa | Propósito"

Paso 1 — Generación
Usa la herramienta Agent:
"Escribe un mensaje corto de outreach (máx 5 oraciones) para:
Contacto: $ARGUMENTS
Tono: profesional pero humano. Sin aperturas genéricas."

Paso 2 — Revisión crítica
Usa la herramienta Agent con el mensaje del paso 1:
"Eres un crítico de comunicación B2B. Revisa este mensaje:
[mensaje del paso 1]

Evalúa:
- ¿Suena como spam? (sí/no + por qué)
- ¿El tono es adecuado?
- ¿El llamado a la acción es claro?
- Sugiere una versión mejorada si hay problemas."

Paso 3 — Versión final
Si el crítico sugirió cambios, usa su versión mejorada.
Si aprobó el mensaje, usa el original.
Retorna solo el mensaje final listo para enviar.

Variante avanzada

Puedes hacer que el crítico sea un agente especializado con su propio skill .md, con reglas de revisión detalladas. Así reutilizas el mismo crítico en múltiples flujos.

Patrón 4: Specialist Team (Equipo Especializado)

Qué es

Cada agente tiene un rol estrictamente definido y solo hace esa tarea. El orquestador asigna trabajo según el rol.

Orquestador
├── Agente Investigador (solo busca)
├── Agente Redactor (solo escribe)
└── Agente Verificador (solo valida datos)

Cuándo usarlo

Cuando un agente generalista produce resultados mediocres porque intenta hacer demasiado. Dividir responsabilidades genera outputs más precisos y consistentes.

Ejemplo

Skills especializados para el sistema de partner briefs:

# .claude/commands/researcher-agent.md
# researcher-agent

Eres exclusivamente un agente de investigación. Tu único trabajo es buscar y retornar datos.
NO redactes, NO opines, NO interpretes.

Tarea: $ARGUMENTS

Usa WebSearch y WebFetch para encontrar los datos solicitados.
Retorna los resultados en formato estructurado con la fuente de cada dato.
Si no encuentras un dato, escribe "NO ENCONTRADO" — no inventes.

# .claude/commands/writer-agent.md
# writer-agent

Eres exclusivamente un agente de redacción. Tu único trabajo es escribir.
NO busques información, NO verifiques datos. Usa solo lo que te proveen.

Datos de entrada: $ARGUMENTS

Redacta el contenido solicitado con tono profesional y directo.
Máximo 150 palabras salvo que se indique lo contrario.

El orquestador llama primero al researcher-agent, luego pasa sus resultados al writer-agent. Ninguno hace el trabajo del otro.

Por qué funciona mejor

Un agente con un prompt enfocado comete menos errores. Al no tener que "decidir" si busca o escribe, toda su capacidad va a hacer bien esa única tarea.

Source: Anthropic — Agents overview

Patrón 5: Map-Reduce

Qué es

Una extensión del Fan-out aplicada a colecciones de datos. Divide una lista en ítems, procesa cada uno en paralelo (map), y combina todos los resultados en un output unificado (reduce).

Input: [Empresa A, Empresa B, Empresa C]
Map:    Agente A    Agente B    Agente C   (paralelo)
Reduce:        Orquestador combina
Output: Reporte consolidado

Cuándo usarlo

Para procesar listas. Múltiples empresas, múltiples tickets de soporte, múltiples PRs. Cualquier cosa donde el mismo flujo se aplica a N ítems.

Ejemplo

Generar un digest semanal investigando varias empresas:

# .claude/commands/weekly-digest.md
# weekly-digest

Genera un digest de partner briefs para esta lista de empresas: $ARGUMENTS
Formato esperado: "Empresa1, Empresa2, Empresa3"

MAP — Para cada empresa en la lista, lanza un agente EN PARALELO:
"Ejecuta una investigación completa de [Empresa].
Retorna: resumen de la empresa, 2-3 contactos clave con sus perfiles."

(Todos los agentes del map son independientes entre sí.)

REDUCE — Cuando todos los agentes terminen, usa la herramienta Agent:
"Tienes los siguientes reportes de empresas:
[resultados del map]

Compílalos en un digest semanal en Markdown con esta estructura:
- Una sección por empresa
- Tabla comparativa al final (empresa, industria, contacto principal, canal recomendado)
- Fecha del reporte: [fecha de hoy]"

Guarda el resultado como weekly-digest-[YYYY-MM-DD].md

Uso con el scheduler de Claude Code

Este patrón es ideal para tareas programadas. Combinado con /schedule:

/schedule weekly on Monday at 7am run /weekly-digest Stripe, Notion, Figma

Cada lunes a las 7am, Claude investiga las tres empresas en paralelo y genera un digest consolidado automáticamente.

Cuándo usar cada patrón

Situación	Patrón recomendado
Tareas secuenciales con dependencias	Pipeline
Múltiples ítems independientes	Fan-out / Fan-in
Output de alta calidad requerido	Critic
Tareas complejas con roles distintos	Specialist Team
Procesar una lista de N ítems	Map-Reduce

Los patrones también se combinan. Un pipeline puede tener un Fan-out en el paso 3 y un Critic en el paso 5. No son mutuamente excluyentes.

El error más común

Poner demasiada lógica en un solo agente. Si tu skill .md tiene 10 pasos y 500 palabras, es una señal de que deberías dividirlo en múltiples agentes especializados. Los prompts largos aumentan la probabilidad de que Claude pierda instrucciones del principio cuando llega al final.

La regla práctica: si un skill hace más de una cosa bien definida, divide.

Recursos

Keywords: claude code agents, orquestación de agentes IA, multi-agent systems, claude skills, patrones de orquestación

Meta description: Aprende los cinco patrones de orquestación en Claude Code: Pipeline, Fan-out/Fan-in, Critic, Specialist Team y Map-Reduce. Guía práctica con ejemplos en archivos .md.