Faire tourner des agents de code en parallèle dans des git worktrees

Lancez deux agents de code dans le même checkout et vous comprendrez vite pourquoi les équipes logicielles utilisent des branches. Un agent renomme un module pendant que l’autre lance la suite de tests sur la moitié de ce renommage. L’un indexe des fichiers que l’autre vient de supprimer. Aucun des deux n’a tort ; ils partagent simplement le même bureau.

SuperDevSpace fait travailler un manager et plusieurs workers sur un même dépôt en même temps. Cet article explique le mécanisme qui les sépare — les git worktrees — et les règles précises que l’application applique autour d’eux.

Qu’est-ce qu’un git worktree

Un dépôt git a normalement un seul répertoire de travail. git worktree permet à un même dépôt d’en avoir plusieurs, chacun sur sa propre branche, tous partageant la même base d’objets. Pas de deuxième clone, pas de deuxième copie de l’historique : un nouveau worktree coûte les fichiers d’un checkout, rien de plus.

Vous pouvez l’essayer à la main dans n’importe quel dépôt. Les commandes sont les mêmes partout ; seul le shell change :

git worktree add -b agent/frontend-demo ../myrepo-frontend
git worktree list
cd ../myrepo-frontend && git status
cd - && git worktree remove ../myrepo-frontend

git worktree add -b agent/frontend-demo ..\myrepo-frontend
git worktree list
cd ..\myrepo-frontend; git status
cd ..\myrepo; git worktree remove ..\myrepo-frontend

Chaque worktree a son propre HEAD, son propre index et ses propres fichiers. Deux processus peuvent modifier, compiler et tester dans deux worktrees à la fois sans voir les changements à moitié faits de l’autre. C’est exactement la propriété dont une équipe d’agents a besoin.

Comment SuperDevSpace les utilise

Les règles sont simples, et les mêmes pour toutes les organisations :

• Le manager travaille dans votre checkout principal. Il planifie, relit et fusionne ; c’est le seul endroit où les branches se rejoignent.
• Chaque worker reçoit son propre worktree sur sa propre branche. Quand le manager recrute un worker, l’application exécute git worktree add -b <branche> <chemin> pour lui. La branche s’appelle agent/<nom-du-worker>-<horodatage>, sauf si vous lui avez donné un nom.
• Les worktrees vivent dans le dossier de données de l’application, sous worktrees/<organisation>/<worker>, jamais dans votre dépôt. Votre dossier de projet ne se remplit pas de répertoires d’agents.
• Chaque tour est commité. Quand un worker termine un tour, l’application commite tout ce qui a changé dans son worktree (agent(<nom>): turn). Rien de ce qu’a fait un worker n’existe seulement dans un répertoire de travail non commité.
• La fusion est un squash merge. Quand le manager accepte le rapport d’un worker, la branche est fusionnée dans votre ligne avec git merge --squash, en un seul commit. En cas de conflit, l’application abandonne la fusion et laisse le dépôt propre pour l’opération suivante, au lieu de vous laisser au milieu d’un merge en conflit.
• Une seule opération git à la fois par dépôt. Les répertoires de worktree isolent les fichiers ; une file par dépôt sérialise les commandes git elles-mêmes, si bien que deux workers qui terminent au même instant ne se disputent jamais les métadonnées de git.

Le diagramme en texte

gitGraph
  commit id: "main"
  branch agent/frontend
  commit id: "frontend : tour 1"
  checkout main
  branch agent/qa
  commit id: "qa : tour 1"
  checkout agent/frontend
  commit id: "frontend : tour 2"
  checkout main
  merge agent/frontend id: "squash : frontend"
  merge agent/qa id: "squash : qa"

Sur le tableau, cela se traduit par plusieurs tâches en cours en même temps, chacune confiée à un worker différent, chacune avec sa propre branche en dessous.

Ce qui rend la chose praticable

Un worktree neuf ne contient que ce que git suit. Cela ne suffit généralement pas à faire tourner un projet : node_modules, un .env local, des fichiers générés. Deux détails règlent la question.

Un script d’installation par dépôt

Si votre dépôt contient .super/scripts/setup-worktree.sh, l’application l’exécute dans chaque nouveau worktree avant le démarrage du worker, avec SUPERDEV_MAIN_REPO pointant vers votre checkout principal. Sa sortie s’affiche en direct — une longue installation n’est pas une attente à l’aveugle — et vous pouvez l’annuler.

#!/usr/bin/env bash
set -euo pipefail
# Copier les fichiers purement locaux depuis le checkout principal
cp "$SUPERDEV_MAIN_REPO/.env" .env 2>/dev/null || true
# Installer les dépendances (pnpm crée des liens depuis un store partagé, c’est rapide)
pnpm install --frozen-lockfile

Les submodules

git worktree add laisse les submodules vides. Si le nouveau worktree contient un fichier .gitmodules, l’application y lance git submodule update --init --recursive, pour qu’aucun worker ne compile contre une dépendance discrètement absente.

Faire le ménage sans perdre de travail

Les worktrees s’accumulent. L’application les récupère, mais avec prudence :

Le diagramme en texte

flowchart TD
  start["Le worker a terminé"] --> clean{"Arbre de travail propre ?"}
  clean -->|"non"| keep["Le worktree reste"]
  clean -->|"oui"| merged{"Branche fusionnée dans votre ligne ?"}
  merged -->|"non"| keep
  merged -->|"oui"| remove["Le worktree est supprimé"]

Un worktree avec des modifications non commitées, ou dont la branche contient du travail pas encore dans votre ligne, reste où il est. Un dossier supprimé se recrée ; un travail perdu, non. La même prudence s’applique aux branches : l’application garde la trace des branches qu’elle a créées et ne touche qu’à celles-là.

Ce que cela change pour vous

Avec chaque worker sur sa propre branche, « lancer quatre agents à la fois » n’est plus un pari. Vous pouvez :

• donner au manager une directive qui se découpe en tâches indépendantes et laisser les workers tourner en parallèle ;
• lire le diff de n’importe quel worker isolément, à côté de la conversation qui l’a produit ;
• rejeter la modification d’un worker sans déranger les autres ;
• continuer à utiliser votre checkout principal pendant que l’équipe travaille.

C’est la même discipline qu’une équipe humaine, appliquée à des agents qui ne peuvent pas vous prévenir qu’ils sont sur le point de se marcher dessus. Si vous vous demandez pourquoi nous avons construit toute une application autour de cela, le premier article raconte l’histoire.

L’essayer

L’essai de 14 jours est en Premium, sans carte. Téléchargez SuperDevSpace, associez une nouvelle organisation à un dépôt et regardez les worktrees apparaître à mesure que le manager recrute ses premiers workers.