Claude Code : plusieurs agents IA en parallèle

Claude Code : plusieurs agents IA en parallèle

La méthode la plus fiable consiste à utiliser les subagents pour la recherche, des worktrees Git séparés dès que plusieurs sessions écrivent du code, puis une validation centralisée avant toute fusion. Les équipes qui veulent faire fonctionner plusieurs agents IA avec Claude Code doivent donc traiter quatre sujets dans cet ordre : découper les tâches, isoler les fichiers, vérifier les résultats et fusionner selon les dépendances.

Qui devrait suivre ce workflow ?

Ce guide s’adresse aux développeurs qui utilisent déjà Claude Code dans le terminal, aux responsables techniques qui veulent traiter simultanément une fonctionnalité, ses tests et sa documentation, ainsi qu’aux ingénieurs qui préparent plusieurs sessions Claude Code sur un Mac distant.

L’objectif n’est pas de lancer le plus grand nombre possible d’agents. Il consiste à obtenir plusieurs livrables indépendants, vérifiables et fusionnables sans transformer le dépôt en zone de conflits.

Dernière mise à jour : 13 août 2026. Les commandes, les modes de parallélisation et les comportements liés aux worktrees ont été vérifiés dans la documentation officielle de Claude Code à cette date. Les paramètres peuvent évoluer ; une nouvelle vérification est nécessaire après une mise à jour importante de Claude Code.

Première étape : séparer le contexte de travail et les fichiers

Le premier problème vient d’une confusion entre l’isolation du contexte, l’isolation de la session et l’isolation du système de fichiers.

Un subagent est un agent spécialisé appelé depuis une session principale. Il peut explorer un dépôt, analyser des journaux, rechercher les tests associés à un composant ou proposer une stratégie de correction. Il renvoie ensuite un résultat à la session qui l’a lancé. Son contexte de conversation est séparé, mais cela ne signifie pas automatiquement qu’il travaille dans un répertoire différent.

Les agent teams coordonnent plusieurs sessions Claude Code indépendantes autour d’une liste de tâches et d’échanges entre agents. La documentation officielle les présente comme une fonction expérimentale, ce qui impose de les activer volontairement et de vérifier leur comportement avant de les intégrer à un processus de production. Documentation officielle des agents parallèles

Le worktree, en revanche, agit directement sur le répertoire de travail. Il permet à plusieurs branches d’exister dans des dossiers distincts, tout en partageant l’historique du même dépôt Git. Deux sessions placées dans deux worktrees ne modifient donc pas le même ensemble de fichiers local. Documentation officielle des worktrees dans Claude Code

La distinction opérationnelle est la suivante :

• recherche, lecture de logs ou cartographie du code : subagent ;
• modification indépendante de fichiers : session Claude Code dans un worktree ;
• coordination de plusieurs sessions autonomes : agent teams, après validation de leur statut expérimental ;
• modification d’un fichier ou d’une interface très partagée : agent propriétaire unique, les autres sessions restant en lecture ou attendant un contrat validé.

Un subagent peut disposer d’un contexte propre sans posséder de dossier propre. Un worktree peut isoler les fichiers sans résoudre les problèmes de communication entre agents. Ces deux mécanismes répondent donc à des risques différents.

Pourquoi plusieurs sessions peuvent-elles encore se gêner ?

L’utilisation de plusieurs worktrees réduit les écrasements directs, mais elle ne supprime pas les dépendances cachées. Deux agents peuvent travailler dans des dossiers distincts et produire des changements incompatibles.

Les zones à risque sont généralement :

• les interfaces publiques et les types partagés ;
• les migrations de base de données ;
• les fichiers de verrouillage des dépendances ;
• les schémas et fichiers de configuration ;
• le code généré ;
• les scripts de build et de déploiement ;
• les ports locaux et les bases de données de test ;
• les fichiers ignorés par Git qui contiennent la configuration de l’environnement.

Par exemple, un agent peut modifier un contrat d’API pendant qu’un second écrit les tests selon l’ancienne signature. Aucun fichier n’est écrasé, mais la fusion échoue ou produit une suite de tests incohérente. De la même manière, deux agents peuvent générer des fichiers différents à partir d’un même schéma, puis tenter de fusionner deux résultats qui ne correspondent plus à la même source.

Git worktree isole les arbres de travail, mais il partage l’historique, les objets Git et généralement le dépôt distant. Les branches restent donc nécessaires, tout comme une règle claire de fusion. La documentation Git décrit le fonctionnement des arbres de travail multiples et leurs contraintes de gestion. Référence officielle de git worktree

À retenir : l’isolation des fichiers empêche surtout les modifications simultanées dans le même répertoire. Elle ne décide pas quelle interface, quelle migration ou quelle implémentation doit devenir la référence.

Deuxième étape : choisir le mécanisme adapté à la tâche

Avant de démarrer plusieurs agents IA avec Claude Code, chaque tâche doit être classée selon son niveau de dépendance et son besoin d’écriture.

Utilisez un subagent pour les tâches d’analyse

Le subagent convient lorsque la session principale a besoin d’un résultat, mais pas d’une modification immédiate du dépôt. Il peut notamment :

• recenser les points d’entrée d’un service ;
• analyser les erreurs d’un journal ;
• rechercher les tests existants ;
• comparer deux implémentations ;
• identifier les dépendances d’un composant audio, vidéo ou de design ;
• proposer des critères d’acceptation.

La consigne doit fournir un objectif, une zone d’exploration et un format de sortie. Une instruction comme « analysez le dépôt et dites-moi ce qui ne va pas » pousse l’agent à parcourir trop de fichiers et à retourner une réponse difficile à exploiter.

Une consigne plus précise peut être formulée ainsi :

Analysez le module de traitement audio.

Examinez uniquement :
- src/audio ;
- tests/audio ;
- package.json.

Retournez :
1. les fichiers concernés ;
2. les dépendances externes ;
3. les tests déjà présents ;
4. trois risques de régression ;
5. les commandes de vérification proposées.

Ne modifiez aucun fichier.

Les subagents sont particulièrement utiles pour préserver le contexte de la session principale. Une recherche sur les logs, les formats pris en charge ou les chemins de code peut remplir rapidement la conversation sans contribuer directement à l’implémentation. Guide officiel des subagents Claude Code

Utilisez un worktree pour toute écriture concurrente

Dès que plusieurs sessions doivent modifier le code simultanément, chaque session doit disposer d’un répertoire de travail et d’une branche identifiables.

Une session peut être lancée avec :

claude --worktree fonctionnalite-a

Une autre session peut recevoir un worktree différent :

claude --worktree tests-fonctionnalite-a

Cette séparation évite qu’une session réécrive localement les fichiers modifiés par une autre. Elle permet aussi de supprimer une proposition sans remettre en cause le travail en cours dans les autres branches.

Le worktree ne doit toutefois pas être présenté comme une copie complète de l’ordinateur. Les fichiers ignorés par Git, les dépendances déjà installées, les services locaux, les certificats et les variables d’environnement peuvent manquer. L’environnement doit être préparé séparément.

Envisagez les agent teams pour la coordination

Les agent teams sont pertinentes lorsque plusieurs sessions doivent se transmettre des informations, suivre un plan commun et signaler leur état. Elles peuvent simplifier la supervision d’une tâche comportant plusieurs rôles : implémentation, tests, documentation et revue.

Elles ne remplacent ni les branches ni les worktrees. Si plusieurs coéquipiers écrivent dans le même répertoire, le risque de collision demeure. Elles ne remplacent pas non plus la validation humaine : la coordination des agents ne constitue pas une preuve que le résultat répond aux critères d’acceptation. Documentation officielle des agent teams

Décision rapide : quelle stratégie retenir ?

La liste suivante sert de décision opérationnelle avant le lancement :

• [ ] La tâche consiste uniquement à lire, chercher ou résumer ? Choisissez un subagent sans modification de fichier.
• [ ] La tâche doit créer ou modifier du code ? Attribuez-lui un worktree et une branche distincts.
• [ ] Deux tâches touchent-elles le même contrat, schéma ou fichier de configuration ? Désignez un agent propriétaire ou séquencez les changements.
• [ ] Les agents doivent-ils échanger directement autour d’un plan commun ? Envisagez les agent teams après vérification de leur statut et de leurs limites.
• [ ] Chaque worktree peut-il installer les dépendances et exécuter les tests ? Si ce n’est pas le cas, préparez d’abord l’environnement.
• [ ] Chaque agent peut-il retourner un résumé, les tests, les limites et un retour arrière ? Sinon, la tâche n’est pas suffisamment définie.
• [ ] La branche peut-elle être fusionnée sans reprendre une modification concurrente ? Si la réponse est non, réduisez le périmètre ou changez l’ordre des tâches.
• [ ] La machine peut-elle maintenir les builds et les sessions prévues ? Si elle devient instable ou si les agents restent inactifs, diminuez le parallélisme.

Si les deux premières conditions sont remplies mais que les tâches partagent une interface critique, il faut revenir à une exécution séquentielle sur cette interface. Le parallélisme doit être appliqué aux zones réellement indépendantes, pas à tout le projet par principe.

Troisième étape : découper les tâches pour faciliter la fusion

Un découpage efficace ne consiste pas à attribuer « la moitié du projet » à un agent. Chaque tâche doit posséder une frontière claire, une entrée connue, un livrable et une méthode de vérification.

Un découpage raisonnable peut attribuer :

• à l’agent A, l’implémentation d’un service dont l’interface est déjà définie ;
• à l’agent B, les tests unitaires de cette interface ;
• à l’agent C, la documentation et les exemples ;
• à l’agent D, l’analyse des journaux ou la revue des risques ;
• à la session principale, l’arbitrage des interfaces, les tests globaux et la fusion.

Les tâches qui touchent les mêmes fichiers doivent être traitées différemment. Trois options sont généralement possibles :

1. un agent devient propriétaire du fichier partagé ;
2. l’interface commune est modifiée en premier, puis les autres tâches démarrent sur cette base ;
3. un agent prépare une proposition sans l’appliquer, afin que la session principale sélectionne une solution.

Cette règle est essentielle pour les migrations, les fichiers de dépendances, les générateurs et les configurations de déploiement. Les agents secondaires peuvent consommer un contrat documenté, mais ne doivent pas le réinterpréter en parallèle.

Quatrième étape : rendre chaque environnement reproductible

Un worktree Claude Code est un nouvel arbre de travail, pas nécessairement une copie de l’environnement local. Les fichiers .env, les certificats et les paramètres ignorés par Git peuvent manquer dès la création de la branche.

Claude Code documente l’utilisation de fichiers permettant de recopier certains éléments ignorés par Git dans les worktrees. Cette fonction doit rester limitée aux paramètres non sensibles ou injectés de manière contrôlée. Les secrets ne doivent pas être ajoutés au dépôt, au worktree partagé ou à une image distante sans mécanisme de protection. Paramètres officiels de Claude Code

Chaque session devrait pouvoir exécuter un script d’initialisation reproductible comprenant :

• l’installation des dépendances ;
• la vérification de la version de Git ;
• l’installation du compilateur et des outils de test ;
• la préparation des dossiers temporaires ;
• la configuration de ports distincts ;
• l’injection contrôlée des variables d’environnement ;
• la vérification de l’accès aux services nécessaires.

Pour les projets audio, vidéo et design, il faut ajouter la vérification des codecs, des bibliothèques graphiques, des outils de rendu et des volumes de fichiers. Un agent peut déclarer une tâche terminée alors que le build fonctionne uniquement parce qu’un outil installé manuellement sur la machine principale est absent du worktree distant.

Sur un Mac distant, une image préconfigurée ou un script versionné réduit les différences entre sessions. Les ingénieurs qui préparent ce type d’environnement peuvent aussi consulter le centre d’aide de Zutcloud avant de choisir une méthode de connexion, de transfert de fichiers ou d’initialisation.

Cinquième étape : exiger une preuve de livraison

La déclaration « tâche terminée » ne suffit pas. Chaque branche doit fournir des éléments permettant à la session principale ou à un agent de revue de contrôler le résultat.

La consigne de fin peut imposer la structure suivante :

Retournez :
- un résumé des changements ;
- la liste des fichiers modifiés ;
- les commandes exécutées ;
- le résultat de chaque test ;
- les limites connues ;
- les risques de régression ;
- la méthode de retour arrière ;
- le hash du commit, si un commit a été créé.

La porte de validation commune doit vérifier, selon le projet :

• la compilation ou le contrôle des types ;
• les tests unitaires de la zone modifiée ;
• les tests d’intégration lorsque l’interface a changé ;
• le lint et le formatage ;
• l’absence de secret ajouté par erreur ;
• la cohérence des migrations ;
• la génération correcte des fichiers dérivés ;
• la différence entre la branche et sa base.

Une branche doit être évaluée dans un environnement aussi proche que possible de celui de la fusion. Un test réussi dans une session ne garantit pas qu’il réussira après l’ajout des changements d’un autre agent.

Sixième étape : fusionner dans l’ordre des dépendances

L’ordre d’arrivée des agents ne doit pas déterminer l’ordre de fusion. Une branche terminée plus tôt peut dépendre d’une interface qui n’est pas encore stabilisée.

L’ordre le plus sûr est souvent le suivant :

1. contrat, interface ou schéma partagé ;
2. implémentation principale ;
3. tests dépendants de cette implémentation ;
4. documentation et exemples ;
5. revue globale et nettoyage.

Après chaque fusion, les tests concernés doivent être relancés. Une branche testée seule peut échouer une fois intégrée parce qu’elle rencontre une nouvelle signature, une migration différente ou une configuration modifiée.

Lorsque deux agents proposent deux solutions concurrentes, il ne faut pas fusionner les deux pour récupérer « le meilleur de chaque ». Il faut comparer les critères d’acceptation : comportement attendu, couverture de tests, complexité, compatibilité avec l’architecture et facilité de retour arrière. Une seule solution devient la référence ; l’autre est abandonnée ou conservée comme historique.

Les commandes suivantes permettent de contrôler l’état du dépôt :

git worktree list
git status
git diff main...branche-agent
git log --oneline --decorate --graph --all

Après la fusion finale, les worktrees temporaires et les branches abandonnées doivent être supprimés. Un espace de travail conservé sans raison augmente le risque de reprendre une ancienne branche ou de croire qu’un agent est toujours actif.

Comment limiter les ressources et les sessions inutiles ?

Le parallélisme consomme davantage que la simple durée de génération de texte. Chaque session peut lancer un serveur de développement, installer des dépendances, compiler le projet, analyser des logs ou exécuter des tests. Plusieurs worktrees peuvent également dupliquer des fichiers volumineux et multiplier les caches.

Chaque tâche devrait donc définir :

• une condition d’arrêt ;
• un nombre maximal de nouvelles tentatives ;
• une durée maximale sans progrès ;
• un événement nécessitant une confirmation humaine ;
• une commande de nettoyage ;
• un résultat minimal acceptable.

Si un agent reste bloqué sur une dépendance partagée, il est généralement préférable de l’arrêter et de réviser le découpage plutôt que de multiplier les tentatives. La supervision doit également distinguer une session active d’un terminal simplement ouvert.

Pour des tâches ponctuelles, un Mac distant utilisé selon les besoins peut éviter de maintenir un poste supplémentaire allumé en permanence. Pour une charge continue, un environnement local ou administré à long terme peut être plus adapté. Le choix dépend surtout de la fréquence des builds, du nombre de sessions réellement actives et de la nécessité d’accéder à des périphériques physiques.

FAQ : les points souvent mal compris

Comment lancer plusieurs agents Claude Code en même temps sans perdre le contrôle du projet ?

Pour des recherches indépendantes, le terminal principal peut déléguer des subagents et récupérer des synthèses structurées. Pour plusieurs modifications de code, lancez des sessions distinctes avec claude --worktree nom-de-tache, puis attribuez à chaque branche un périmètre de fichiers clairement défini. Les agent teams ajoutent une coordination entre sessions, mais restent expérimentales et doivent être activées explicitement.

Quelle est la différence entre un subagent et un worktree dans Claude Code ?

Un subagent isole surtout le contexte de conversation : il explore, analyse ou exécute une tâche, puis renvoie un résultat à la session principale. Un worktree isole le répertoire de travail et la branche Git. Les deux mécanismes peuvent être combinés lorsqu’un agent doit modifier des fichiers sans perturber la session principale.

Comment éviter les conflits de fichiers avec plusieurs sessions Claude Code ?

La règle la plus sûre consiste à donner un worktree et une branche à chaque session qui écrit du code. Avant le lancement, identifiez les fichiers partagés, les contrats d’API, les migrations et les fichiers de verrouillage. Une seule session doit posséder chaque fichier à haut risque ; les autres consomment son interface ou attendent son résultat validé.

Un agent Claude Code peut-il travailler sur une branche différente des autres agents ?

Oui. Chaque worktree Claude Code peut être créé sur une branche distincte, tout en partageant l’historique et le dépôt distant du même projet. Les branches restent toutefois indépendantes jusqu’à la fusion. Il faut donc choisir un ordre d’intégration, lancer les tests après chaque fusion et supprimer proprement les worktrees devenus inutiles.

Quel environnement faut-il pour exécuter plusieurs sessions Claude Code à distance ?

L’environnement distant doit disposer de Git, de la chaîne de compilation du projet, des gestionnaires de dépendances et d’un mécanisme sûr pour injecter les variables nécessaires. Les fichiers secrets ne doivent pas être commités. Une image préconfigurée ou un script d’initialisation reproductible limite les différences entre sessions et facilite l’exécution sur un Mac distant.

Le choix du Mac distant dépend de la durée réelle des sessions

Un poste local reste préférable lorsque les agents travaillent régulièrement sur un projet, accèdent à des périphériques physiques ou doivent conserver un environnement de développement permanent. En revanche, une machine personnelle devient moins confortable lorsque plusieurs builds, tests et sessions Claude Code doivent rester actifs durant de longues périodes : elle doit rester allumée, conserver des ressources disponibles et absorber les pics de compilation sans interrompre le travail.

Dans ce cas, un Mac distant utilisé par période peut être plus cohérent qu’un poste acheté uniquement pour des tâches ponctuelles. Zutcloud propose des environnements de location de Mac mini qui peuvent servir à tester une organisation de travail distante. Il faut toutefois vérifier la durée prévue, la fréquence des builds, les besoins en stockage et l’accès aux périphériques avant de choisir.

Si le projet exige une charge stable et continue, l’achat d’un Mac ou une infrastructure administrée à long terme peut rester plus rationnel. Si les sessions sont occasionnelles, que le poste local manque de disponibilité ou que l’équipe doit ouvrir temporairement plusieurs environnements isolés, la location d’un Mac distant évite de conserver une machine inactive entre deux campagnes de développement.

FAQ

Comment lancer plusieurs agents Claude Code en même temps sans perdre le contrôle du projet ?

Pour des recherches indépendantes, le terminal principal peut déléguer des subagents et récupérer des synthèses structurées. Pour plusieurs modifications de code, lancez des sessions distinctes avec claude --worktree nom-de-tache, puis attribuez à chaque branche un périmètre de fichiers clairement défini. Les agent teams ajoutent une coordination entre sessions, mais restent expérimentales et doivent être activées explicitement.

Quelle est la différence entre un subagent et un worktree dans Claude Code ?

Un subagent isole surtout le contexte de conversation : il explore, analyse ou exécute une tâche, puis renvoie un résultat à la session principale. Un worktree isole le répertoire de travail et la branche Git. Les deux mécanismes peuvent être combinés lorsqu’un agent doit modifier des fichiers sans perturber la session principale.

Comment éviter les conflits de fichiers avec plusieurs sessions Claude Code ?

La règle la plus sûre consiste à donner un worktree et une branche à chaque session qui écrit du code. Avant le lancement, identifiez les fichiers partagés, les contrats d’API, les migrations et les fichiers de verrouillage. Une seule session doit posséder chaque fichier à haut risque ; les autres consomment son interface ou attendent son résultat validé.

Un agent Claude Code peut-il travailler sur une branche différente des autres agents ?

Oui. Chaque worktree Claude Code peut être créé sur une branche distincte, tout en partageant l’historique et le dépôt distant du même projet. Les branches restent toutefois indépendantes jusqu’à la fusion. Il faut donc choisir un ordre d’intégration, lancer les tests après chaque fusion et supprimer proprement les worktrees devenus inutiles.

Quel environnement faut-il pour exécuter plusieurs sessions Claude Code à distance ?

L’environnement distant doit disposer de Git, de la chaîne de compilation du projet, des gestionnaires de dépendances et d’un mécanisme sûr pour injecter les variables nécessaires. Les fichiers secrets ne doivent pas être commités. Une image préconfigurée ou un script d’initialisation reproductible limite les différences entre sessions et facilite l’exécution sur un Mac distant.