Git worktree para agentes de IA: trabajo paralelo sin pisar tu repositorio
Un worktree no hace seguro a un agente, pero evita la colisión más tonta: dos tareas modificando el mismo directorio. Úsalo para aislar ramas, contexto y validación; no para saltarte revisión, secretos o integración.
`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.
Checklist
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.
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 gratisLos 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.
Puntos a revisar
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.
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.
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.
Checklist
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.
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.
Fuentes y referencias
También te puede interesar
Cómo coordinar varios agentes de códigoCodex CLI: configuración, AGENTS.md y permisosPRs de agentes de IA: gobernanza humanaClaude Code: subagentes, contexto y permisosHooks para agentes de código: guardrails y validaciónRecibe 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
