Espace de travail fantôme et Git Worktrees

1. Vue d'ensemble du concept et problème systémique

Lorsqu'un agent autonome commence à modifier la base de code dans le répertoire actif du développeur, un verrouillage critique du workflow (Workflow Lockout) se produit. Si l'agent édite 25 fichiers, compile le code, installe des paquets et exécute des tests, l'humain ne peut plus écrire de code en parallèle, vérifier son serveur local ou changer de branche : les modifications non commitées du développeur et celles de l'agent finissent inévitablement par se mélanger, provoquant des conflits.

Pire encore : si l'agent échoue, se bloque ou hallucine, une réinitialisation de l'arborescence de travail (git checkout -f ou git clean) risque d'effacer accidentellement le travail non commité de l'ingénieur lui-même.

Le Shadow Workspace (espace de travail fantôme), basé sur les Git Worktrees, résout ce problème définitivement. L'agent obtient un répertoire entièrement isolé sur le disque, lié à sa propre branche. L'ingénieur continue de coder dans son éditeur favori pendant que l'agent effectue en arrière-plan un refactoring complexe dans cet environnement fantôme, sans aucun impact sur la station de travail active.

2. Taxonomie architecturale et modèle mental

L'architecture d'interaction avec les espaces fantômes repose sur la séparation des disques et une base d'objets Git partagée :

┌─────────────────────────────────────────────────────────────┐
│                 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 unique d'objets partagée (Single Object Database) :
   • Tous les workspaces utilisent la même base locale d'objets Git (.git/objects). Il n'est pas nécessaire de retélécharger des gigaoctets d'historique ni d'effectuer un git clone lent.
2. Worktree dynamique de l'agent :
   • Créé en quelques millisecondes via la commande git worktree add -b <agent-branch> <shadow-path> <base-commit>.
   • Fournit à l'agent une arborescence de travail parfaitement propre, exempte de résidus et de modifications partielles humaines.
3. Découplage de l'environnement (Environment Decoupling) :
   • Fichiers de configuration propres (.env.test), ports réseau isolés et répertoires temporaires de build dédiés.
4. Mécanisme de réconciliation et de nettoyage (Reconciliation & Cleanup) :
   • Après vérification et réussite des tests, les changements sont encapsulés dans un commit atomique, puis le répertoire fantôme est supprimé en toute sécurité (git worktree remove).

3. Pipeline technique et mécanique interne

Cycle de vie d'une tâche dans un espace de travail fantôme :

1. Initialisation et allocation de l'espace fantôme : L'orchestrateur (ou le développeur via une commande type agy-run-in-worktree) génère un ID de tâche unique et crée le répertoire :

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

2. Liaison rapide des dépendances : Pour éviter d'attendre plusieurs minutes lors d'un npm install, l'orchestrateur crée des liens symboliques vers les node_modules partagés ou utilise le cache par contenu de pnpm :

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

3. Travail autonome de l'agent : L'agent démarre avec le répertoire de travail Cwd = ../shadow-auth. Il procède indépendamment :
   • Lit et modifie les fichiers.
   • Lance un serveur local sur un port isolé (PORT=3005 npm run test:e2e).
   • Itère dans une boucle ReAct jusqu'à succès complet.
4. Validation du résultat : Tous les tests s'exécutent dans l'espace fantôme. Si l'agent casse le build, l'ingénieur ne rencontre aucun problème dans son IDE principal.
5. Fixation et intégration : L'agent effectue un commit final sur la branche agent/auth-refactor. L'orchestrateur supprime le répertoire fantôme :

   git worktree remove ../shadow-auth
   

6. Présentation du résultat à l'ingénieur : L'ingénieur reçoit une notification de complétion de la tâche et peut effectuer un git merge rapide ou ouvrir une PR.

4. Scénarios d'ingénierie pratiques en production

01. Développement parallèle de fonctionnalités sans interruption du flux de travail

L'ingénieur construit une nouvelle écran de paramètres sur la branche main :

• Il lance simultanément un agent en arrière-plan pour écrire les migrations de base de données et les contrôleurs dans l'espace fantôme.
• L'agent exécute les tests, corrige les types et prépare la partie backend en isolation.
• L'ingénieur n'interrompt jamais, même une seconde, le développement de son interface.

02. Test comparatif d'hypothèses concurrentes (Multi-Agent Bake-off)

Recherche de l'algorithme le plus rapide pour le traitement de grands volumes de données :

• L'orchestrateur déploie trois Worktrees parallèles : agent-a, agent-b, agent-c.
• Une même tâche d'optimisation est assignée à trois modèles différents (Claude 3.7 Sonnet, DeepSeek R1, GPT-4o).
• Un benchmark est lancé ; la solution offrant la meilleure latence est retenue, tandis que les deux autres workspaces sont automatiquement supprimés.

03. Exécution sécurisée de scripts agents non vérifiés

Test d'une mise à jour radicale du noyau système :

• Si l'agent détruit complètement la structure de fichiers ou génère du code inutilisable, le développeur supprime simplement le répertoire workspace en 1 seconde, sans crainte d'endommager le dépôt Git local.

5. Pièges courants, erreurs typiques et sécurité

• Conflits de ports réseau (Port Collisions) : Si un workspace fantôme lance des tests tentant implicitement de démarrer un serveur web sur le port fixe 3000, ils échoueront avec une erreur EADDRINUSE si ce port est déjà occupé par le développeur. Configurez toujours la paramétrisation des ports.
• Verrous de branches (Worktree Branch Locks) : Git interdit le montage de la même branche dans deux Worktrees différents simultanément. Les agents fantômes doivent toujours travailler sur des branches nouvelles et uniques.
• Accumulation d'espace disque : Si l'orchestrateur termine anormalement sans étape de nettoyage (git worktree remove), des dizaines de dossiers oubliés peuvent rester sur le disque. Exécutez périodiquement git worktree prune.
• Fuite de fichiers non contrôlés (.env.local) : Les fichiers présents dans .gitignore ne sont pas copiés automatiquement dans le nouveau worktree. Il faut explicitement donner accès à l'agent aux variables d'environnement de test pour assurer la validité des tests.