Agents Claude Code et Codex en parallèle : l’isolation qui évite de brûler vos tokens

Voir la vidéo : isoler des agents de code qui travaillent en parallèle

Le problème n’est pas de lancer plus d’agents

Je fais tourner des dizaines d’agents de code Claude Code et Codex, 24 heures sur 24. Les lancer en parallèle est facile. Leur permettre de travailler sans se marcher dessus est beaucoup plus difficile.

Un worktree Git donne à chaque agent son propre dossier et sa propre branche. C’est nécessaire, mais insuffisant. L’application continue souvent d’utiliser les mêmes ressources : une base de données commune, un port partagé, les mêmes variables d’environnement, un serveur déjà lancé ou un navigateur E2E connecté à une instance qui ne correspond pas à la branche testée.

J’en ai payé le prix directement : une boucle entière de 24 heures a brûlé 12 millions de tokens pour rien. Les agents écrivaient du code, lançaient des tests et tentaient de corriger les erreurs. Mais une partie des erreurs venait de collisions entre leurs environnements, pas de leur implémentation.

Un agent peut alors passer des heures à réparer du code qui fonctionne. Il observe un symptôme réel, mais attribue ce symptôme à la mauvaise cause.

Pourquoi les worktrees ne suffisent pas

Le worktree isole les fichiers suivis par Git. Il n’isole pas automatiquement l’état d’exécution de l’application.

Git peut donc être parfaitement propre alors que l’environnement d’exécution est contaminé.

Les erreurs les plus trompeuses

Les collisions produisent rarement un message disant clairement : « un autre agent vient de modifier ta base ». Elles ressemblent plutôt à des bugs ordinaires : contrainte absente, utilisateur introuvable, serveur indisponible, session expirée, migration déjà appliquée ou élément d’interface invisible.

L’agent lit l’erreur, inspecte son code et propose une correction locale. Si la cause se trouve dans une ressource partagée, chaque nouvelle correction peut l’éloigner davantage de la bonne solution.

Une sandbox complète par user story

La bonne unité d’isolation n’est pas l’agent. C’est la user story.

Chaque story reçoit son propre ensemble de ressources :

• une branche dédiée ;
• un worktree dédié ;
• un port réservé ;
• une base de données isolée ;
• un fichier d’environnement propre ;
• un serveur lancé depuis le bon worktree ;
• une cible E2E reliée à ce serveur ;
• des migrations et des données de test appliquées uniquement à cette sandbox.

Le numéro de story doit apparaître partout. Il devient la clé qui permet à un humain, un script ou un agent de relier les ressources entre elles.

Exemple de convention branche, worktree, port, base et E2E

Voici une convention générique, sans dépendre d’un outil précis :

Le principe compte plus que la syntaxe. Une même valeur, <numero>, identifie toute la chaîne.

story       = STORY-<numero>
branch      = story/<numero>-<sujet>
worktree    = ../worktrees/story-<numero>
port        = PORT_<numero>
database    = app_story_<numero>
env         = .env.story-<numero>
server      = server-story-<numero>
e2e_project = e2e-story-<numero>
e2e_baseUrl = http://127.0.0.1:${PORT_<numero>}

L’agent ne choisit pas ces valeurs au hasard. Un script prépare la sandbox, écrit la configuration et transmet à l’agent un contexte déjà cohérent.

Le cycle de vie d’une story isolée

Préparer avant de déléguer

Avant de lancer Claude Code ou Codex, le système crée la branche et le worktree, réserve le port, prépare la base puis génère le fichier d’environnement. Les migrations sont exécutées contre la base de la story, jamais contre une base partagée par défaut.

Cette étape doit échouer immédiatement si une ressource demandée est déjà occupée. Un refus clair avant le lancement coûte moins cher qu’un agent qui enquête sur une collision pendant toute une boucle.

Démarrer le serveur dans la bonne sandbox

Le serveur doit être lancé depuis le worktree de la story avec son fichier d’environnement explicite. Le répertoire courant ne suffit pas comme garantie : le processus doit exposer dans ses logs la story, le port et la base utilisés.

Un contrôle de santé doit ensuite confirmer que le serveur répond sur l’URL attendue. Sans cette vérification, le navigateur E2E peut tomber sur un ancien processus encore actif.

Exécuter les E2E contre une cible explicite

Le projet E2E reçoit une baseURL propre à la story. Les sessions, fichiers temporaires et données de test doivent aussi être séparés lorsque le framework les conserve entre deux exécutions.

L’agent doit pouvoir répondre sans ambiguïté à trois questions :

1. Quel commit est testé ?
2. Quel serveur exécute ce commit ?
3. Quelle base contient les données observées par le test ?

Si une réponse manque, le résultat E2E n’est pas une preuve fiable.

Nettoyer sans toucher aux autres stories

Après intégration ou abandon, le système arrête le serveur de la story, libère le port, supprime sa base et retire son worktree. Le nettoyage doit cibler des noms complets dérivés du numéro de story. Une commande globale de suppression transforme vite l’isolation en nouveau risque.

Les garde-fous à donner aux agents

L’isolation technique fonctionne mieux avec des règles simples et vérifiables :

• ne jamais utiliser une base ou un port par défaut ;
• ne jamais lancer une migration sans afficher la cible ;
• refuser un test E2E si la baseURL ne correspond pas à la story ;
• enregistrer la branche, le commit, le port et la base dans les logs ;
• vérifier la santé du serveur avant les tests ;
• traiter une ressource déjà occupée comme une erreur de configuration, pas comme un bug applicatif ;
• limiter chaque agent au worktree et aux services de sa story.

Ces règles réduisent aussi le coût du diagnostic humain. Quand un test échoue, on sait quelle version, quel serveur et quelles données examiner.

Ce que cette méthode change

Avec une sandbox par story, les agents peuvent encore produire de mauvais changements. L’isolation ne remplace ni les tests, ni la revue, ni une spécification claire. Elle retire cependant une catégorie entière de faux signaux causés par les ressources partagées.

Cela change la qualité de la boucle autonome. L’agent travaille sur un environnement qu’il peut modifier, redémarrer et remettre à zéro sans casser celui de ses voisins. Ses observations deviennent reproductibles. Une migration appartient à une story. Une donnée de test appartient à une story. Un navigateur regarde le serveur de cette story.

Conclusion

Faire travailler Claude Code et Codex en parallèle demande plus que plusieurs branches. Il faut isoler tout ce que le code touche pendant son exécution : worktree, port, base, environnement, migrations, données, serveur et navigateur E2E.

La convention la plus utile reste la plus simple : placer le numéro de story dans chaque ressource, créer la sandbox avant de lancer l’agent et la détruire proprement après son travail. C’est ce qui évite qu’un agent passe sa boucle à corriger les effets de bord produits par un autre.

Voir la méthode complète en vidéo

Recevoir les prochains retours terrain sur le développement agentique