Shadow Workspace & Git Worktrees

1. Visión general del concepto y problema sistémico

Cuando un agente autónomo comienza a modificar la base de código en el directorio activo del desarrollador, se produce un bloqueo crítico (Workflow Lockout). Si el agente edita 25 archivos, compila código, instala paquetes y ejecuta pruebas, la persona no puede escribir código, verificar su servidor local o cambiar ramas simultáneamente: los cambios no confirmados del desarrollador y del agente inevitablemente se mezclan, causando conflictos.

Además, si el agente falla, se cuelga o alucina, restablecer el árbol de trabajo (git checkout -f o git clean) puede borrar accidentalmente el trabajo no confirmado del ingeniero.

Shadow Workspace (espacio de trabajo sombra) basado en Git Worktrees resuelve este problema de una vez por todas. El agente obtiene un directorio completamente aislado en el disco, vinculado a su propia rama. El ingeniero continúa escribiendo código en su editor favorito, mientras el agente en segundo plano realiza un complicado refactorizado en un entorno sombra sin afectar la estación de trabajo activa.

2. Taxonomía arquitectónica y modelo mental

La arquitectura de interacción con los espacios sombra se basa en la distribución de discos y una base de objetos Git compartida:

┌─────────────────────────────────────────────────────────────┐
│                 SHARED REPOSITORY OBJECTS (.git)            │
└──────────────┬───────────────────────────────┬──────────────┘
               │                               │
               ▼                               ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│  PRIMARY WORKSPACE (Human)  │ │ SHADOW WORKSPACE (AI Agent) │
│ • Branch: feature/payments  │ │ • Branch: agent/fix-auth    │
│ • Path: ~/projects/app      │ │ • Path: ~/.worktrees/task-42│
│ • Port: 3000 (Active)       │ │ • Port: 3001 (Isolated)     │
│ • Uncommitted local edits   │ │ • Automated ReAct Loop      │
└─────────────────────────────┘ └─────────────────────────────┘

1. Base de objetos compartida (Single Object Database):
   • Todos los espacios de trabajo utilizan una base local de objetos Git (.git/objects). No es necesario volver a descargar gigabytes de historial o realizar un lento git clone.
2. Worktree de agente dinámico:
   • Se crea en milisegundos con el comando git worktree add -b <agent-branch> <shadow-path> <base-commit>.
   • Proporciona al agente un árbol de trabajo completamente limpio, sin basura ni ediciones incompletas del humano.
3. Aislamiento del entorno (Environment Decoupling):
   • Archivos de configuración de entorno propios (.env.test), puertos de red aislados y directorios temporales de compilación propios.
4. Mecanismo de reconciliación y limpieza (Reconciliation & Cleanup):
   • Después de la verificación y la exitosa ejecución de pruebas, los cambios se registran como un commit atómico, tras lo cual el directorio sombra se elimina de forma segura (git worktree remove).

3. Pipeline técnico y mecánica interna

Ciclo de vida de una tarea en el espacio de trabajo sombra:

1. Iniciación y asignación del espacio sombra: El orquestador (o el desarrollador a través de un comando como agy-run-in-worktree) genera un ID único para la tarea y crea un directorio:

   git worktree add -b agent/auth-refactor ../shadow-auth main
   

2. Vinculación rápida de dependencias: Para no esperar minutos a que se ejecute npm install, el orquestador crea enlaces simbólicos a node_modules compartidos o utiliza la caché de contenido de pnpm:

   ln -s $(pwd)/node_modules ../shadow-auth/node_modules
   

3. Trabajo autónomo del agente: El agente se ejecuta con el directorio de trabajo Cwd = ../shadow-auth. Él mismo:
   • Lee y edita archivos.
   • Inicia un servidor local en un puerto aislado (PORT=3005 npm run test:e2e).
   • Itera en un ciclo ReAct hasta el éxito completo.
4. Validación del resultado: Todas las pruebas se ejecutan en el espacio sombra. Si el agente rompe la compilación, el ingeniero no experimenta ningún problema en su IDE principal.
5. Confirmación e integración: El agente realiza el commit final en la rama agent/auth-refactor. El orquestador elimina el directorio sombra:

   git worktree remove ../shadow-auth
   

6. Presentación del resultado al ingeniero: El ingeniero ve un mensaje de tarea lista y puede realizar un rápido git merge o abrir un PR.

4. Escenarios prácticos de ingeniería en producción

01. Desarrollo paralelo de una característica sin interrumpir al desarrollador

El ingeniero está diseñando una nueva pantalla de configuración en la rama main:

• Al mismo tiempo, inicia un agente en segundo plano para escribir migraciones de base de datos y controladores en el espacio sombra.
• El agente ejecuta pruebas, corrige tipos y prepara la parte del backend en aislamiento.
• El ingeniero no interrumpe en absoluto el diseño de su pantalla.

02. Pruebas de torneo de hipótesis competidoras (Multi-Agent Bake-off)

Búsqueda del algoritmo más rápido para procesar grandes conjuntos de datos:

• El orquestador despliega tres Worktrees paralelos: agent-a, agent-b, agent-c.
• A tres modelos diferentes (Claude 3.7 Sonnet, DeepSeek R1, GPT-4o) se les asigna la misma tarea de optimización.
• Se ejecuta un benchmark; se elige la solución con el mejor indicador de latencia, y los otros dos espacios de trabajo se eliminan automáticamente.

03. Ejecución segura de scripts de agentes no verificados

Pruebas de una actualización radical del núcleo del sistema:

• Si el agente rompe completamente la estructura de archivos o genera código no funcional, el desarrollador simplemente elimina el directorio del espacio de trabajo en 1 segundo sin temor a dañar el repositorio local de Git.

5. Errores comunes, trampas y seguridad

• Conflictos de puertos de red ocupados (Port Collisions): Si el espacio de trabajo sombra ejecuta pruebas que intentan levantar un servidor web en un puerto fijo 3000, fallarán con el error EADDRINUSE, si ese puerto está ocupado por el desarrollador. Siempre configure la parametrización de puertos.
• Bloqueos de ramas (Worktree Branch Locks): Git prohíbe montar la misma rama en dos Worktrees diferentes al mismo tiempo. Los agentes sombra siempre deben trabajar en ramas nuevas y únicas.
• Acumulación de espacio en disco: Si el orquestador termina inesperadamente sin el paso de limpieza (git worktree remove), pueden quedar decenas de carpetas olvidadas en el disco. Ejecute periódicamente git worktree prune.
• Fugas de archivos no controlados (.env.local): Los archivos que están en .gitignore no se copian automáticamente en el nuevo worktree. El agente necesita acceso explícito a las variables de entorno de prueba para pasar las pruebas correctamente.