Cómo ejecuto múltiples agentes de Claude Code en paralelo

Cómo ejecuto múltiples agentes de Claude Code en paralelo

Tres agentes. Un repositorio. Cero conflictos.

Esa frase me habría parecido absurda hace seis meses. Llevaba un tiempo usando Claude Code en proyectos personales, y cada vez que quería lanzar un segundo agente para manejar una funcionalidad diferente, me estrellaba contra el mismo muro: conflictos de Git, directorios de trabajo sucios, agentes pisando los cambios del otro. La solución alternativa era dolorosa: stash, cambiar de rama, rezar para que nada se rompiera, repetir.

Entonces Anthropic lanzó soporte nativo de Git work trees para Claude Code. Y, sinceramente, cambió de forma fundamental cómo construyo software con agentes de IA.

No estoy exagerando. Esta única funcionalidad transformó mi flujo de trabajo de "un agente haciendo cosas secuencialmente" a "tres agentes trabajando en tres funcionalidades diferentes simultáneamente, cada uno en su propia sandbox aislada, fusionándose limpiamente cuando terminan." El salto en productividad fue inmediato y visceral — lo sentí desde el primer día.

Pero hay algo que nadie te dice sobre los work trees en Claude Code: el comportamiento por defecto tiene un detalle sutil que puede enviar tus commits directamente a main cuando crees que van a una rama de funcionalidad. Lo descubrí a la 1 AM un martes. Déjame ahorrarte ese mismo momento de pánico.

Por qué tu flujo de trabajo con un solo agente te está frenando

Aquí va un escenario que probablemente te suena familiar. Estás construyendo una funcionalidad — digamos, añadiendo autenticación a una API. Tienes a Claude Code trabajando en el middleware de autenticación. A mitad del proceso, te das cuenta de que también necesitas actualizar el esquema de la base de datos. Y ya que estás, hay un bug en el frontend que un usuario reportó esta mañana.

¿Qué haces? Esperas. Terminas primero el middleware de autenticación, lo commiteas, luego pasas al esquema, y después a la corrección del bug. Todo sucede en secuencia porque Git solo te permite tener una rama checked out a la vez en un único directorio de trabajo.

Pasé meses trabajando de esta manera. Se sentía normal porque es como cada desarrollador ha trabajado desde que se inventó Git. Un directorio, una rama, una cosa a la vez.

El coste de este enfoque secuencial es brutal cuando trabajas con agentes de IA. Claude Code puede generar e iterar sobre código dramáticamente más rápido de lo que yo puedo escribirlo — pero solo si se lo permito. Cuando estoy creando un cuello de botella en todo el pipeline al forzar todo a través de una sola rama, esencialmente estoy comprando un coche deportivo y conduciéndolo en primera marcha.

Los Git work trees resuelven esto a nivel de infraestructura. Y la integración nativa de Claude Code lo hace casi sin esfuerzo. Pero antes de mostrarte la configuración, necesitas entender qué son realmente los work trees — porque el modelo mental importa más que los comandos.

Git Work Trees — La funcionalidad que has estado ignorando

Llevaba más de una década usando Git antes de usar work trees en serio. Sinceramente, sabía que existían, pero se sentían como una de esas funcionalidades oscuras de Git que solo le importaban a los desarrolladores del kernel. Estaba equivocado.

Un Git work tree es un directorio de trabajo separado vinculado al mismo repositorio. Piénsalo así: tu repositorio normal es tu taller principal. Un work tree es un segundo taller al otro lado del pasillo que comparte la misma caja de herramientas (tu historial de Git, tus remotos, tu configuración) pero tiene su propio banco de trabajo donde puedes desplegar un proyecto completamente diferente.

Cada work tree tiene su propia rama checked out. Puedes tener main en tu directorio principal, feature/auth en un work tree, y fix/login-bug en otro — todos al mismo tiempo. Los cambios en uno no afectan a los demás. Los commits en uno no aparecen en los otros hasta que los fusionas.

La idea clave que me hizo clic: los work trees no son copias de tu repositorio. Son vistas adicionales del mismo repositorio. Tu directorio .git permanece en un solo lugar. Los work trees simplemente lo referencian. Eso significa que son ligeros de crear y destruir.

Aquí está el comando Git directo:

git worktree add ../my-feature-branch feature/my-feature

Esto crea un nuevo directorio ../my-feature-branch con la rama feature/my-feature checked out. Puedes hacer cd hacia él, hacer cambios, commitear, hacer push — todo independientemente de tu directorio de trabajo principal.

Y cuando terminas:

git worktree remove ../my-feature-branch

Limpio. Sin archivos residuales. Sin ramas huérfanas a menos que las quieras.

Esa es la base. Ahora veamos cómo Claude Code toma este concepto y lo convierte en algo genuinamente poderoso.

La integración de Work Trees en Claude Code — Qué hace realmente

Cuando Anthropic añadió soporte nativo de work trees a Claude Code, no se limitaron a envolver los comandos Git. Construyeron un sistema de gestión del ciclo de vida alrededor de ello. Y la diferencia importa.

Esto es lo que sucede cuando le dices a Claude Code que use un work tree. Puedes activarlo a través del CLI o configurando un agente para que use modo de aislamiento. El comando se ve así:

claude --worktree

O dentro de una sesión, puedes entrar a un work tree con el comando /worktree. Claude Code hace varias cosas automáticamente:

1. Crea un nuevo directorio bajo .claude/worktrees/ en la raíz de tu proyecto
2. Genera un nombre de rama — a menudo algo ingenioso y auto-generado (he visto nombres como claude/witty-fox y claude/brave-eagle)
3. Hace checkout de esa rama basándose en tu HEAD actual
4. Cambia todo el contexto de trabajo del agente a ese work tree

A partir de ese momento, todo lo que el agente hace — lecturas de archivos, escrituras, operaciones Git — ocurre dentro del work tree. Tu directorio de trabajo principal permanece intacto.

Aquí es donde se pone interesante para flujos de trabajo multi-agente. Cada agente o sub-agente puede obtener su propio work tree. El Agente A está implementando un nuevo endpoint de API en claude/worktrees/endpoint-feature. El Agente B está escribiendo tests en claude/worktrees/test-suite. El Agente C está arreglando un bug de CSS en claude/worktrees/ui-fixes. Los tres están ejecutándose simultáneamente, los tres están aislados, y ninguno puede pisar el trabajo del otro.

Cuando cada agente termina, tienes ramas limpias listas para pull requests.

Quiero ser específico sobre la experiencia en VS Code aquí porque está genuinamente bien hecha. Cuando tienes múltiples work trees activos, el panel de Source Control de VS Code muestra cada uno como un repositorio separado. Puedes ver el diff, los cambios en staging y el estado de la rama para cada work tree de forma independiente. Es como tener múltiples repos abiertos, excepto que todos comparten el mismo historial de Git.

Dicho esto, hay una sutileza sobre la que necesito advertirte — y es la trampa que mencioné al principio.

La trampa del push de ramas que casi me cuesta un día de trabajo

Esto es lo que pasó. Creé un work tree a través de Claude Code, hice un montón de cambios, los commiteé y los pusheé. Todo parecía bien. El push fue exitoso. Seguí con la siguiente tarea.

Treinta minutos después, revisé GitHub y encontré mis commits del work tree en main.

No en una rama de funcionalidad. En main. En producción.

El problema es sutil. Cuando Claude Code crea un work tree, crea una nueva rama local basada en HEAD. Pero cuando haces push, el comportamiento por defecto de Git depende de tu configuración de push.default. Si está configurado como simple o current (que son valores por defecto comunes), y tu nueva rama aún no tiene una rama de seguimiento upstream, Git podría hacer push a main — la rama en la que se basó tu HEAD.

La solución es directa, pero tienes que conocerla:

git push -u origin claude/your-branch-name

Esa flag -u establece la rama de seguimiento upstream. Después de ese primer push con -u, los comandos git push subsiguientes irán al lugar correcto.

Consejo profesional: también puedes configurar esto globalmente para que Git siempre haga push a una rama con el mismo nombre:

git config --global push.autoSetupRemote true

Con esa configuración, cada nueva rama automáticamente rastrea una rama remota con el mismo nombre. No más pushes accidentales a main.

Claude Code ha comenzado a añadir salvaguardas alrededor de esto — prompts y hooks que te advierten cuando estás a punto de hacer push a una rama que podría no ser la que pretendías. Pero aun así recomendaría la configuración global como red de seguridad.

Aprendí esto por las malas para que tú no tengas que hacerlo. Si te llevas una sola cosa de todo este artículo, que sea esta: siempre configura tu upstream antes de hacer push desde un work tree.

Ahora que hemos cubierto la trampa, déjame guiarte paso a paso por el flujo de trabajo completo que uso a diario.

Mi flujo de trabajo completo con agentes en paralelo — Paso a paso

Este es el flujo de trabajo en el que me he estabilizado después de semanas de iteración. No es la única forma de usar work trees con Claude Code, pero es la que me ha resultado más fiable.

Paso 1: Planificar el trabajo en paralelo

Antes de lanzar múltiples agentes, dedico cinco minutos a identificar tareas independientes. La palabra clave es independientes. Si la Tarea B depende del resultado de la Tarea A, no pueden ejecutarse verdaderamente en paralelo — te encontrarás con conflictos de merge o problemas de dependencias.

Buenos candidatos para paralelización:

• Trabajo de funcionalidades + corrección de bugs (diferentes áreas del código)
• Cambios en backend + cambios en frontend
• Implementación + escritura de tests
• Actualización de documentación + refactorización de código

Malos candidatos:

• Dos funcionalidades que modifican los mismos archivos
• Una migración de base de datos y código que depende del nuevo esquema
• Cualquier cosa donde la salida de una tarea sea la entrada de otra

Paso 2: Crear work trees para cada agente

Normalmente comienzo desde mi rama main con un directorio de trabajo limpio:

# Verificar estado limpio
git status

# Crear work trees para cada tarea
git worktree add .claude/worktrees/feature-auth -b feature/auth
git worktree add .claude/worktrees/fix-login -b fix/login-bug
git worktree add .claude/worktrees/update-tests -b update/test-coverage

Alternativamente, dejo que Claude Code los cree. Cuando se usa la herramienta Task con isolation: "worktree", cada sub-agente obtiene automáticamente su propio work tree:

Use the Task tool with isolation: "worktree" to assign independent work to sub-agents

Cada sub-agente recibe una copia fresca del repositorio con su propia rama, hace su trabajo y devuelve los resultados. El work tree se limpia automáticamente si no se hicieron cambios, o se preserva con el nombre de la rama si existen cambios.

Paso 3: Ejecutar agentes en paralelo

Aquí es donde ocurre la magia. Lanzo múltiples sesiones de Claude Code o sub-agentes, cada uno apuntando a un work tree diferente.

En la práctica, he descubierto que tres agentes en paralelo es el punto óptimo para mis proyectos. Más que eso y empiezo a perder la capacidad de revisar efectivamente la calidad del resultado. Tu experiencia puede variar dependiendo de la complejidad de cada tarea.

Cada agente trabaja de forma completamente independiente. Pueden leer archivos, escribir archivos, ejecutar tests, hacer commits — todo sin saber que los otros agentes existen.

Paso 4: Revisar y hacer push de cada rama

Una vez que los agentes terminan, reviso los cambios de cada work tree:

# Revisar qué pasó en cada work tree
cd .claude/worktrees/feature-auth
git log --oneline -5
git diff HEAD~1

# Configurar upstream y hacer push
git push -u origin feature/auth

Repito esto para cada work tree. El paso de revisión es crítico — no confío ciegamente en la salida de los agentes, especialmente cuando ejecuto múltiples agentes. Un vistazo rápido al diff detecta la mayoría de los problemas.

Paso 5: Crear Pull Requests

Desde cada work tree (o desde el GitHub CLI en cualquier lugar):

gh pr create --title "Add authentication middleware" --body "Implemented JWT auth..."

Ahora tengo tres PRs separados, cada uno con cambios enfocados, diffs limpios y sin contaminación cruzada.

Paso 6: Fusionar y limpiar

Después de que los PRs se revisan y fusionan:

# De vuelta en el directorio principal
git checkout main
git pull

# Eliminar work trees
git worktree remove .claude/worktrees/feature-auth
git worktree remove .claude/worktrees/fix-login
git worktree remove .claude/worktrees/update-tests

Borrón y cuenta nueva. Listo para el siguiente lote.

Si has seguido hasta este punto, ya tienes un flujo de trabajo de desarrollo en paralelo funcional con Claude Code. La mayoría de los tutoriales se detienen aquí. Pero el verdadero poder aparece cuando empiezas a combinar work trees con sub-agentes y orquestación jerárquica de tareas.

Sub-agentes con Work Trees — Paralelización jerárquica

Esta es la parte que genuinamente me emocionó cuando la descubrí por primera vez.

Claude Code soporta sub-agentes — agentes más pequeños y enfocados que un agente principal puede lanzar para manejar tareas específicas. Cuando combinas sub-agentes con aislamiento de work trees, obtienes algo notable: un agente principal que actúa como director de proyecto, delegando tareas independientes a sub-agentes, cada uno trabajando en su propio entorno aislado.

Aquí está el modelo mental. Tu agente principal lee la lista de tareas, identifica tres piezas independientes de trabajo y genera tres sub-agentes con isolation: "worktree". Cada sub-agente:

1. Obtiene su propio work tree (creado automáticamente)
2. Trabaja en su tarea asignada
3. Commitea sus cambios
4. Reporta de vuelta al agente principal
5. Su work tree se preserva con el nombre de la rama

El agente principal luego revisa los resultados, decide si algo necesita revisión y puede incluso crear PRs programáticamente.

Usé este patrón la semana pasada para refactorizar una API. El agente principal analizó el código, identificó cuatro módulos independientes que necesitaban actualización y generó cuatro sub-agentes. Cada sub-agente refactorizó su módulo, escribió tests y commiteó los cambios. Toda la refactorización que me habría tomado un día completo se completó en unos 40 minutos.

El detalle crucial: las tareas deben ser verdaderamente independientes. Las modificaciones de archivos superpuestas entre sub-agentes crearán conflictos de merge cuando intentes integrar todo. Planifica tu descomposición de tareas cuidadosamente.

Hay un patrón más que quiero compartir — usar work trees para experimentación.

Work Trees como sandboxes desechables

No todo work tree necesita convertirse en un PR. Algunos de mis usos más productivos de work trees son puramente experimentales.

Lanzo un work tree, le pido a Claude Code que pruebe un enfoque completamente diferente para un problema y evalúo el resultado. Si funciona — genial, tengo una rama lista. Si no — elimino el work tree y sigo adelante. Riesgo cero para mi código principal.

Este patrón de "sandbox desechable" ha cambiado cómo tomo decisiones arquitectónicas. En lugar de agonizar sobre si el enfoque A o el enfoque B es mejor, implemento ambos en work trees separados y los comparo directamente. Código real, tests reales, datos reales — no debates teóricos en una pizarra.

El mes pasado, estaba decidiendo entre dos enfoques de gestión de estado para un proyecto de React. Creé dos work trees, implementé cada enfoque, ejecuté la misma suite de tests contra ambos y comparé tamaños de bundle y métricas de rendimiento. La decisión que habría tomado un día de deliberación tomó una hora de experimentación en paralelo.

Ese es el cambio de mentalidad que permiten los work trees. El código se vuelve barato de probar. Los experimentos se vuelven de bajo coste. Y las malas ideas se eliminan con evidencia, no con opiniones.

Las compensaciones honestas que nadie menciona

Te haría un mal servicio si pintara los work trees como algo puramente mágico. Hay limitaciones reales y asperezas.

El espacio en disco se acumula. Cada work tree es un checkout completo de los archivos de tu proyecto (aunque no un clon completo — comparte el directorio .git). Para monorepos grandes, tres o cuatro work trees pueden consumir espacio en disco significativo. He aprendido a limpiar agresivamente después de fusionar.

La carga mental aumenta. Hacer seguimiento de lo que está pasando en tres agentes paralelos requiere disciplina. Mantengo un archivo de texto simple anotando qué work tree está haciendo qué, o me apoyo en la gestión de tareas de Claude Code para rastrear el progreso. Sin esto, he perdido la pista de qué rama tiene qué cambios.

No todo se paraleliza bien. Lo mencioné antes, pero vale la pena repetirlo. Si tus tareas tienen dependencias — si la Tarea B necesita la salida de la Tarea A — no puedes simplemente lanzarlas a work trees separados y esperar lo mejor. Terminarás con conflictos de merge o código roto.

Los work trees no son automáticos. Tienes que optar explícitamente por usarlos. Claude Code no creará work trees por su cuenta a menos que lo configures para hacerlo. Esto es en realidad una buena decisión de diseño — la paralelización implícita podría causar caos — pero significa que necesitas pensar cuándo usarlos.

Los nombres de rama pueden ser confusos. Los nombres de rama auto-generados de Claude Code son creativos (he visto cosas como claude/dazzling-penguin) pero no siempre descriptivos. He empezado a proporcionar nombres de rama explícitos en lugar de confiar en los auto-generados. Tu yo del futuro agradecerá a tu yo del presente cuando lea git log.

Estas no son razones para descartarlo. Son simplemente cosas que deberías saber antes de lanzarte de lleno con los work trees en paralelo. Las ganancias de productividad superan con creces estos puntos de fricción — pero solo si los gestionas intencionalmente.

Lo que he medido después de un mes de work trees en paralelo

Hice seguimiento de mi producción durante un mes para ver si los work trees realmente cumplían la promesa. Aquí están los números en bruto.

Antes de los work trees (flujo de trabajo secuencial):

• Funcionalidades completadas por día en promedio: 1-2
• Tiempo promedio desde inicio de tarea hasta PR: 3-4 horas
• Cambios de contexto que rompían mi flujo: 5-6 por día
• Enfoques experimentales abandonados: 1 por semana (demasiado caro intentarlo)

Después de los work trees (flujo de trabajo en paralelo):

• Funcionalidades completadas por día en promedio: 3-4
• Tiempo promedio desde inicio de tarea hasta PR: 1.5-2 horas
• Cambios de contexto que rompían mi flujo: 1-2 por día
• Enfoques experimentales probados: 3-4 por semana (barato de explorar)

La mayor ganancia no fue la velocidad en bruto — fue la reducción en cambios de contexto. Cuando cada agente tiene su propio work tree, no necesito rastrear mentalmente "¿en qué estado está mi directorio de trabajo?" Esa pregunta simplemente desaparece.

El conteo de enfoques experimentales fue la métrica sorpresa. Porque probar cosas se volvió barato, empecé a probar más cosas. Y algunos de esos experimentos llevaron a soluciones significativamente mejores de lo que mi primer instinto habría producido.

Ganancias rápidas que noté en la primera semana: correcciones de bugs más rápidas (lanzar un work tree, arreglar, push, PR — hecho en minutos), diffs de PR más limpios (cada PR solo contiene cambios para una tarea), y menos momentos de "ups, commiteé eso en la rama equivocada".

A largo plazo, espero que el efecto compuesto sea sustancial. Mejor calidad de código gracias a más experimentación, entregas más rápidas gracias a la paralelización, y un historial de Git más limpio gracias a ramas aisladas.

El futuro del desarrollo en paralelo asistido por IA

Estoy genuinamente convencido de que la paralelización basada en work trees se va a convertir en un flujo de trabajo fundamental para la programación asistida por IA. No solo para Claude Code — para cualquier herramienta de programación con IA.

El patrón es natural. Los agentes de IA funcionan mejor cuando se les dan tareas enfocadas y bien delimitadas. Los work trees proporcionan el aislamiento que esos agentes necesitan. La combinación es casi obvia en retrospectiva.

Lo que estoy esperando que venga a continuación: integración más estrecha con el IDE (imagina VS Code mostrando el progreso en tiempo real de cada agente de work tree en un panel), descomposición de tareas más inteligente (el agente principal identificando automáticamente qué tareas pueden ejecutarse en paralelo), y detección automática de conflictos (advirtiéndote antes de que dos agentes comiencen a modificar los mismos archivos).

Algo de esto ya existe en forma básica. Algo está por llegar. Todo se siente inevitable.

Aquí va mi desafío para ti: la próxima vez que te sientes a trabajar en un proyecto con Claude Code, identifica dos tareas que sean completamente independientes entre sí. Crea dos work trees. Ejecuta ambas simultáneamente. Cronometra el resultado.

Esa primera experiencia — ver dos funcionalidades materializarse en paralelo mientras tomas tu café — es el momento en que el flujo de trabajo hace clic. Y una vez que hace clic, no volverás atrás.

Trabajemos juntos

¿Buscas construir sistemas de IA, automatizar flujos de trabajo o escalar tu infraestructura tecnológica? Me encantaría ayudarte.

• Fiverr (builds personalizados e integraciones): fiverr.com/s/EgxYmWD
• Portfolio: mejba.me
• Ramlit Limited (soluciones empresariales): ramlit.com
• ColorPark (diseño y branding): colorpark.io
• xCyberSecurity (servicios de seguridad): xcybersecurity.io