Git worktree para agentes de IA: la guía que incluye lo que se rompe

Respuesta corta: git worktree add -b nombre ../carpeta crea una copia del proyecto en otra carpeta, ligada al mismo repositorio, en una rama separada. Así trabaja cada agente de IA sin sobrescribir a los demás. Lo que las guías omiten es que la copia nace sin node_modules, sin .env y sin build, y ahí es donde se atascan casi todos los intentos.

El comando, y qué hace

git worktree add -b agente/tarea ../proyecto-tarea\ncd ../proyecto-tarea

Eso crea una carpeta nueva con todos los archivos versionados, en una rama nueva, compartiendo el mismo historial. No es un clon: el repositorio es el mismo, así que los commits se ven para todos y no hay subida ni descarga. Al terminar, git worktree remove ../proyecto-tarea.

Qué NO viene con ella (la parte que atasca)

Solo se copia lo versionado. Todo lo que .gitignore excluye se queda atrás, y es justo lo que el proyecto necesita para funcionar:

• Dependencias (node_modules, vendor): hay que instalarlas en la worktree. Un atajo habitual es un enlace simbólico a la carpeta principal, y para node_modules suele funcionar. Para dependencias de lenguajes que resuelven rutas de archivo, como el autoloader de PHP, el enlace puede hacer que el agente de IA cargue código de la OTRA rama sin avisar, y acabas depurando un comportamiento que no está en el código que lees.
• Variables de entorno (.env): el enlace simbólico va bien aquí, porque es un archivo de texto que se lee una vez.
• Build del front: si tu framework busca un manifiesto generado, no existe en la worktree nueva y la página se rompe con un error que jamás menciona worktrees.

La base de datos es compartida, y eso es una trampa

La worktree no aísla la base de datos. Si un agente de IA ejecuta una migración destructiva, afecta la base de todos los demás y la tuya. Conviene decirlo explícitamente en las instrucciones del proyecto, y que las pruebas usen una base en memoria en vez de la de desarrollo.

Cuándo NO vale la pena

Con un agente de IA por vez, no vale: pagas el coste de preparar el entorno y no ganas aislamiento, porque no hay con quién chocar. Tampoco vale para trabajo de lectura, como investigar o explicar código, que no escribe nada. El aislamiento existe para escritura concurrente, y se paga a partir de tres o cuatro frentes simultáneos.

¿Worktree o contenedor?

La worktree es más ligera y rápida: archivos en el mismo disco, y el agente sigue viendo las herramientas de tu máquina. El contenedor aísla más a fondo, incluidos proceso y red, y es lo que quieres si vas a dejar un agente sin supervisión. Para trabajo supervisado en tu propio Mac, la worktree basta.

Cómo saber quién está en qué worktree

git worktree list las muestra todas, con la rama de cada una. Es el comando que responde "quién está tocando qué" cuando tienes cinco agentes de IA abiertos y perdiste la cuenta.

¿Y cuando dos worktrees tocan el mismo archivo?

Va a pasar, y lo correcto es que aparezca pronto. Con aislamiento, cada uno trabaja en su copia y la colisión surge al integrar, con Git mostrando las dos versiones lado a lado. Lo que no quieres es enterarte por una prueba que empezó a fallar sin motivo aparente.