Uso de Git Worktrees con agentes de codificación de IA

La manera confiable de ejecutar múltiples agentes de codificación de IA sobre un mismo repositorio es: una tarea, una rama, un worktree, un agente. Cada agente obtiene su propio directorio creado con git worktree add, trabaja en su propia rama y nunca toca los archivos que otro agente está editando.

La mayoría de los desarrolladores llega a este patrón por las malas. Dos agentes en un mismo checkout se sobrescriben en silencio las ediciones a medio terminar, o uno de ellos se atasca al intentar hacer checkout de una rama que ya está en uso en otro lugar. Este artículo trata específicamente del flujo de trabajo con agentes: qué aísla el patrón, qué deliberadamente no aísla y qué hacer cuando tres agentes terminan al mismo tiempo.

El patrón de Git Worktree para agentes de IA

El patrón de un agente por worktree requiere dos comandos por tarea. Crea un worktree con una rama nueva basada en main y luego arranca un agente dentro de él:

git worktree add ../task-a -b agent/task-a main
git worktree add ../task-b -b agent/task-b main

Apunta un agente a ../task-a y otro a ../task-b. Cada uno tiene su propio directorio de trabajo, su propio índice y su propio HEAD, mientras que todos los worktrees comparten la misma base de datos de objetos y las mismas refs, de modo que los commits hechos en uno son visibles de inmediato desde los demás. Vincula el worktree a la tarea, no al agente: créalo cuando comience el trabajo y elimínalo cuando la rama se fusione. Anthropic documenta esta misma secuencia manual en la guía de worktrees de Claude Code, y Cursor ejecuta agentes en worktrees aislados desde su ventana de Agentes; Codex funciona igual cuando se lo apunta a un directorio.

¿Por qué falla un único directorio compartido?

Dos agentes en un mismo directorio fallan en silencio: ni git ni los agentes lanzan un error cuando uno sobrescribe las ediciones sin commitear del otro, así que el daño solo aparece a la hora de revisar. La detección de conflictos de git compara commits; las escrituras concurrentes sobre el mismo árbol de trabajo nunca llegan a ese punto.

El segundo fallo es más ruidoso, pero peor. Las operaciones de git concurrentes en un directorio compartido chocan con .git/index.lock, y si un agente se cae mientras mantiene el lock, el archivo obsoleto bloquea los comandos git de todos los demás agentes hasta que alguien lo borra a mano. Algunos agentes reintentan; otros desisten de hacer commit y siguen generando código sobre un estado sin commitear que no deja de crecer. Los worktrees separados disuelven ambos problemas, porque cada worktree hace staging contra su propio índice en lugar de uno compartido.

Qué no contiene un worktree nuevo

Un worktree nuevo contiene únicamente archivos versionados, así que node_modules, .env, las cachés de compilación y cualquier otra cosa en el gitignore no existen hasta que las crees. Un agente arrancado en un worktree sin preparar fallará en su primera ejecución de tests o, peor aún, reescribirá “servicialmente” la configuración para compensar. Prepara cada worktree antes de que arranque el agente:

cd ../task-a
npm ci
cp ../main-repo/.env .env

npm ci es la instalación adecuada aquí: está pensada para entornos limpios e instala exactamente lo que especifica el lockfile. Si tu agente es Claude Code, un archivo .worktreeinclude puede llevar archivos ignorados por git como .env a los worktrees que Claude Code crea por sí mismo, pero no se aplica a los worktrees que creas a mano con git worktree add, así que la copia manual funciona con cualquier herramienta.

Qué no aíslan los worktrees

Los worktrees aíslan archivos, no el entorno de ejecución: los puertos, las bases de datos, los volúmenes de Docker y las cachés compartidas pertenecen a la máquina, así que dos servidores de desarrollo arrancados desde dos worktrees seguirán peleándose por el puerto 3000. El límite del directorio no significa nada para cualquier cosa direccionada por hostname o puerto.

Dale a cada worktree su propio puerto y su propia base de datos antes de arrancar un agente que ejecute migraciones, porque un cambio de esquema hecho desde un worktree aterriza en cualquier base de datos que compartan los demás. Configura ambos en el .env copiado:

# ../task-a/.env
PORT=3001
DATABASE_URL=postgres://localhost:5432/app_agent_task_a

Nombrar la base de datos según la rama facilita detectar las obsoletas y eliminarlas más adelante. Los contenedores también pueden aislar la capa de ejecución, pero eso implica un conjunto de compensaciones que dan para otro artículo.

¿Cómo le indicas al agente que está en un worktree?

Una rama solo puede estar en checkout en un worktree a la vez, así que un agente que intente sincronizarse ejecutando git checkout main recibirá un error y a menudo se quedará bloqueado. El manual de git checkout describe este comportamiento y señala --ignore-other-worktrees como la forma de anularlo. No dejes que el agente lo descubra en tiempo de ejecución; ponlo en el archivo de instrucciones que el agente lee (AGENTS.md, CLAUDE.md o equivalente):

You are working inside a git worktree.
Stay on the current branch. Never run `git checkout` or `git switch`.
To sync with main, run `git fetch origin` and `git rebase origin/main`.

Cuando un agente solo necesita leer o compilar un commit concreto, prescinde por completo de las ramas: git worktree add --detach crea un worktree con un HEAD desacoplado, lo que evita del todo la regla de exclusividad.

git worktree add --detach ../review-b1a2c3 b1a2c3

¿Cómo se fusiona lo que regresa?

Los worktrees no eliminan los conflictos de fusión; los desplazan desde sobrescrituras silenciosas en tiempo de ejecución hacia conflictos visibles en el momento del merge, donde las herramientas habituales de git los gestionan. Cuando varios agentes terminan a la vez, integra de forma secuencial: fusiona una rama, haz rebase de la siguiente sobre la main actualizada, fusiónala y repite.

cd ../main-repo
git merge agent/task-a

cd ../task-b
git rebase main
cd ../main-repo
git merge agent/task-b

Cada rebase saca a la luz los conflictos contra todo lo ya fusionado, rama por rama, en lugar de acumular sorpresas a tres bandas. La regla de ordenación está aguas arriba del merge: las tareas que tocan los mismos archivos, o en las que una consume la salida de la otra, se secuencian en vez de paralelizarse. Ninguna disposición de worktrees arregla una descomposición de tareas que nunca fue independiente.

Cuántos agentes y cuándo limpiar

El techo práctico no lo marcan git ni el disco; lo marca tu capacidad de revisión, ya que cada agente en paralelo produce una rama que debes leer, probar y fusionar. Los equipos que publican sobre este flujo de trabajo, como el equipo de ingeniería de incident.io, describen ejecutar cuatro o cinco agentes a la vez, y la mayoría de los desarrolladores considera que con menos es suficiente. Cuando una rama se fusiona, ejecuta git worktree remove ../task-a; como la preparación añadió archivos no versionados, es previsible que necesites --force, que git worktree remove exige para worktrees que no están limpios. Si en cambio se eliminó un directorio con rm -rf, git worktree prune limpia los metadatos obsoletos que git aún conserva.

Empezar con dos agentes

Una tarea, una rama, un worktree, un agente: eso convierte a los agentes en paralelo, de una fuente de corrupción silenciosa, en un conjunto de ramas revisables. Empieza con dos: crea los worktrees, prepara cada uno con npm ci y un .env por tarea, añade la instrucción de permanecer en la rama y practica la secuencia de rebase y luego merge antes de escalar más allá de lo que realmente puedes revisar.

Preguntas frecuentes

¿Debería usar git worktrees o clones separados para ejecutar agentes de IA en paralelo?

Normalmente los worktrees son mejores porque comparten una única base de datos de objetos, de modo que un commit hecho en un worktree es visible de inmediato desde los demás sin necesidad de push ni fetch, y el historial se almacena una sola vez en disco. Los clones separados duplican todo el historial y necesitan push y fetch para intercambiar commits. Los clones solo ganan cuando necesitas un aislamiento completo, como en repositorios con submódulos.

¿Funcionan los git worktrees con repositorios que usan submódulos?

Solo en parte. El propio manual de worktree de Git incluye el soporte de submódulos en la sección BUGS, califica el checkout múltiple como experimental y desaconseja hacer checkout de un superproyecto en más de un sitio a la vez. Además, un worktree que contiene submódulos no puede reubicarse con git worktree move. Para ejecutar agentes en paralelo sobre un repositorio con submódulos, los clones completos separados son el mecanismo de aislamiento más seguro, aunque dupliquen el historial y requieran hacer push para compartir commits entre checkouts.

¿Comparten todos los git worktrees la misma configuración de git?

Sí. Todos los worktrees leen la misma configuración del repositorio salvo que decidas lo contrario. Para darle a un worktree sus propios ajustes, ejecuta git config extensions.worktreeConfig true y luego escribe los valores con git config --worktree, que los guarda en el archivo config.worktree propio de ese worktree. La contrapartida: las versiones antiguas de Git no podrán abrir el repositorio una vez activada la extensión.

¿Eliminar un worktree borra la rama del agente?

No. Las ramas son refs compartidas por todo el repositorio, así que git worktree remove elimina el directorio de trabajo y sus metadatos, pero deja intactas la rama y todos sus commits. Solo se pierden los cambios sin commitear de ese directorio, y por eso remove rechaza los worktrees que no están limpios a menos que pases --force. Borra la rama por separado con git branch -d una vez fusionada.