Utiliser les worktrees Git avec les agents de codage IA

La méthode fiable pour exécuter plusieurs agents de codage IA sur un même dépôt tient en une règle : une tâche, une branche, un worktree, un agent. Chaque agent dispose de son propre répertoire créé avec git worktree add, travaille sur sa propre branche et ne touche jamais aux fichiers qu’un autre agent est en train de modifier.

La plupart des développeurs découvrent ce pattern à leurs dépens. Deux agents dans un même checkout écrasent silencieusement leurs modifications inachevées respectives, ou bien l’un d’eux se bloque en tentant de basculer sur une branche déjà extraite ailleurs. Cet article traite spécifiquement du workflow des agents : ce que ce pattern isole, ce qu’il n’isole délibérément pas, et que faire lorsque trois agents terminent en même temps.

Le pattern des worktrees Git pour les agents IA

Le pattern « un agent par worktree » se résume à deux commandes par tâche. Créez un worktree avec une nouvelle branche basée sur main, puis démarrez un agent à l’intérieur :

git worktree add ../task-a -b agent/task-a main
git worktree add ../task-b -b agent/task-b main

Dirigez un agent vers ../task-a et un autre vers ../task-b. Chacun dispose de son propre répertoire de travail, de son propre index et de son propre HEAD, tandis que tous les worktrees partagent la même base d’objets et les mêmes refs : les commits réalisés dans l’un sont donc immédiatement visibles depuis les autres. Liez le worktree à la tâche, et non à l’agent : créez-le au démarrage du travail, supprimez-le lorsque la branche est fusionnée. Anthropic documente cette même séquence manuelle dans le guide des worktrees de Claude Code, et Cursor exécute les agents dans des worktrees isolés depuis sa fenêtre Agents ; Codex fonctionne de la même manière lorsqu’on le pointe vers un répertoire.

Pourquoi un répertoire partagé unique échoue-t-il ?

Deux agents dans un même répertoire échouent silencieusement : ni Git ni les agents ne signalent d’erreur lorsque l’un écrase les modifications non validées de l’autre, si bien que les dégâts n’apparaissent qu’au moment de la revue. La détection de conflits de Git compare des commits ; les écritures concurrentes dans le même arbre de travail ne l’atteignent jamais.

Le second mode de défaillance est plus bruyant, mais plus grave. Les opérations Git concurrentes dans un répertoire partagé entrent en collision sur .git/index.lock, et si un agent plante alors qu’il détient le verrou, le fichier obsolète bloque les commandes Git de tous les autres agents jusqu’à ce que quelqu’un le supprime à la main. Certains agents réessaient ; d’autres renoncent à commiter et continuent de générer du code par-dessus un état non validé qui ne cesse de croître. Des worktrees séparés dissolvent ces deux problèmes, car chaque worktree indexe ses modifications dans son propre index plutôt que dans un index partagé.

Ce qu’un nouveau worktree ne contient pas

Un nouveau worktree ne contient que les fichiers suivis par Git : node_modules, .env, les caches de build et tout ce qui figure dans .gitignore sont donc absents tant que vous ne les créez pas. Un agent démarré dans un worktree vierge échouera dès sa première exécution de tests ou, pire, réécrira « obligeamment » la configuration pour compenser. Initialisez chaque worktree avant de lancer l’agent :

cd ../task-a
npm ci
cp ../main-repo/.env .env

npm ci est la commande d’installation appropriée ici : elle est conçue pour les environnements vierges et installe exactement ce que spécifie le lockfile. Si votre agent est Claude Code, un fichier .worktreeinclude peut transporter des fichiers ignorés par Git comme .env vers les worktrees que Claude Code crée lui-même, mais il ne s’applique pas aux worktrees que vous créez manuellement avec git worktree add : la copie manuelle fonctionne donc avec tous les outils.

Ce que les worktrees n’isolent pas

Les worktrees isolent les fichiers, pas l’environnement d’exécution : les ports, les bases de données, les volumes Docker et les caches partagés appartiennent à la machine. Deux serveurs de développement lancés depuis deux worktrees se disputeront donc toujours le port 3000. La frontière du répertoire ne signifie rien pour tout ce qui est adressé par nom d’hôte ou par port.

Attribuez à chaque worktree son propre port et sa propre base de données avant de lancer un agent qui exécute des migrations, car un changement de schéma effectué depuis un worktree se répercute sur toute base de données partagée avec les autres. Définissez les deux dans le .env copié :

# ../task-a/.env
PORT=3001
DATABASE_URL=postgres://localhost:5432/app_agent_task_a

Nommer la base de données d’après la branche facilite le repérage et la suppression ultérieure des bases obsolètes. Les conteneurs peuvent également isoler la couche d’exécution, mais les compromis que cela implique mériteraient un article à part entière.

Comment indiquer à l’agent qu’il se trouve dans un worktree ?

Une branche ne peut être extraite que dans un seul worktree à la fois : un agent qui tente de se synchroniser en exécutant git checkout main obtient donc une erreur et se retrouve souvent bloqué. Le manuel de git checkout décrit ce comportement et mentionne --ignore-other-worktrees comme moyen de le contourner. Ne laissez pas l’agent découvrir cela à l’exécution ; inscrivez-le dans le fichier d’instructions que l’agent lit (AGENTS.md, CLAUDE.md ou équivalent) :

You are working inside a git worktree.
Stay on the current branch. Never run `git checkout` or `git switch`.
To sync with main, run `git fetch origin` and `git rebase origin/main`.

Lorsqu’un agent doit seulement lire ou compiler un commit précis, faites l’impasse sur les branches : git worktree add --detach crée un worktree avec un HEAD détaché, ce qui contourne entièrement la règle d’exclusivité.

git worktree add --detach ../review-b1a2c3 b1a2c3

Comment fusionner ce qui revient ?

Les worktrees n’éliminent pas les conflits de fusion ; ils les déplacent d’écrasements silencieux à l’exécution vers des conflits visibles au moment de la fusion, là où l’outillage Git habituel sait les traiter. Lorsque plusieurs agents terminent en même temps, intégrez en série : fusionnez une branche, rebasez la suivante sur la branche main mise à jour, fusionnez-la, et ainsi de suite.

cd ../main-repo
git merge agent/task-a

cd ../task-b
git rebase main
cd ../main-repo
git merge agent/task-b

Chaque rebase fait apparaître les conflits par rapport à tout ce qui a déjà été fusionné, une branche à la fois, au lieu d’empiler les mauvaises surprises à trois voies. La règle d’ordonnancement se situe en amont de la fusion : les tâches qui touchent les mêmes fichiers, ou dont l’une consomme la sortie de l’autre, doivent être séquencées plutôt que parallélisées. Aucune organisation de worktrees ne rattrape une décomposition de tâches qui n’était pas indépendante dès le départ.

Combien d’agents, et quand faire le ménage

Le plafond pratique n’est ni Git ni l’espace disque : c’est votre capacité de revue, puisque chaque agent parallèle produit une branche que vous devez lire, tester et fusionner. Les équipes qui publient sur ce workflow, comme l’équipe d’ingénierie d’incident.io, évoquent l’exécution de quatre ou cinq agents simultanément, et la plupart des développeurs trouvent qu’un nombre plus réduit suffit largement. Lorsqu’une branche est fusionnée, exécutez git worktree remove ../task-a ; comme l’initialisation a ajouté des fichiers non suivis, attendez-vous à devoir utiliser --force, que git worktree remove exige pour les worktrees non propres. Si un répertoire a été supprimé avec rm -rf à la place, git worktree prune nettoie les métadonnées obsolètes que Git conserve encore.

Commencer avec deux agents

Une tâche, une branche, un worktree, un agent : cette règle transforme les agents parallèles, source de corruption silencieuse, en un ensemble de branches examinables. Commencez avec deux : créez les worktrees, initialisez chacun avec npm ci et un .env propre à la tâche, ajoutez la consigne de rester sur la branche, et entraînez-vous à la séquence rebase-puis-fusion avant de dépasser ce que vous pouvez réellement relire.

FAQ

Vaut-il mieux utiliser des worktrees Git ou des clones distincts pour exécuter des agents IA en parallèle ?

Les worktrees sont généralement préférables, car ils partagent une seule base d'objets : un commit réalisé dans un worktree est immédiatement visible depuis les autres, sans push ni fetch, et l'historique n'est stocké qu'une seule fois sur le disque. Les clones distincts dupliquent l'intégralité de l'historique et nécessitent des push et des fetch pour échanger les commits. Les clones ne l'emportent que lorsque vous avez besoin d'une isolation complète, par exemple pour les dépôts comportant des sous-modules.

Les worktrees Git fonctionnent-ils avec les dépôts qui utilisent des sous-modules ?

Seulement en partie. Le manuel des worktrees de Git classe la prise en charge des sous-modules dans la section BUGS, qualifie les checkouts multiples d'expérimentaux et déconseille d'extraire un superprojet à plusieurs endroits à la fois. Un worktree contenant des sous-modules ne peut par ailleurs pas être déplacé avec git worktree move. Pour exécuter des agents en parallèle sur un dépôt à sous-modules, des clones complets distincts constituent un mécanisme d'isolation plus sûr, même s'ils dupliquent l'historique et imposent un push pour partager les commits entre checkouts.

Tous les worktrees Git partagent-ils la même configuration Git ?

Oui. Chaque worktree lit la même configuration de dépôt, sauf si vous choisissez explicitement le contraire. Pour donner à un worktree ses propres paramètres, exécutez git config extensions.worktreeConfig true, puis écrivez les valeurs avec git config --worktree, ce qui les conserve dans le fichier config.worktree propre à ce worktree. La contrepartie : les anciennes versions de Git n'ouvriront plus le dépôt une fois l'extension activée.

La suppression d'un worktree efface-t-elle la branche de l'agent ?

Non. Les branches sont des refs partagées à l'échelle du dépôt : git worktree remove supprime le répertoire de travail et ses métadonnées, mais laisse intacts la branche et l'ensemble de ses commits. Seules les modifications non validées de ce répertoire sont perdues, raison pour laquelle remove refuse les worktrees non propres à moins de passer --force. Supprimez la branche séparément avec git branch -d une fois qu'elle est fusionnée.