Claude Code workflows: orquesta agentes con un script

Le pides a Claude Code que revise los archivos que cambiaron en tu rama. Sin Claude Code workflows, lanza tres subagentes, luego dos más, y el contexto se llena de informes a medias. A mitad de camino ya no recuerda qué dijo el primero.

El problema no es el modelo. Es que el plan vive en su cabeza, turno a turno.

Los Claude Code workflows sacan ese plan de la cabeza del modelo y lo meten en un script. Eso arregla la coordinación y abre otro problema: un script que lanza 40 agentes solo te avisa del gasto cuando ya está corriendo, y el aviso no lo frena.

En corto: un workflow de Claude Code es un script JavaScript que Claude escribe y un runtime ejecuta en segundo plano, lanzando subagentes con agent(), pipeline() y parallel(). Se activa con la palabra ultracode o pidiéndolo explícitamente, y se guarda en .claude/workflows/ para reutilizarlo. Cada agente gasta tokens propios, así que fija una guía de tamaño y pruébalo antes sobre una parte pequeña.

Si te conviene un sistema multiagente lo discuto en cómo orquestar subagentes en Claude Code y en harness multiagente frente a un solo agente. Aquí va el cómo.

¿Qué son los Claude Code workflows?

Un workflow (en la documentación, "dynamic workflow") es un script JavaScript que orquesta muchos subagentes a la vez: Claude lo escribe para tu tarea y un runtime aislado lo ejecuta en segundo plano mientras tu sesión sigue libre.

Con subagentes normales decide Claude, turno a turno, y cada resultado vuelve a su contexto. Con un workflow decide el script: los resultados intermedios viven en variables y a Claude solo le llega el final.

Llegó en la v2.1.154 como research preview, según las novedades de esa semana. La documentación de dynamic workflows (consultada en octubre de 2026) los da por disponibles en todos los planes de pago, la API de Anthropic, Bedrock, Google Cloud y Microsoft Foundry. En Pro se activan en /config.

Cómo se activan los Claude Code workflows y quién los autoriza

Hay tres puertas de entrada, y todas las abres tú:

1. Petición explícita. Escribes ultracode en el prompt o dices "usa un workflow". Vale para esa tarea. Antes de la v2.1.160 la palabra clave era workflow.
2. Ultracode en toda la sesión. /effort ultracode hace que Claude planifique un workflow para cada tarea sustancial. claude --effort ultracode arranca así y además sube el esfuerzo a xhigh (v2.1.203 o posterior).
3. Workflows guardados. /deep-research viene incluido, y los tuyos se ejecutan como /<nombre>.

Desde la v2.1.210 la palabra solo actúa en un prompt que escribes tú: no dispara nada si llega por -p, por una tarea programada o por un comentario de PR.

Antes de arrancar, Claude Code te enseña las fases y te deja ver el script. En modo manual pregunta en cada ejecución, salvo que marques "no volver a preguntar" para un workflow guardado; en modo auto, solo la primera vez, y ni eso con ultracode activo. Con claude -p no hay diálogo (lo detallo en las preguntas frecuentes).

Anatomía de un script: meta, phase y agent

Todo script empieza con export const meta = { name, description } como objeto literal. Después viene JavaScript plano con await de primer nivel:

Función	Qué hace
agent(prompt, opts)	Lanza un subagente. Con schema devuelve JSON validado
pipeline(items, fn)	Lanza un agente por cada elemento de la lista
parallel(...)	Ejecuta un conjunto de tareas de agente a la vez y espera a todas
phase(title)	Agrupa los agentes siguientes bajo un título en la vista de progreso
log(msg) y args	Mensaje sobre las fases y entrada de un workflow guardado

El script no toca disco ni shell ni admite import(). Date.now() y Math.random() lanzan error: para reanudar, una reejecución debe repetir las mismas llamadas.

Ejemplo de workflow en Claude Code: revisar una rama por dimensiones

Un caso típico: revisar cada archivo cambiado por dimensiones e intentar refutar cada hallazgo antes de enseñártelo. Solo usa la API documentada:

export const meta = {
  name: 'review-branch',
  description: 'Revisa los archivos cambiados por dimensiones y verifica cada hallazgo',
}

const base = args?.base ?? 'main'
const str = { type: 'string' }
const findingsSchema = {
  type: 'object', required: ['findings'],
  properties: { findings: { type: 'array', items: {
    type: 'object', required: ['file', 'line', 'issue'],
    properties: { file: str, line: { type: 'number' }, issue: str },
  } } },
}
const verdictSchema = {
  type: 'object', required: ['confirmed', 'reason'],
  properties: { confirmed: { type: 'boolean' }, reason: str },
}

phase('Descubrir')
const changed = await agent(`Ejecuta git diff --name-only ${base}...HEAD y devuelve los archivos .ts cambiados.`, {
  label: 'git diff',
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: str } } },
})

const dimensions = ['correctness', 'security', 'tests']
const tasks = changed.files.flatMap(file => dimensions.map(dimension => ({ file, dimension })))

phase('Revisar')
const reviews = await pipeline(tasks, ({ file, dimension }) =>
  agent(`Revisa ${file} solo desde la dimensión ${dimension}. Devuelve hallazgos con número de línea.`, {
    label: `${dimension}: ${file}`, schema: findingsSchema,
  }),
)
const findings = reviews.filter(Boolean).flatMap(review => review.findings)

phase('Verificar')
const verdicts = await pipeline(findings, finding =>
  agent(`Intenta refutar este hallazgo leyendo el código. Confírmalo solo si se sostiene: ${JSON.stringify(finding)}`, {
    label: `verify ${finding.file}:${finding.line}`, schema: verdictSchema,
  }),
)

return findings.filter((finding, i) => verdicts[i]?.confirmed)

El primer agente existe solo para ejecutar git diff, porque el script no puede. Y pipeline() deja null en el hueco de un agente que falla, de ahí el .filter(Boolean). Añade Bash(git diff:*) a tus reglas allow antes de lanzarlo: un permiso pendiente pausa la ejecución.

No hace falta escribirlo a mano: se lo pides a Claude y, si te convence, lo guardas desde /workflows con s, en .claude/workflows/ (compartido) o en ~/.claude/workflows/ (solo tú). Es el paso de idea a proceso repetible que trabajamos en el curso Construye con IA.

Cuánto cuestan los Claude Code workflows

Un workflow cuesta, como mínimo, la suma de lo que gasta cada agente: cada llamada a agent() envía sus propias peticiones y cuenta contra los límites de tu plan. Por eso una ejecución gasta bastantes más tokens que la misma tarea en la conversación.

Haz la cuenta del ejemplo. Con 5 archivos y 3 dimensiones tienes 1 agente de descubrimiento y 15 de revisión: 16 antes de verificar nada. Con 10 hallazgos, 26. Ya pasaste el umbral de 25 agentes en el que aparece el aviso Large workflow, que también salta si se prevén más de 1,5 millones de tokens. Ojo: si eliges tú una guía de tamaño, su número sustituye a los 25, así que con small el aviso salta por encima de 5 agentes. Y con ultracode activo no aparece nunca.

Ese aviso no frena nada. Lo que controlas es la guía de tamaño: en /config desde la v2.1.202, y como clave workflowSizeGuideline en cualquier settings y con medium por defecto desde la v2.1.219:

Valor	Agentes que Claude intenta no superar
small	Menos de 5
medium (por defecto; small en Pro desde la v2.1.271)	Menos de 10 (menos de 15 antes de la v2.1.271)
large	Menos de 50
unrestricted	Sin guía: Claude dimensiona según la tarea

Es un consejo para Claude al escribir el script, no un tope. Los topes duros del runtime son 1.000 agentes por ejecución y 4.096 elementos por llamada a pipeline() o parallel(). Los 16 concurrentes por defecto limitan cuántos corren a la vez, no cuántos se lanzan.

No es teoría. En el issue #92631 un usuario documenta que con ultracode activo la guía deja de tener efecto y tareas pequeñas lanzan más de 50 agentes. En el #98400 otro reporta más de 70 con medium.

Mi opinión: no actives ultracode para toda la sesión. Pide el workflow cuando lo quieras y pon small mientras aprendes. /workflows enseña los tokens de cada agente y te deja parar con x. Si cambias de modelo, lee por qué el coste de los subagentes sube al cambiar de modelo: sin otra indicación, los agentes usan el modelo de tu sesión.

Workflow, subagentes a mano o claude -p: qué elegir

Usa un workflow cuando la tarea necesita más agentes de los que una conversación puede coordinar o quieres repetir la orquestación; para dos o tres tareas delegadas bastan los subagentes, y para control total desde CI, un bucle con claude -p.

Criterio	Workflow	Subagentes a mano	Bucle con claude -p
Quién decide el siguiente paso	El script	Claude, turno a turno	Tu script de shell
Dónde viven los resultados	Variables del script	Contexto de Claude	Ficheros o stdout
Escala razonable	Decenas a cientos de agentes	Unos pocos por turno	La que programes
Reanudación	En la sesión, con caché por agente	Reinicia el turno	La que programes
Riesgo principal	Gasto que crece sin verlo venir	Contexto saturado	Mantienes tú la orquestación

Cómo se reanuda un workflow parado

Una ejecución pausada se reanuda desde /workflows con p. Si la detuviste, pides a Claude que la relance (por debajo, resumeFromRunId). Funciona en la misma sesión o en una recuperada con claude --resume.

Los agentes completados devuelven su resultado guardado. Pero si uno falla o cambia su prompt, se repiten ese agente y todos los que arrancaron después. Si arrancan A, B, C y D y falla B, vuelves a pagar B, C y D, aunque C y D ya hubieran terminado.

Desde la v2.1.271, si chocas con el límite de uso de tu suscripción, la ejecución se pausa en vez de fallar. Solo pasa en una sesión interactiva con autoContinueAtUsageLimit activo, si el límite se reinicia en menos de 24 horas y como mucho dos veces por ejecución. El issue #98299 reporta 26 agentes que fallaron igualmente en la app de escritorio con la v2.1.281: no cuentes con ello a ciegas.

Límites de los Claude Code workflows

No hay pasos deterministas de shell. Ejecutar npm test exige envolverlo en un agent(), que gasta tokens y puede parafrasear el comando. Está pedido en el issue #98566, todavía abierto.

No puedes intervenir a mitad. Si necesitas aprobar entre fases, cada fase tiene que ser un workflow distinto.

El resultado depende de tus prompts. Un workflow multiplica un mal prompt por 40. La especificación va antes que el orquestador; es la tesis del libro de Spec-Driven Development.

Cómo probar Claude Code workflows sin quemar tu cuota

Hoy puedes hacer una cosa: /config workflowSizeGuideline=small, pedir un workflow que revise una sola carpeta y mirar en /workflows cuánto gasta cada agente. Con ese número sabes si escalar compensa.

Si quieres llevarlo a un proceso de equipo, con contratos de revisión y AGENTS.md, es lo que hacemos en el workshop SDD + Agentic Engineering.

Preguntas frecuentes

¿Qué versión de Claude Code necesito para usar workflows?

La v2.1.154 o posterior. La guía de tamaño pide la v2.1.202 y la pausa por límite de uso, la v2.1.271.

¿Dónde se guardan los Claude Code workflows?

En .claude/workflows/ del proyecto o en ~/.claude/workflows/. Si coinciden los nombres, gana el del proyecto. Cada ejecución deja además su script dentro de ~/.claude/projects/.

¿Puedo ejecutar un workflow en CI con claude -p?

Sí, pidiéndolo con tus palabras o lanzando uno guardado; la palabra ultracode no lo dispara ahí. No hay diálogo de aprobación, así que necesitas que algo apruebe la llamada: una regla Workflow (o Workflow(<nombre>) para uno guardado) en tus permisos, un hook PreToolUse, el modo auto, el modo bypass o --permission-prompt-tool.

¿Cómo desactivo los workflows?

Con el ajuste Dynamic workflows en /config (escribe "enableWorkflows": false en tu settings de usuario), con "disableWorkflows": true o con CLAUDE_CODE_DISABLE_WORKFLOWS=1. Desactivarlos también quita ultracode.

---

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.