Trabajo paralelo con Claude Code: worktree, Agents y Workflows

Materiales prácticos para trabajar con agentes en paralelo: documentación de Ailoot.

Esta guía reúne experiencia práctica y un mapa de dónde se aplican las herramientas. Incluye las cuatro primitivas oficiales de Claude Code, un mapa de sus usos y un marco contra el hype para determinar cuántos agentes en paralelo necesita realmente un vibe coder. Todas las cifras y citas enlazan con fuentes primarias de Anthropic.

¿Qué es el modo multiagente en Claude Code y por qué no son «1000 agentes»?#

Una configuración multiagente es aquella en la que una tarea se divide en varios flujos de trabajo independientes, cada uno se ocupa de su parte y devuelve un resultado. El ejemplo más sencillo: escribes el frontend en una ventana de Claude Code y el backend en otra ventana en la misma máquina, con un repositorio git compartido entre ambas. Eso ya es trabajo multiagente, aunque «orquestación» sería una palabra innecesariamente grandilocuente para describirlo.

Una configuración más compleja: dentro de una sesión de Claude Code, inicias cinco subagentes con distintos roles (desarrollador de frontend, desarrollador de backend, revisor de seguridad, tester, redactor de documentación), y cada uno devuelve su parte del resultado a la conversación compartida. Es el mismo enfoque multiagente, pero con un único punto de control.

Una configuración aún más compleja: le dices a Claude «haz una auditoría de seguridad semanal de los 500 archivos de mi proyecto» y Claude escribe un script de orquestación en JavaScript. El runtime inicia varias decenas de agentes en segundo plano; cada uno audita su propia sección. Después, agentes independientes revisan los hallazgos de los demás y tú recibes un único informe. Eso son los Dynamic Workflows, publicados por Anthropic el 28 de mayo de 2026. Encontrarás un análisis detallado de la función en la guía aparte sobre Dynamic Workflows.

La diferencia entre estos tres escenarios no está en el número de agentes. La diferencia está en quién decide qué hará el siguiente agente. En el primer escenario, eres tú. En el segundo, Claude decide a medida que avanza la conversación. En el tercero, lo decide un script de JavaScript escrito por Claude.

Por cierto, «1000 agentes» es una cifra real. Es el límite superior de un Dynamic Workflow en Claude Code. La documentación oficial de Anthropic dice:

En otras palabras, es una protección técnica contra comportamientos descontrolados, no una carga de trabajo recomendada. En la práctica, entre 2 y 8 flujos de trabajo paralelos resuelven el 95 % de las tareas. Si estás pensando en usar más, pregúntate primero qué harán.

Las 4 primitivas de Claude Code: subagentes, skills, agent teams y workflows#

Claude Code cuenta con cuatro primitivas oficiales para dividir una tarea entre varios agentes. Anthropic las reunió en una tabla comparativa en la documentación de Dynamic Workflows. Aquí tienes la comparación en lenguaje sencillo:

Cada una de estas primitivas resuelve un problema distinto. Los subagentes sirven para delegar 2–3 comprobaciones dentro de una tarea. Las skills son útiles cuando tienes instrucciones preparadas que Claude debe seguir (por ejemplo, «haz una revisión de PR con esta lista de comprobación»). Los agent teams sirven cuando distintas partes de un producto están en ventanas diferentes y necesitas un coordinador. Los workflows son para tareas demasiado grandes para una sola ventana de contexto.

Los subagentes se explican en detalle en la guía Claude Code Subagents 2026. El árbol de decisiones para elegir «qué usar en una tarea concreta» está en la guía de Skills, Subagents, MCP y Plugins. Esta guía trata de cómo reunirlos en una configuración multiagente basada en git worktree.

Nivel 1: subagentes en una sesión, la forma más sencilla de empezar#

Un subagente es la forma más sencilla de dividir una tarea. La conversación principal coordina el trabajo. Los subagentes son trabajadores temporales que el agente principal inicia a medida que avanza.

Un ejemplo concreto del proyecto descrito. Después del primer borrador de una guía, la revisión se organiza así: Claude recibe esta petición: «inicia seis subagentes en paralelo: uno busca marcadores de IA; el segundo, vocabulario legal; el tercero revisa la voz y el tono; el cuarto verifica los hechos con WebFetch; el quinto revisa la estructura SEO; y el sexto comprueba la exactitud de los enlaces cruzados». Cada uno devuelve un informe y, después, se aplican las modificaciones.

Técnicamente, esto se hace con archivos en .claude/agents/[subagent-name].md que describen el rol y las herramientas. La llamada se realiza mediante la herramienta Agent en la conversación principal. Claude decide cuándo enviar una solicitud a un subagente.

Cuándo funciona. Para tareas con 3–7 comprobaciones paralelas de un mismo artefacto (código, texto, diseño). Cada comprobación es independiente. Los resultados caben en la ventana de contexto principal.

Cuándo se queda corto. Si tienes más de 50 archivos o cada comprobación necesita su propio contexto de 50K tokens, la ventana principal se llenará. Necesitas workflows o agent teams.

Riesgo principal. Cada subagente consume tokens por separado. Si inicias seis en un proyecto de 200 archivos y cada uno vuelve a leer los 200, pagas 6×. Por eso DEBES especificar exactamente qué archivos debe revisar cada subagente. Consulta la guía sobre el consumo de tokens en Claude Code para obtener más detalles.

Nivel 2: git worktree, aislar archivos entre sesiones paralelas#

Cuando los subagentes no bastan y necesitas dos instancias completas de Claude Code en terminales distintos trabajando en el mismo repositorio, surge un problema clásico. Empiezan a editar el mismo archivo; una guarda primero y la otra sobrescribe sus cambios. La semana pasada, un cliente preguntó al equipo de soporte: «5 se están sobrescribiendo entre sí al mismo tiempo».

La solución es git worktree. Es una función integrada de git que permite tener varias copias de trabajo del mismo repositorio, cada una en su propia rama y con un repositorio .git compartido. Un origen, directorios distintos en el disco y ningún solapamiento entre sus archivos. El mecanismo se explica en detalle en la guía de Git worktree en Claude Code.

Comandos para configurarlo en cinco minutos:

# From the main project directory
cd ~/projects/my-app

# Create a worktree for feature/auth
git worktree add ../my-app-auth feature/auth

# Create a worktree for feature/billing
git worktree add ../my-app-billing feature/billing

# Open two terminal windows
cd ~/projects/my-app-auth && claude   # first Claude Code
cd ~/projects/my-app-billing && claude # second Claude Code

Cada copia está en su propia rama. Cada instancia de Claude Code escribe en su propio directorio. Cuando termine la tarea, ejecuta git push desde su rama y luego git worktree remove ../my-app-auth.

Lo que debes saber. Un worktree no duplica node_modules, .venv ni otros archivos incluidos en .gitignore. Si necesitas dependencias independientes (una versión distinta de una biblioteca en cada rama), ejecuta npm install por separado en el nuevo directorio después de worktree add.

Cuántos worktrees por persona. Según las encuestas a equipos de 2026, el límite práctico es de 4–8 worktrees paralelos por desarrollador. El factor limitante no es Claude, sino la capacidad de una persona para revisar y aceptar los resultados. Si tienes 10 worktrees, estarán esperando a que los revisen.

En la práctica descrita, la gente suele usar de 2 a 3 worktrees paralelos. Uno principal para el trabajo activo, uno de reserva para correcciones urgentes y uno para un experimento (una función nueva sobre la que tienes dudas). No hacen falta más.

Nivel 3: agent teams, varias ventanas y un agente líder#

Los agent teams son una primitiva relativamente nueva. La idea: un agente líder mantiene el plan compartido en forma de lista de tareas y varias sesiones pares, en ventanas independientes, se encargan de las tareas que el líder les asigna. Todos trabajan con el mismo sistema de archivos y pueden ver los artefactos intermedios de los demás.

Esto resulta útil cuando una tarea se divide en 3–5 flujos de trabajo grandes que duran horas (migrar un módulo grande, reescribir un subsistema o llevar a cabo una auditoría de seguridad completa). En ese caso, el agente líder conserva el plan en un único archivo de tareas compartido con ruta absoluta fuera de los worktrees. Los agentes lo leen e informan de resultados; solo el líder actualiza estados para evitar escrituras simultáneas.

Técnicamente, los agent teams son varias ventanas que trabajan sobre git worktree con un punto de planificación compartido. En la práctica, el 80 % de la gente gestiona los agent teams manualmente (como se ha descrito con worktree) y no usa ningún «framework de equipos» especial. No pasa nada.

Si no sabes si necesitas un framework, casi seguro que no lo necesitas. Usa worktrees manuales y un agente líder en el directorio principal.

Nivel 4: Dynamic Workflows, Claude escribe un script de orquestación en JS#

En los tres niveles anteriores, el plan se mantiene en una conversación: en la cabeza del agente principal o en la lista de tareas del agente líder. Dynamic Workflows traslada el plan al código. Claude expresa la tarea como un script de JavaScript; el runtime lo ejecuta en un entorno aislado, los resultados intermedios se guardan en variables del script en vez de en tu contexto y la sesión sigue respondiendo mientras los agentes trabajan en segundo plano.

Un ejemplo concreto de la documentación oficial. Dices:

ultracode: audit every API endpoint under src/routes/ for missing auth checks

Claude escribe un script de JavaScript con una lógica más o menos así: «toma todos los archivos de src/routes/, divídelos en grupos de 30 endpoints, ejecuta un agente en cada grupo con la misma comprobación, luego ejecuta dos agentes evaluadores independientes para revisar sus hallazgos y consolida un informe final». Se ejecuta y obtienes una tabla de resultados y una lista de endpoints que sin duda necesitan revisión.

Cuándo funciona.

• Auditar todo un proyecto para encontrar un mismo problema (seguridad, tipado, API obsoletas).
• Migraciones grandes (500+ archivos regidos por una misma regla).
• Preguntas de investigación que necesitan verificarse desde varios ángulos independientes (Anthropic hace esto con su comando integrado /deep-research).

Encontrarás un análisis detallado de Dynamic Workflows, sus límites y el funcionamiento de ultracode en la guía aparte sobre Dynamic Workflows en Claude Code.

Cuándo NO usarlo. Cuando la tarea es lineal y está clara. No necesitas un workflow para una tarea como «termina este componente». Un workflow tiene sentido cuando una tarea se divide en 10+ subtareas independientes que necesitan comprobarse entre sí.

Limitación principal. Un workflow consume bastantes más tokens que una sesión normal. Anthropic recomienda en su documentación:

En otras palabras, ejecuta tu primer workflow en un directorio, no en todo el proyecto. Comprueba cuánto cuesta y decide después si merece la pena ampliarlo.

Outcomes: una rúbrica de criterios y un revisor independiente#

Lo más peligroso del trabajo multiagente es confiar en los resultados de los agentes. Cada agente devuelve un texto que parece un trabajo terminado. Una cita parece cierta, un informe parece completo y una migración parece acabada. Con un agente, puedes comprobarlo tú mismo. Con 10, no puedes: no tendrás tiempo.

Anthropic aborda este problema con Outcomes, una función de Managed Agents publicada el 6 de mayo de 2026. La idea es sencilla: la sesión recibe un SEGUNDO agente (un evaluador) cuyo único trabajo es comprobar el trabajo del primer agente con una rúbrica estricta.

Así funciona técnicamente. Escribes una rúbrica, un documento Markdown con una lista detallada de lo que significa «terminado», qué fuentes hay que consultar y qué etiquetas hay que usar. La plataforma crea automáticamente un agente evaluador en una ventana de contexto nueva. Solo recibe la rúbrica y el resultado, nada más. Después de cada intento del agente principal (el redactor), el evaluador vuelve a leer el resultado y lo aprueba o devuelve una lista detallada de lo que sigue incompleto.

Una cita del Anthropic Cookbook:

Cifras de impacto real: después de integrar Outcomes en Claude Managed Agents, la tasa de finalización de tareas de la empresa de IA Harvey aumentó alrededor de 6×. En Wisedocs (documentación médica), el tiempo dedicado a revisar un documento se redujo un 50 %. Estas cifras proceden del anuncio oficial de la función.

Lo que importa para un vibe coder, en vez de para una empresa, es que Outcomes es un patrón, no solo una función específica. Puedes crear tu propio agente evaluador describiendo los mismos criterios en .claude/agents/grader.md y pidiéndole al agente principal que lo ejecute después de cada intento. Funciona con cualquier configuración multiagente, no solo con Managed Agents.

La regla principal del Cookbook para redactar rúbricas es especificar algo verificable, no algo general. No «comprueba que el brief cubra la facturación», sino «abre el brief, busca la sección sobre facturación y confirma que indica una cantidad en $ o un porcentaje de los ingresos». Con la primera instrucción, el evaluador puede echar un vistazo y marcar una casilla. La segunda le obliga a abrir el documento y encontrar una cifra concreta.

Antipatrón: «50 agentes haciendo disparates»#

Este es el antipatrón central del trabajo multiagente. Alguien se entera de que Claude Code puede ejecutar 16 agentes a la vez y Dynamic Workflows puede ejecutar 1000 por ejecución, así que se pone a iniciarlos. Resultado: cero. Consumo de tokens: 10× el de una sesión normal.

Una prueba sencilla. Coge una hoja de papel y dibuja un recuadro para cada uno de tus agentes. En cada recuadro, escribe:

1. Qué hace exactamente (una frase).
2. Qué archivos toca.
3. Qué devuelve.
4. Quién lo comprueba.

Si no puedes responder a una sola de estas preguntas en 30 segundos, no deberías tener ese agente. Esta regla se aplica a todos los niveles: subagentes, agent teams y Dynamic Workflows.

El segundo antipatrón es ejecutar en paralelo trabajos que deberían ser secuenciales. Si el frontend necesita primero el backend porque lee el esquema de la API, no los ejecutes en paralelo. Haz primero el backend y luego el frontend. Las tareas solo deben ejecutarse en paralelo si son independientes.

El tercer antipatrón es usar el modo multiagente para ganar velocidad. Solo funciona hasta cierto punto. Si divides una tarea en cuatro flujos de trabajo independientes, acabarán más o menos en el tiempo que habría tardado un solo flujo (más una coordinación mínima). Pero si hay 50 flujos en una máquina, cada uno irá más lento porque comparten la CPU. El límite práctico en un portátil es de 4–6 instancias de Claude Code simultáneas; a partir de ahí empieza la ralentización.

Cuánto cuesta y cómo evitar agotar tus límites#

En mayo y junio de 2026, el sector se enfrentó a la realidad de que programar con IA costaba más de lo esperado.

Una sesión normal de chat con Claude Code tiene un coste relativamente razonable. Activa Dynamic Workflows para todo un repositorio y recibirás una factura 20× más alta. La documentación oficial de Anthropic dice:

Qué hacer en la práctica. Estas son las reglas para ahorrar de la práctica descrita.

1. Especifica con precisión los archivos de cada agente. No «revisa el proyecto y encuentra problemas», sino «revisa src/auth/*.ts y comprueba que todas las funciones validen userId». El segundo prompt te dará exactamente el trabajo que estás pagando.

2. Prueba siempre un workflow primero en un solo directorio. No en todo src/. Empieza por src/auth/. Si te gustan los resultados y entiendes el coste, amplíalo después.

3. Usa /effort high de forma predeterminada y ultracode solo cuando lo decidas deliberadamente. /effort ultracode significa xhigh más orquestación automática. Es muy caro. Úsalo cuando una tarea realmente necesite varios flujos de trabajo paralelos.

4. Cambia los subagentes a un modelo más pequeño cuando puedas. Si seis subagentes revisan una guía, ni el agente QA que busca marcadores de IA ni el verificador de enlaces cruzados necesitan Opus. Sonnet bastará. Esto reduce el consumo entre 3 y 5 veces.

Encontrarás un análisis detallado sobre cómo ahorrar tokens en la guía sobre el consumo de tokens en Claude Code y en Cómo no agotar los límites de Claude Code.

Por dónde empezar hoy: una lista de comprobación de 30 minutos#

1. Actualiza Claude Code a v2.1.154+

   Es la versión mínima que admite Dynamic Workflows. Ejecuta claude update en el terminal.

2. Activa Dynamic Workflows en /config

   Están desactivados de forma predeterminada en el plan Pro. Abre /config, busca la línea «Dynamic workflows» y actívala. Ya están activados en Max, Team y Enterprise.

3. Crea tu primer worktree

   En el directorio principal del proyecto, ejecuta git worktree add ../<project>-experiment <branch>. Abre una segunda ventana de terminal en ese directorio. Ejecuta claude.

4. Añade una lista de tareas compartida

   Usa una única ruta absoluta fuera de todos los worktrees. Un tasks.md en cada worktree es un archivo distinto y no se sincroniza automáticamente. La sesión líder debe ser la única escritora; los agentes leen la lista y le comunican resultados.

   Crea una sola vez el directorio y la lista de coordinación:

       mkdir -p "$HOME/projects/my-app-coordination"
       printf '%s\n' '# Tasks' '- Auth: assigned to the auth worktree' '- Billing: assigned to the billing worktree' > "$HOME/projects/my-app-coordination/tasks.md"
   

   En la primera terminal:

       cd "$HOME/projects/my-app-auth"
       printf 'Shared task list: %s\n' "$HOME/projects/my-app-coordination/tasks.md"
       claude
   

   En la segunda terminal:

       cd "$HOME/projects/my-app-billing"
       printf 'Shared task list: %s\n' "$HOME/projects/my-app-coordination/tasks.md"
       claude
   

   En ambas sesiones, entrega al agente la misma ruta absoluta expandida impresa antes: «Lee esta lista compartida. Trabaja solo en tu tarea y archivos asignados. No edites la lista; informa de finalización y bloqueos al líder, responsable de actualizarla». Comprueba que los dos agentes puedan leer ese archivo exacto antes de empezar y resuelve cualquier petición de permiso para esa ruta. La lista coordina estados; el código sigue en worktrees separados.

5. Trabaja así durante una semana

   No instales un wrapper GUI de inmediato. Pasa una semana trabajando manualmente con dos worktrees. Verás qué falta y, entonces, podrás elegir una herramienta para resolver un problema concreto.

6. Solo entonces activa `/effort ultracode`

   Elige una tarea, como «encuentra todos los endpoints de API sin comprobaciones de auth en src/routes/». Activa /effort ultracode. Observa qué workflow escribe Claude, cuánto cuesta y qué resultado produce. Ese será tu primer Dynamic Workflow.

Qué viene después: memoria entre sesiones, Code Review y Multi-Agent v2#

Esto es lo que apareció en mayo y junio de 2026 y hacia dónde se dirige el modo multiagente en Claude Code.

Managed Agents con Dreaming. Se publicó el 6 de mayo de 2026 en Code with Claude. Un proceso programado lee las transcripciones anteriores de un agente entre sesiones, identifica patrones recurrentes y actualiza su memoria. La finalización de tareas de la empresa jurídica de IA Harvey aumentó seis veces específicamente después de Dreaming. Sigue en vista previa de investigación.

Outcomes como función de Managed Agents. Descrita más arriba. Está disponible a través de Claude Agent SDK, no directamente en la CLI de Claude Code. Ya puedes aplicar el mismo patrón manualmente con un subagente evaluador.

Multi-Agent Orchestration v2 en Claude Agent SDK. Un agente líder delega tareas a subagentes por iniciativa propia mediante un sistema de archivos compartido. Es el paso de «iniciar N subagentes manualmente» a «describir una tarea y dejar que el líder decida a quién delega y cómo». Si apenas estás aprendiendo a usar subagentes, todavía no tienes que preocuparte por la v2. Aprende el patrón clásico —«un agente principal + 3–5 subagentes con roles»— y pasa a la v2 de forma natural en 3–6 meses.

Code Review por un equipo de agentes. En Code with Claude, Anthropic anunció una función de revisión automática del código al abrir una PR. Un equipo de agentes de IA revisa el diff en paralelo, busca errores, verifica los hallazgos entre sí y los clasifica por gravedad. Está disponible en Team y Enterprise, pero aún no en Pro.

Plugin Marketplace. Se lanzó el 23 de mayo de 2026 en v2.1.128-136. Algunos plugins del marketplace son configuraciones multiagente listas para usar (parallel-review, security-audit, migration-helper). Puedes instalarlos con /plugin install <name>@claude-plugins-official y ver cómo están construidos, una buena forma de aprender a escribir los tuyos.

El modo multiagente de Claude Code sigue siendo un conjunto de primitivas con distintos niveles de madurez. Los subagentes y git worktree son estables, están probados y funcionan en todas partes. Los agent teams son mitad automáticos y mitad manuales. Dynamic Workflows está en vista previa de investigación y cambia rápidamente. Managed Agents v2 es solo para empresas. Esto significa que, durante el próximo año, la configuración óptima para un vibe coder no será la versión más reciente, sino la configuración mínima necesaria para una tarea concreta. Dos worktrees y un subagente evaluador bastan para un mes de trabajo activo. Añade complejidad solo cuando empieces a notar limitaciones.

Una configuración funcional para programar con vibe coding#

Materiales prácticos: documentación de Ailoot.

Más materiales y herramientas: Ailoot.