Khavel

Posted on Aug 27 Originally published at devaisemanal.com

Git worktree para agentes de IA: trabajo paralelo sin pisar tu repositorio

#spanish #ai #espanol #automation

git worktree permite tener varios directorios de trabajo conectados al mismo repositorio, cada uno con su HEAD e índice. La keyword principal es git worktree agentes IA; la intención es práctica: un developer quiere ejecutar tareas de agentes en paralelo sin que compartan el árbol de archivos que están editando.

TL;DR

Un worktree es aislamiento de checkout, no aislamiento de ejecución. Evita que un agente borre el build de otro o cambie su lockfile a mitad de una prueba; no separa credenciales, procesos que escuchan en el mismo puerto, recursos cloud, cachés globales ni la decisión de mergear.

Mi postura: asigna un worktree por cambio pequeño y verificable, no uno por cada pensamiento del modelo. Paraleliza investigación, documentación, tests o módulos con fronteras claras; integra de uno en uno con CI y revisión humana. Si dos tareas necesitan tocar la misma abstracción, el cuello de botella no es Git: es una decisión de diseño que nadie ha tomado todavía.

Qué aísla realmente un Git worktree

Un repositorio puede tener un worktree principal y varios worktrees enlazados. Git comparte el almacén de objetos y la mayoría de las refs, pero cada checkout enlazado tiene su propio HEAD, índice y directorio de trabajo. Por eso dos agentes pueden partir del mismo commit y modificar archivos distintos sin sobrescribir el disco del otro.

Git protege una frontera importante: normalmente rechaza que la misma rama esté checkout en dos worktrees. No fuerces ese bloqueo con --force para 'hacerlo funcionar'. Si dos agentes trabajan sobre la misma rama, has recuperado el problema original con una topología más difícil de depurar.

La frase útil para documentar en tu repositorio es: un worktree representa una tarea y una rama; un agente representa un ejecutor temporal de esa tarea. La rama sobrevive a la conversación, el worktree puede desecharse después de que el cambio esté validado y fusionado.

Los worktrees separan archivos, índice y rama de cada tarea; la integración vuelve a ser una cola única con pruebas y revisión.

La unidad correcta de paralelismo

No distribuyas una petición como 'mejora la autenticación' entre cuatro agentes. Divide por contrato comprobable: uno añade una validación de entrada, otro actualiza documentación y ejemplos, otro escribe tests de regresión. Cada tarea debe tener rutas permitidas, una salida observable y un comando de validación que no dependa de adivinar la intención del otro agente.

Evita el paralelismo si varias tareas tocan la misma migración, interfaz pública, lockfile o selector central. También evítalo si todas requieren el mismo entorno mutable: un emulador con un puerto fijo, una base de datos de desarrollo compartida o una cuenta de pruebas que no resetea el estado. Un worktree no convierte esos recursos en seguros para concurrencia.

Empieza por dos worktrees. Si la integración termina generando conflictos repetidos, baja el paralelismo y mejora la división de tareas. Más agentes no arreglan límites de módulo mal definidos; solo generan más diffs que una persona tendrá que entender.

Crear un worktree por rama de agente

Parte de una referencia explícita y actualizada. Nombrar rama y directorio hace que la intención sea auditable y reduce el riesgo de que un agente trabaje contra un HEAD local olvidado. La opción -b falla si la rama ya existe, que es una protección útil para una automatización que se reintenta.

terminal
git fetch origin
git worktree add -b agent/authz-input ../miapp-agent-authz origin/main
git worktree add -b agent/docs-authz ../miapp-agent-docs origin/main
git worktree list --porcelain

No uses el nombre del modelo como rama (claude-fix, codex-fix). Usa el resultado técnico (agent/authz-input) y guarda en la tarea quién la ejecutó, el prompt o issue, el commit base y el comando de verificación. Así puedes cambiar de herramienta sin perder trazabilidad ni convertir el historial Git en marketing involuntario.

Contexto y configuración: lo que viaja y lo que no

¿Te está sirviendo? Hay una dosis cada semana

Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Los archivos versionados viajan con la rama: AGENTS.md, README, scripts de bootstrap, linters y fixtures deberían estar ahí. Codex compone sus instrucciones desde el root del proyecto hasta el directorio actual; por tanto, un AGENTS.md comprometido es una forma reproducible de dar a cada worktree los mismos límites, comandos y rutas sensibles.

Lo que conviene comprobar

Los archivos no versionados no aparecen por magia. .env, claves SSH, credenciales de cloud, bases SQLite locales y caches deben ser creados por un bootstrap explícito de desarrollo, preferiblemente con datos de prueba y privilegios mínimos. Copiar el .env de producción a cada worktree es una comodidad que transforma una mejora de productividad en una multiplicación de secretos.

La configuración de Git es compartida por defecto. Si un worktree necesita sparse-checkout, hooks o una opción local distinta, activa extensions.worktreeConfig y escribe con git config --worktree. No pongas una configuración de una tarea en el config común: terminará sorprendiendo al siguiente agente que use el repositorio.

Recorta el checkout sin contaminar a los demás

En monorepos grandes, un agente que cambia un paquete no necesita indexar todo el producto. git sparse-checkout set configura la selección para el worktree actual y Git actualiza a configuración específica cuando hace falta. Es una optimización de I/O y de contexto, no una frontera de seguridad: el agente puede seguir acceder a otras rutas si le das permisos de sistema amplios.

desde el worktree del agente
git sparse-checkout set --cone apps/api packages/auth
git sparse-checkout list
git config --show-origin --get core.sparseCheckout
Prueba primero con un worktree desechable. Algunas herramientas de generación, IDEs y scripts de release esperan rutas que un checkout disperso no contiene. Si la tarea necesita ejecutar integración end-to-end del monorepo, un checkout completo y un agente menos paralelo suelen ser la decisión más barata.

Un contrato operativo antes de arrancar el agente

El prompt debe describir una frontera, no solo un objetivo: rutas que puede modificar, archivos prohibidos, datos de prueba, comandos de setup, tests obligatorios y condición para pedir ayuda. Escríbelo junto al trabajo, no solo en la conversación, para que un reintento o una revisión humana pueda comprobar el mismo contrato.

Una plantilla mínima: base_sha, branch, worktree_path, allowed_paths, forbidden_paths, setup, verify, network_policy y handoff. El handoff debe incluir resumen, archivos tocados, pruebas ejecutadas, pruebas no ejecutadas y riesgos. Si el agente no puede completar verify, su resultado es un borrador bloqueado, no un cambio listo para merge.

Los límites de permisos siguen fuera de Git. Ejecuta tareas de lectura en un sandbox de lectura, separa la red de la escritura de código y solicita aprobación para operaciones que afecten recursos externos. El worktree organiza el checkout; el sandbox y la política controlan lo que el proceso puede hacer.

Validar cada worktree antes de mirar el diff

Un diff bonito no demuestra que el agente partió de una base sana. Primero registra la revisión inicial y confirma que no heredó cambios locales. Después ejecuta setup y pruebas en el propio directorio del worktree. Nunca valides desde el worktree principal 'por comodidad': eso abre la puerta a probar una cosa y entregar otra.

checklist ejecutable por tarea

git status --porcelain
git rev-parse HEAD
make setup
make test
git diff --check
git diff --stat

Añade pruebas negativas cuando el cambio toca permisos, aislamiento de tenant o acciones mutantes. El caso feliz debe usar fixtures estables; un agente no debe necesitar credenciales de producción para demostrar que una validación de entrada funciona. Conserva logs redactados y el SHA probado como artefactos de la tarea.

La integración sigue siendo secuencial

Los worktrees aceleran la exploración, pero no autorizan merges simultáneos sobre una misma rama objetivo. Rebasea o actualiza cada rama contra una referencia reciente, ejecuta la suite que corresponda y revisa el diff con contexto. Fusiona un cambio, vuelve a calcular la base del siguiente y repite. Es menos espectacular que un enjambre, y bastante más fiable.

En CI, protege despliegues y migraciones con un grupo de concurrencia. GitHub Actions garantiza que solo un job o workflow con la misma clave de concurrencia se ejecuta a la vez; úsalo para impedir que dos pipelines publiquen el mismo entorno o apliquen cambios incompatibles mientras tus agentes trabajan en ramas separadas.

.github/workflows/deploy.yml

concurrency:
  group: deploy-staging
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: ./scripts/deploy-staging.sh

Limpieza: no borres directorios a ciegas

Después de mergear, usa git worktree remove sobre un worktree limpio. Git se niega a eliminar un worktree con cambios rastreados o archivos no rastreados salvo que fuerces la operación; esa fricción es una revisión final de bajo coste, no algo que debas automatizar con un rm -rf genérico.

Si un directorio se perdió fuera de Git, inspecciona primero git worktree list --verbose y usa git worktree prune --dry-run antes de limpiar metadatos obsoletos. prune arregla registros de worktrees ausentes; no recupera el contenido que alguien eliminó manualmente. Para worktrees en un disco externo o efímero, git worktree lock --reason evita que Git los considere basura mientras están desconectados.

Evita git clean -xfd como final automático de una tarea de agente. La documentación de Git confirma que -x borra también archivos ignorados: ahí suelen vivir .env, artefactos locales y estado que no podrás reconstruir sin ayuda. Si necesitas limpieza, empieza siempre con git clean -nd y limita un path concreto que hayas comprobado.

Checklist para agentes en paralelo

Crear una rama y un worktree por tarea, ambos con un nombre técnico y una base SHA registrada.
Dar a cada agente rutas permitidas, rutas prohibidas, setup, tests obligatorios y un handoff verificable.
Mantener AGENTS.md, scripts de bootstrap y fixtures versionados; no copiar secretos reales entre worktrees.
Configurar por worktree sparse-checkout, hooks o ajustes locales que no deban filtrarse al repositorio común.
Ejecutar setup, tests y git diff --check dentro del worktree que generó el cambio.
Serializar merge, migraciones y despliegues aunque la investigación y edición hayan sido paralelas.
Usar git worktree remove en árboles limpios y simular cualquier prune o clean antes de borrar algo.

Preguntas frecuentes

¿Qué es un Git worktree?

Es un checkout adicional enlazado al mismo repositorio. Tiene su propio directorio de trabajo, HEAD e índice, por lo que permite trabajar en ramas distintas al mismo tiempo sin cambiar el checkout principal.

¿Un worktree permite que dos agentes modifiquen la misma rama?

No es el diseño seguro. Git normalmente impide que una rama esté checkout en dos worktrees; usa una rama por tarea y resuelve la integración mediante commits, rebase, CI y revisión.

¿Los worktrees comparten node_modules, .env o puertos?

No comparten el directorio de trabajo, pero tampoco aíslan recursos externos. Cada worktree necesita su bootstrap; procesos, caches globales, puertos, bases de datos y credenciales requieren controles propios.

¿Debo usar sparse-checkout para cada agente?

Solo cuando el monorepo y la tarea lo justifican. Reduce I/O y contexto, pero puede romper scripts que esperan el árbol completo y no es un control de seguridad.

¿Puedo borrar un worktree con rm -rf?

No como procedimiento normal. Usa git worktree remove cuando esté limpio; si hay inconsistencias, inspecciona y prueba git worktree prune --dry-run antes de tocar metadatos.

¿Los worktrees sustituyen la revisión humana?

No. Aíslan la edición, pero no validan arquitectura, permisos, pruebas, impacto de migraciones ni calidad del merge. La cola de integración debe seguir teniendo gates explícitos.

Cómo ejecutar dos tareas de agentes con Git worktree sin colisiones

Registrar la base. Parte de un commit o rama remota explícita y anota su SHA junto a cada tarea.
Dividir el trabajo. Define dos cambios con rutas y contratos separados; no paralelices una misma interfaz o migración.
Crear las ramas. Ejecuta git worktree add -b para cada rama y directorio de tarea, sin forzar ramas ya checkout.
Preparar el entorno. Ejecuta el bootstrap del repositorio en cada worktree con fixtures y secretos de desarrollo mínimos.
Cargar instrucciones. Mantén AGENTS.md y los comandos de verify versionados para que cada agente reciba el mismo contexto comprobable.
Acotar el agente. Entrega rutas permitidas, prohibiciones, política de red y condición de handoff antes de que edite.
Verificar localmente. Corre tests, lint y git diff --check desde el worktree que produjo el cambio; guarda SHA y resultados.
Integrar de uno en uno. Actualiza la rama objetivo, revisa el diff y CI, mergea un cambio y recalcula la base del siguiente.
Retirar con seguridad. Cuando el árbol esté limpio y el cambio integrado, elimina con git worktree remove; simula prune o clean antes de cualquier limpieza. > ### Límite sano > > Paraleliza investigación y tareas acotadas. No paralelices criterio técnico ni integración final.

Fuentes y referencias

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

DEV Community