Guide du Parallel AI Coding : coder à plusieurs

La documentation de l’API de Cursor indique qu’elle peut gérer jusqu’à 256 agents actifs par clé d’API, mais cette capacité ne signifie pas que votre projet gagnera automatiquement en vitesse. (docs.cursor.com)

Symptôme : plusieurs agents écrivent en même temps, mais les conflits, les reprises et les revues absorbent le temps gagné.
Solution la plus rapide : commencez par cartographier les dépendances, imposez un contrat de tâche à chaque AI Coding Agent, isolez les branches avec un Git worktree ou un environnement distant, puis refusez toute fusion qui n’a pas franchi les mêmes contrôles automatisés.

Ce guide du Parallel AI Coding s’adresse aux développeurs indépendants qui passent d’un agent unique à plusieurs agents, aux petites équipes qui veulent raccourcir un cycle de livraison et aux ingénieurs de plateforme qui doivent dimensionner des environnements parallèles.

Le parallélisme commence par une décision de dépendance

Ouvrir plusieurs terminaux n’est pas encore une architecture de développement parallèle. La première question n’est pas « combien d’agents pouvez-vous lancer ? », mais « quelles tâches peuvent avancer sans attendre une modification concurrente ? ».

Prenez votre prochaine fonctionnalité et dessinez quatre catégories :

• les modules indépendants, qui peuvent être modifiés sans attendre une autre branche ;
• les interfaces partagées, comme les types, schémas, contrats d’API ou événements ;
• les fichiers à forte collision, comme les routes centrales, les fichiers de configuration ou les points d’entrée ;
• les tâches de validation, qui doivent observer le résultat des autres branches.

Un projet se prête bien au Parallel AI Coding lorsque vous pouvez produire plusieurs lots avec des entrées et sorties explicites. Par exemple, pour une application audio ou vidéo, un agent peut préparer l’import et la normalisation des médias, un autre construire l’interface de prévisualisation, tandis qu’un troisième écrit les tests de formats et les scripts de validation. En revanche, si les trois agents doivent modifier le même pipeline de rendu, le parallélisme est artificiel.

Les limites à détecter avant le lancement

Vous devez interrompre le découpage et repasser en séquence dans au moins quatre situations :

• le modèle de données n’est pas stabilisé ;
• plusieurs tâches nécessitent une modification du même fichier central ;
• les critères d’acceptation sont encore discutés ;
• l’environnement local ne permet pas de reproduire les tests de manière identique.

Un agent qui attend constamment un autre agent n’est pas un agent parallèle : c’est une file d’attente supplémentaire, avec davantage de contexte à synchroniser.

Le coût caché ne vient pas uniquement des conflits Git. Il inclut aussi les installations répétées, les ports occupés, les caches incohérents, les secrets exposés, les résultats de test impossibles à comparer et la revue humaine de sorties redondantes. Le nombre d’agents doit donc rester inférieur au nombre de lots réellement indépendants.

Première étape : rédiger le contrat de chaque agent

Avant de créer un espace de travail, rédigez une fiche courte pour chaque tâche. Cette fiche doit être versionnée dans le dépôt ou attachée à un ticket, afin que les agents et les humains consultent la même référence.

Votre contrat doit contenir :

• Objectif : le résultat attendu, formulé avec un verbe vérifiable ;
• Périmètre autorisé : les fichiers ou répertoires que l’agent peut modifier ;
• Zone interdite : les fichiers centraux qu’il doit seulement lire ;
• Entrées : branche de départ, interface disponible, données de test ou décision technique ;
• Sorties : commit, fichier de documentation, test ou artefact produit ;
• Commandes de validation : commandes exactes à exécuter ;
• Définition de terminé : conditions qui autorisent la revue ou la transmission ;
• Procédure de blocage : information à consigner si une dépendance manque.

Évitez les consignes comme « améliorez le système d’authentification ». Préférez : « ajoutez la validation du jeton dans src/auth/validator, sans modifier le schéma utilisateur, puis fournissez les tests couvrant les jetons expirés et malformés ».

Cette précision répond à un problème souvent sous-estimé : deux agents peuvent interpréter la même demande avec des hypothèses différentes. L’un peut privilégier une modification minimale, l’autre réorganiser tout le module. Sans contrat partagé, vous ne comparez pas deux implémentations ; vous comparez deux projets différents.

Rappel : une consigne d’agent n’est pas un historique de projet. Conservez l’état, les décisions, les blocages et les artefacts dans le dépôt, le système de tickets ou un journal partagé, plutôt que dans une seule conversation.

Deuxième étape : créer des espaces isolés dès la première heure

Le mécanisme git worktree permet d’associer plusieurs répertoires de travail à un même dépôt et de conserver une branche distincte pour chacun. La documentation officielle de Git fournit notamment les commandes add, list, lock, move, remove et prune. (git-scm.com)

Un démarrage minimal peut ressembler à ceci :

git fetch origin
git switch main
git pull --ff-only

git worktree add ../projet-api -b agent/api origin/main
git worktree add ../projet-interface -b agent/interface origin/main
git worktree add ../projet-tests -b agent/tests origin/main

git worktree list

Chaque agent reçoit ensuite un chemin différent. Il ne travaille pas dans le répertoire principal et ne doit pas changer de branche dans un espace déjà attribué à un autre processus.

L’isolation Git ne règle cependant pas tout. Préparez également :

• un fichier de configuration propre à chaque espace ;
• des ports différents pour les serveurs locaux ;
• des caches identifiables ;
• une commande d’installation reproductible ;
• un jeu de variables d’environnement minimal ;
• une politique claire pour les accès réseau et les secrets.

Les secrets ne doivent pas être copiés dans des fichiers accessibles à un agent qui n’en a pas besoin. Pour un agent distant, vérifiez aussi le stockage des identifiants, l’accès au dépôt, la conservation des journaux et les commandes exécutées automatiquement.

Les outils ne présentent pas tous le même modèle. Claude Code indique par exemple des exigences d’exécution incluant macOS 10.15 ou une distribution Linux compatible, 4 Go de mémoire vive et Node.js 18 ou ultérieur dans sa documentation de configuration. (docs.anthropic.com) Cela décrit son environnement de base, pas une capacité garantie à faire fonctionner plusieurs sessions lourdes sans saturation.

Cursor Background Agents exécutent les agents dans des machines Ubuntu isolées, avec une configuration d’environnement pouvant être conservée dans .cursor/environment.json. La documentation précise également que les agents clonés depuis GitHub travaillent sur une branche séparée. (docs.cursor.com)

OpenHands documente pour sa part un fonctionnement dans un conteneur Docker isolé du système hôte. Cette séparation limite les effets directs sur la machine principale, mais elle ne dispense pas de contrôler les permissions réseau, les volumes montés et les secrets injectés. (docs.openhands.dev)

Troisième étape : lancer uniquement les lots réellement indépendants

Une fois les worktrees prêts, attribuez à chaque agent une mission et un état. Un journal simple peut suivre les valeurs suivantes :

• à préparer ;
• en cours ;
• bloqué par une dépendance ;
• en validation ;
• prêt pour revue ;
• rejeté ;
• fusionné.

L’objectif n’est pas de surveiller chaque phrase produite par l’agent. Vous devez plutôt savoir où se trouve son code, quelle commande a été lancée, quel résultat a été obtenu et quelle décision est attendue.

Pour une équipe qui développe un outil créatif, le découpage peut suivre cette logique :

• l’agent A définit l’interface d’import des fichiers audio et vidéo ;
• l’agent B implémente un adaptateur de format sans toucher à l’interface ;
• l’agent C prépare les tests et les fichiers d’exemple ;
• l’agent D vérifie l’ergonomie de la prévisualisation et documente les cas limites.

L’agent B ne doit démarrer que si l’interface de A est suffisamment stable. Si elle change encore, vous devez arrêter B, mettre à jour le contrat et relancer sa branche depuis une base cohérente.

Les outils orientés worktree peuvent faciliter cette organisation. La documentation d’Orca décrit un cycle de création, travail, revue, envoi de la branche puis archivage du worktree. Elle précise également qu’un worktree possède sa propre branche, ses fichiers sur disque et ses terminaux d’agent. (onorca.dev)

Le même principe peut être déporté sur une machine distante lorsque le poste local manque de mémoire, de stockage ou de ports disponibles. La documentation SSH d’Orca décrit un scénario où le worktree et l’agent s’exécutent sur l’hôte distant tandis que l’édition et la revue restent accessibles depuis le poste local. (onorca.dev)

Quatrième étape : organiser la transmission des résultats

Un agent ne doit pas transmettre uniquement « c’est terminé ». Il doit remettre un paquet de travail vérifiable :

1. le nom de la branche ;
2. le commit ou la série de commits ;
3. la liste des fichiers modifiés ;
4. les commandes exécutées ;
5. les résultats de ces commandes ;
6. les choix techniques qui influencent les autres tâches ;
7. les limitations connues ;
8. l’emplacement des captures, journaux ou fichiers générés.

Cette méthode évite de transformer la fenêtre de discussion en système de suivi. Elle est particulièrement importante lorsque plusieurs agents travaillent sur une interface visuelle, un montage de médias ou un prototype de design : une capture d’écran, un fichier audio de test ou une vidéo de démonstration peut être aussi important que le diff lui-même.

Les dépendances doivent circuler par artefacts explicites. Par exemple, l’agent qui définit un schéma publie un fichier de référence et une note de compatibilité. L’agent qui implémente le client consomme cette version précise. Si le schéma change, la tâche du client devient « à mettre à jour », et non « continuer comme si de rien n’était ».

Cinquième étape : imposer une porte d’acceptation commune

Avant toute fusion, exécutez la même séquence pour chaque branche. Adaptez les commandes à votre projet, mais gardez une structure constante :

npm ci
npm run lint
npm test
npm run build

Pour un projet Python, cela pourrait être :

python -m pip install -r requirements.txt
ruff check .
pytest
python -m build

Ajoutez une analyse de sécurité ou une vérification des dépendances si votre application traite des données sensibles, des paiements, des comptes utilisateurs ou des fichiers importés.

La porte d’acceptation doit contrôler cinq éléments :

• le code compile ou se construit ;
• les tests existants passent ;
• les nouveaux tests couvrent la modification ;
• les fichiers interdits n’ont pas été modifiés ;
• la branche respecte le contrat de tâche.

Le contrôle du périmètre est essentiel. Un agent peut produire un résultat fonctionnel tout en modifiant une configuration globale, une dépendance ou une règle de déploiement qui n’était pas dans sa mission.

Ne fusionnez pas une branche parce que son agent affirme avoir lancé les tests. Conservez la sortie des commandes dans le système de CI ou dans un artefact de revue. La validation doit être reproductible par une autre personne, sur un environnement identique ou suffisamment proche.

Sixième étape : fusionner selon les dépendances, pas selon l’ordre d’arrivée

La fusion doit suivre la structure technique du projet. Commencez par les contrats et les modules de base, puis mettez à jour les branches qui en dépendent.

Un ordre fréquent est le suivant :

1. interfaces, types et schémas ;
2. bibliothèques communes ;
3. services ou adaptateurs ;
4. interfaces utilisateur ;
5. tests d’intégration ;
6. documentation et exemples.

Après la fusion d’un socle partagé, les autres branches doivent être rebasées ou recréées à partir de la nouvelle base, puis repasser par les contrôles. Une branche validée contre l’ancien contrat n’est plus automatiquement valide après l’évolution de l’interface.

Lorsque plusieurs agents proposent des implémentations concurrentes, ne choisissez pas simplement le diff le plus volumineux. Évaluez chaque proposition selon des critères écrits :

• respect du contrat ;
• couverture de test ;
• simplicité de maintenance ;
• compatibilité avec l’architecture ;
• impact sur les performances ;
• exposition de sécurité ;
• qualité de la documentation.

Cette grille est utile pour les choix de design, d’interface audio/vidéo ou de présentation visuelle, où la solution la plus longue n’est pas nécessairement la plus claire pour l’utilisateur final.

La checklist de lancement et de fusion

Utilisez cette liste avant de laisser plusieurs agents travailler seuls :

• [ ] Les dépendances entre modules ont été dessinées.
• [ ] Les fichiers à forte collision ont un propriétaire explicite.
• [ ] Chaque tâche possède une définition de terminé.
• [ ] Les branches partent d’une base connue et documentée.
• [ ] Chaque agent dispose d’un Git worktree, conteneur ou environnement distant distinct.
• [ ] Les ports, caches et variables d’environnement sont séparés.
• [ ] Aucun secret inutile n’est copié dans l’espace de travail.
• [ ] Les commandes de test sont écrites avant le lancement.
• [ ] Les états et blocages sont enregistrés hors des conversations.
• [ ] Chaque branche est contrôlée avant revue.
• [ ] Les interfaces de base sont fusionnées avant les implémentations dépendantes.
• [ ] Les branches restantes sont resynchronisées après une fusion structurante.
• [ ] Une personne peut expliquer pourquoi chaque agent était nécessaire.

Si vous ne pouvez pas cocher les points relatifs à l’isolation ou à l’acceptation, n’augmentez pas le nombre d’agents. Corrigez d’abord le dispositif.

Quand faut-il réduire le nombre d’agents ?

Le Parallel AI Coding devient souvent plus lent dans les projets fortement couplés. Les signaux sont faciles à observer :

• les agents attendent fréquemment un fichier ou une décision ;
• les mêmes conflits reviennent après chaque rebase ;
• la revue humaine devient plus longue que l’implémentation ;
• les branches produisent des tests incompatibles ;
• l’environnement doit être réinstallé à chaque tentative ;
• les agents modifient des zones hors contrat ;
• les échecs proviennent de la configuration plutôt que du code.

Dans ce cas, réduisez le parallélisme et stabilisez la base. Un seul agent peut d’abord créer une interface claire, une suite de tests et une configuration reproductible. Plusieurs agents pourront ensuite traiter les lots périphériques avec moins de coordination.

La première semaine, mesurez surtout les temps d’attente, les conflits, les rejets de validation, les reprises et le temps de revue. Ne cherchez pas une promesse de gain linéaire : le résultat dépend de la structure du dépôt et de la qualité des portes de contrôle.

Questions fréquentes

Comment empêcher plusieurs AI Coding Agent de modifier le même fichier ?

Attribuez à chaque agent un périmètre de fichiers explicitement écrit dans son contrat de tâche. Les fichiers partagés, comme les schémas centraux, les configurations communes ou les points d’entrée, doivent appartenir à un seul agent ou être traités dans une phase séquentielle. Un Git worktree évite les écrasements directs, mais il ne supprime pas les conflits lors de la fusion.

Comment découper correctement une tâche pour le Parallel AI Coding ?

Découpez le travail autour de résultats vérifiables plutôt qu’autour de rôles vagues. Un agent peut produire une interface documentée, un autre une implémentation isolée, un troisième des tests ou une documentation. Chaque lot doit préciser ses entrées, ses sorties, les chemins modifiables, la commande de test et la condition qui autorise la transmission au lot suivant.

Chaque agent doit-il disposer de son propre environnement de développement ?

Oui dès que les agents exécutent des commandes, installent des dépendances ou modifient des fichiers simultanément. L’isolation peut prendre la forme d’un Git worktree avec configuration séparée, d’un conteneur, d’une machine virtuelle ou d’un espace distant. Un simple terminal supplémentaire ne suffit pas à isoler les processus, les variables d’environnement, les ports et les secrets.

Comment vérifier le code produit par plusieurs agents ?

Utilisez une porte d’acceptation identique pour toutes les branches : tests unitaires, analyse statique, compilation, tests d’intégration et contrôle de sécurité lorsque le projet le justifie. Ajoutez une vérification du périmètre modifié et une revue humaine des interfaces. Le statut « terminé » déclaré par un agent ne doit jamais remplacer les résultats reproductibles des commandes.

Quand le Parallel AI Coding devient-il plus lent qu’un agent unique ?

Le parallélisme devient contre-productif lorsque les tâches dépendent du même fichier, lorsque les interfaces changent encore ou lorsque le temps de démarrage, de synchronisation et de revue dépasse le travail réellement produit. Il ralentit aussi les petits correctifs et les migrations fortement couplées. Dans ces cas, stabilisez d’abord la base en mode séquentiel, puis ouvrez seulement les lots indépendants.

Choisir ensuite l’environnement qui correspond à votre charge

Après avoir construit votre graphe de dépendances, vous pouvez choisir rationnellement entre trois options. Le poste local convient lorsque les tâches sont courtes, peu nombreuses et proches de votre environnement quotidien. Une machine distante est préférable lorsque les agents doivent rester actifs, exécuter des builds longs ou être accessibles par plusieurs membres de l’équipe. Une location temporaire de Mac devient intéressante lorsque vous devez tester un environnement Apple réel, lancer un projet créatif ou valider une chaîne audio, vidéo ou mobile sans acheter immédiatement une nouvelle machine.

Acheter un Mac très puissant avant de connaître votre niveau réel de concurrence peut immobiliser du budget tout en laissant les problèmes de coordination inchangés. À l’inverse, un environnement local mal isolé entraîne des conflits de ports, des installations répétées et une supervision difficile. Si vous devez seulement valider une architecture parallèle ou exécuter un projet pendant une période limitée, la location d’un Mac distant pour le développement peut offrir un cadre plus prévisible. Pour comparer les conditions d’accès et les limites avant de choisir, consultez également les informations générales de Kvmzen.

Le bon ordre de décision est donc simple : cartographiez d’abord les tâches, estimez les dépendances et les durées d’exécution, puis choisissez entre local, location temporaire ou environnement distant permanent. Ne commencez pas par acheter du matériel ; commencez par prouver que votre projet possède assez de travail indépendant pour justifier plusieurs AI Coding Agent.

Questions fréquentes