Shadow Git Worktrees & Branching

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

Lorsqu'un développeur lance un agent lourd dans le répertoire courant du projet, le travail est paralysé :

• Les fichiers clignotent dans VS Code ou Cursor, l'écran saccade, et le serveur local Next.js se recharge 20 fois par minute.
• Si l'agent corrompt la configuration TypeScript, le développeur perd l'autocomplétion dans ses onglets ouverts.
• Il est impossible de traiter une autre tâche en parallèle tant que l'agent n'a pas terminé sa session.

Shadow Git Worktrees éliminent ce problème. Au lieu d'opérer dans votre espace de travail actuel, l'agent obtient son propre « arbre fantôme » (Worktree) dans un répertoire adjacent.

2. Taxonomie architecturale et modèle mental

┌─────────────────────────────────────────────────────────────┐
│                 SHARED .GIT REPOSITORY CORE                 │
└──────────────┬───────────────────────────────┬──────────────┘
               │                               │
               ▼                               ▼
┌──────────────────────────────┐┌──────────────────────────────┐
│ HUMAN WORKSPACE (main)       ││ AGENT WORKTREE (task/ai-fix) │
│ Path: ~/projects/app         ││ Path: ~/projects/app-agent-1 │
│ • Active Cursor IDE Session  ││ • Headless Agent Execution   │
│ • Local Dev Server on :3000  ││ • Test Runner on :3001       │
│ • Zero Flickering / Chaos    ││ • Builds, lints & verifies   │
└──────────────────────────────┘└──────────────┬───────────────┘
                                               │
                                               ▼ Verified Diff
                                ┌──────────────────────────────┐
                                │ MERGE VIA CLEAN PULL REQUEST │
                                └──────────────────────────────┘

3. Scénarios d'ingénierie concrets en production

01. Exécution parallèle de migrations longues

Un ingénieur travaille sur l'UI d'une nouvelle page dans la branche feat/checkout, tandis qu'un agent en arrière-plan, dans un worktree fantôme, réécrit les anciens endpoints backend d'Express vers Fastify dans la branche refactor/api. Une fois les tests passés, l'ingénieur effectue simplement un rapide git merge.

02. Correction spéculative de bugs (Test A/B des approches)

Le développeur lance deux agents dans deux worktrees distincts : l'un résout le problème via une mise à jour de bibliothèque, l'autre via l'écriture d'un polyfill maison. L'ingénieur compare la taille du bundle des deux branches et choisit la meilleure option.

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

• Worktrees oubliés (Encombrement disque) : Si la suppression des arbres de travail après la fin de la tâche n'est pas automatisée, les dossiers node_modules dans des dizaines de worktrees peuvent rapidement saturer le disque dur du laptop. Utilisez des scripts de nettoyage automatiques (git worktree prune).
• Conflits de ports du serveur local : Si le worktree fantôme démarre son propre serveur de test, il peut tenter d'occuper le même port (par exemple, :3000). Il est impératif de passer le flag PORT=3001 dans les variables d'environnement à l'agent.

5. Conclusion stratégique pour l'ingénieur de 2026

Les Shadow Worktrees rendent la collaboration avec l'IA véritablement asynchrone. Le développeur n'est plus otage d'un terminal qui attend la fin de la génération : l'agent devient un collègue invisible, travaillant dans une pièce voisine et frappant à la porte uniquement avec un résultat prêt et testé.