# Sous-agents et travail parallèle dans Claude Code : comment exécuter plusieurs tâches simultanément > Guide complet sur la parallélisation des tâches dans Claude Code : architecture des sous-agents, contexte partagé et isolé, modèles Fan-Out et Swarm, utilisation via CLI avec le flag -p et optimisation des tokens. ## 1. Qu'est-ce que les sous-agents dans Claude Code : du raisonnement séquentiel au parallèle Une session de travail standard de **Claude Code** fonctionne en mode strictement séquentiel (boucle d'événements mono-thread). L'utilisateur envoie une requête, l'agent lit le contexte, effectue une recherche, édite un fichier, lance un linter ou des tests, et ne passe à la tâche suivante qu'après avoir terminé toute la chaîne. Lorsque le projet prend de l'ampleur et que le développeur est confronté à des dizaines de tâches mutuellement indépendantes, cette approche séquentielle entraîne des retards injustifiés et un encombrement rapide de la fenêtre de contexte. Pour surmonter cette limitation, la concept de **sous-agents** a été intégré à l'architecture de Claude Code — des instances de modèle isolées et autonomes auxquelles sont délégués des fragments indépendants de la tâche globale. ```mermaid flowchart TD subgraph Sequential ["Послідовний режим (Single Session)"] S1["Завдання 1"] --> S2["Завдання 2"] --> S3["Завдання 3"] --> S4["Фінальний результат"] end subgraph Parallel ["Паралельний режим (Subagent Orchestration)"] P_Parent["Батьківська сесія Claude Code"] --> P1["Субагент 1: Auth"] P_Parent --> P2["Субагент 2: Validation"] P_Parent --> P3["Субагент 3: Formatting"] P1 --> P_Join{"Агрегація результатів"} P2 --> P_Join P3 --> P_Join P_Join --> P_Done["Готовий pull request / звіт"] end ``` ### Caractéristiques clés d'un sous-agent autonome - **Fenêtre de contexte propre et isolée :** Le sous-agent n'est pas surchargé par l'historique long de la session principale, se concentrant exclusivement sur la tâche qui lui est confiée. - **Accès partagé au système de fichiers :** Le sous-agent peut lire la structure des répertoires, les configurations du projet et les fichiers de code source avec les mêmes droits que le processus principal. - **Exécution asynchrone :** Plusieurs sous-agents travaillent simultanément, réduisant le temps total d'exécution (*wall-clock time*) proportionnellement au nombre de flux parallèles. - **Agrégation automatique :** Après avoir terminé son travail, le sous-agent génère un résumé structuré, le renvoie à la session parente et libère les ressources allouées. > [!NOTE] > Le modèle mental le plus simple pour comprendre les sous-agents est celui d'une gestion efficace du développement. Au lieu qu'un ingénieur Senior écrive lui-même, l'un après l'autre, la documentation pour cinq microservices, il crée 5 tâches distinctes et les confie à des exécutants parallèles, ne vérifiant que le résultat final de chacun. --- ## 2. Critères de parallélisation : quand diviser les tâches et quand travailler séquentiellement La parallélisation n'est pas une panacée universelle. Son efficacité dépend directement du degré d'indépendance mutuelle des tâches. Tenter d'exécuter en parallèle des étapes interdépendantes provoque inévitablement des *race conditions* (conditions de course) et des collisions logiques. | Scénario de développement | Mode optimal | Justification du choix | | :--- | :---: | :--- | | **Génération de tests unitaires pour différentes utilitaires** | Parallèle | Les modules ne dépendent pas les uns des autres, aucune dépendance partagée | | **Audit multi-vectoriel de sécurité, SEO et UI** | Parallèle | Chaque direction analyse le système sous un angle différent, en lecture seule uniquement | | **Conception du schéma DB et génération des migrations** | Séquentiel | Il est impossible d'écrire la migration avant la finalisation du modèle de base de données | | **Édition du même fichier de configuration** | Séquentiel | Une écriture simultanée par plusieurs agents cause des conflits de fusion | | **Refactoring par lots de composants indépendants** | Parallèle | Chaque composant se trouve dans un fichier séparé sans import croisé | ### Quand la parallélisation est contre-indiquée 1. **Dépendance en cascade des résultats :** Si l'étape B utilise les données de sortie de l'étape A. Par exemple : effectuer d'abord un audit du schéma de base de données, concevoir une nouvelle structure, puis seulement ensuite générer la migration Prisma. 2. **Points communs de modification de fichiers :** Si l'Agent 1 et l'Agent 2 tentent simultanément d'apporter des modifications au même fichier `app.ts` ou `package.json`, l'une des écritures sera écrasée ou corrompue. 3. **Tâches nécessitant un feedback humain itératif :** Si les exigences ne sont pas définitivement fixées et que le développeur doit constamment ajuster la trajectoire via des questions de clarification, la tâche doit rester dans une session interactive unique. > [!WARNING] > Règle d'or de la parallélisation : avant de lancer un pool d'agents, donnez une réponse claire à la question : **« Chaque agent peut-il accomplir sa tâche du début à la fin sans attendre les réponses intermédiaires des autres ? »**. Si la réponse est « non » — travaillez exclusivement en séquentiel. --- ## 3. Architecture et mécanique de lancement des sous-agents via Task Tool Au sein du moteur Claude Code, l'orchestration des sous-agents s'effectue via l'outil système **Task tool**. Lorsque le modèle dans la session principale comprend que la tâche se compose de composants isolés, il initie des processus enfants en arrière-plan. L'utilisateur n'a généralement pas besoin d'appeler manuellement les instructions JSON système du Task tool — il suffit de formuler clairement la décomposition dans la requête ou de laisser Claude Code décomposer la tâche lui-même. ![Architecture de lancement des sous-agents Claude Code et agrégation des résultats dans la session principale](/api/guides-media/ai_agents/claude-code-subagents-and-parallel-work/images/claude-code-subagents-and-parallel-work-step-01.webp) ### Cycle de vie de l'exécution parallèle 1. **Dispatch de la tâche :** La session principale reçoit un prompt complexe (par exemple, écrire des tests pour cinq utilitaires : `auth.ts`, `validation.ts`, `formatting.ts`, `api-client.ts`, `cache.ts`). 2. **Formation des contextes enfants :** Des sous-agents distincts sont créés, chacun recevant une tâche personnalisée et le chemin vers le fichier cible. 3. **Travail autonome :** Chaque agent lit en parallèle le code source de son module, explore les types de données, génère la suite de tests correspondante et vérifie son exécution. 4. **Merge inverse (Aggregation) :** La session principale attend la fin de tous les flux, reçoit les statuts finaux d'exécution et présente au développeur un rapport consolidé. --- ## 4. Contexte partagé vs isolé : ce que voient les sous-agents L'erreur la plus fréquente chez les développeurs débutants est de supposer que les sous-agents ont un lien télépathique entre eux ou qu'ils connaissent tout ce qui a été discuté à l'étape 50 du dialogue principal. En réalité, le modèle suit une politique stricte de séparation de la mémoire. ![Contexte partagé et isolé des sous-agents : ce qui est accessible à tous les agents, et ce qui reste privé](/api/guides-media/ai_agents/claude-code-subagents-and-parallel-work/images/claude-code-subagents-and-parallel-work-extra-02.webp) | Ressource ou état du système | Partagé pour tous les agents ? | Description technique de l'accès | | :--- | :---: | :--- | | **Fichiers du projet sur disque** | **Oui** | Tous les agents ont accès en lecture et écriture au répertoire de travail | | **Règles CLAUDE.md** | **Oui** | Chaque agent est automatiquement initialisé avec les règles du projet et de la stack | | **Historique du dialogue précédent** | **Non** | Fenêtre isolée ; le sous-agent ne voit que son propre prompt direct | | **Modifications dans les fichiers ouverts** | **Prudence requise** | Aucun mécanisme d'auto-verrouillage de fichier ; risque de collision lors de l'écriture | ### Assurer la sécurité de l'écriture de fichiers (Write Ownership) Pour éviter la corruption de la base de code lors d'un travail parallèle, respectez le principe du **propriétaire unique du fichier** : ```text Répartition correcte des zones de responsabilité : Sous-agent 1 ──► src/utils/auth.test.ts (crée un nouveau fichier de test) Sous-agent 2 ──► src/utils/validation.test.ts (crée un nouveau fichier de test) Sous-agent 3 ──► src/utils/formatting.test.ts (crée un nouveau fichier de test) Répartition inacceptable (conflit) : Sous-agent 1 ──► src/index.ts (modifie la ligne d'export) Sous-agent 2 ──► src/index.ts (modifie la ligne d'export) Sous-agent 3 ──► src/index.ts (modifie la ligne d'export) ``` > [!IMPORTANT] > Si plusieurs agents parallèles doivent enregistrer les modules créés dans un fichier index unique (`src/index.ts` ou `src/routes.ts`), **ne leur déléguez pas** cette tâche. Que les agents créent uniquement leurs fichiers isolés, et laissez la session parente effectuer l'enregistrement des imports dans le fichier index après le retour de tous les résultats. --- ## 5. Patterns de formulation de prompts pour lancer des agents parallèles Bien que Claude Code dispose d'heuristiques pour détecter les tâches parallèles, une indication explicite de l'exécution simultanée élimine toute ambiguïté et optimise le temps de dispatch. ### Exemples de formulation efficace de requêtes :::tabs @tab Répartition de base ```markdown Exécute les trois tâches suivantes en parallèle via des sous-agents distincts : 1. Implémente la validation des champs dans le composant du formulaire d'inscription (src/components/RegisterForm.tsx). 2. Crée un composant de squelette de chargement pour le tableau de bord (src/components/DashboardSkeleton.tsx). 3. Ajoute la prise en charge de la pagination dans le hook de chargement des utilisateurs (src/hooks/useUsers.ts). Assure-toi que chaque agent travaille uniquement sur son fichier et ne modifie pas les configurations partagées. ``` @tab Analyse Fan-Out ```markdown Travaille en parallèle via des sous-agents : - Agent 1 : Étudie la documentation officielle de l'API Stripe concernant le traitement des événements webhook liés aux abonnements. - Agent 2 : Analyse notre implémentation actuelle dans le module src/services/billing.ts pour identifier les vulnérabilités. - Agent 3 : Conçois les interfaces TypeScript pour les nouveaux objets DTO d'entrée dans src/types/stripe.ts. Une fois terminé, synthétise les résultats dans un plan de refactoring unique dans la session principale. ``` @tab Audit par lots ```markdown Effectuez un audit parallèle de la base de code selon quatre axes : - Axe A (Sécurité) : Analyse des fuites de secrets dans l’historique Git et vérification de la sécurité des requêtes à la base de données. - Axe B (Performance) : Détection des problèmes N+1 requêtes dans les contrôleurs et identification des imports lourds dans les bundles côté client. - Axe C (Typage) : Vérification de la présence de types « any » dangereux et de champs obligatoires manquants dans les interfaces. - Axe D (Accessibilité) : Audit de la présence des attributs aria-label et du contraste des couleurs dans les classes Tailwind. ``` ::: --- ## 6. Quatre schémas clés de travail parallèle : patterns prêts à l'emploi L'expérience pratique de l'automatisation d'équipe avec Claude Code a permis de cristalliser quatre patterns architecturaux hautement efficaces d'orchestration parallèle. ```mermaid flowchart LR subgraph P1 ["1. Research Fan-Out"] RF_Q["Архітектурне питання"] --> RF1["PostgreSQL"] RF_Q --> RF2["MongoDB"] RF_Q --> RF3["SQLite"] RF1 & RF2 & RF3 --> RF_M["Порівняльна матриця"] end subgraph P2 ["2. Audit Swarm"] AS_Code["Репозиторій"] --> AS1["Security"] AS_Code --> AS2["Performance"] AS_Code --> AS3["A11y"] AS_Code --> AS4["Code Quality"] AS1 & AS2 & AS3 & AS4 --> AS_R["Загальний аудит-звіт"] end ``` ### Research Fan-Out (Recherche parallèle) Utilisé lorsqu'il est nécessaire d'analyser simultanément plusieurs bibliothèques alternatives, technologies ou approches architecturales pour prendre une décision technique. Chaque agent étudie une stack spécifique selon des critères standardisés (avantages, inconvénients, compatibilité de licence, taille du bundle), après quoi la session principale synthétise une matrice comparative. ### Audit Swarm (Audit multidisciplinaire) L'un des patterns les plus économes en ressources en termes de gain de temps. Au lieu qu'un seul agent lise tout le dépôt quatre fois consécutives pour différents contrôles, quatre agents spécialisés sont lancés simultanément. Comme l'audit s'effectue exclusivement en mode lecture seule (*read-only*), le risque de conflit d'écriture de fichier est totalement absent. ### Batch Processor (Refactoring par lots) Appliqué lors de migrations à grande échelle où une transformation identique doit être effectuée sur un grand ensemble de fichiers indépendants : - Conversion des anciens composants React class en hooks fonctionnels dans le répertoire `src/components/`. - Réécriture des tests de Jest vers Vitest. - Mise à jour des imports des anciennes utilitaires après leur extraction dans un monorepo. ### Feature Sprint (Développement parallèle de features indépendantes) Développement simultané de plusieurs modules UI ou endpoints API autonomes. Par exemple : - Agent 1 implémente le toggle de thème sombre (`ThemeToggle.tsx` + contexte associé). - Agent 2 développe le formulaire de recherche globale (`SearchBar.tsx` + hook de recherche). - Agent 3 crée le menu déroulant de notifications (`NotificationsDropdown.tsx`). --- ## 7. Lancement parallèle via CLI : mode Headless et flag -p Outre la session interactive de Claude Code, il existe un outil puissant d'automatisation système : le lancement de Claude en **mode headless (non interactif)** à l'aide du flag `-p` (`--print`). Dans ce mode, l'agent reçoit le prompt comme argument de ligne de commande, exécute la tâche dans un processus terminal isolé et imprime le résultat. Cela ouvre la possibilité d'utiliser les capacités natives d'exécution en arrière-plan des shells Unix-like (`&`) et l'utilitaire de synchronisation `wait`. ```bash # Одночасний запуск трьох фонових процесів Claude Code у bash/zsh claude -p "Write unit tests for src/utils/auth.ts using Vitest" & PID_AUTH=$! claude -p "Write unit tests for src/utils/validation.ts using Vitest" & PID_VAL=$! claude -p "Write unit tests for src/utils/formatting.ts using Vitest" & PID_FMT=$! # Очікуємо завершення всіх паралельних фонових завдань echo "Запущено фонові агенти з PID: $PID_AUTH, $PID_VAL, $PID_FMT. Очікування..." wait $PID_AUTH $PID_VAL $PID_FMT echo "Всі тести згенеровано успішно! Запуск перевірки..." npm test ``` ### Avantages de la parallélisation CLI - **Supervision humaine nulle :** Idéal pour les scripts CI/CD nocturnes, la préparation de suites de tests ou la pré-génération de documentation. - **Isolation OS réelle :** Chaque processus `claude` s'exécute dans un espace d'adressage distinct de l'OS. - **Logging dans des fichiers :** La sortie de chaque processus peut être facilement redirigée vers son propre fichier log : `claude -p "..." > logs/auth.log 2>&1 &`. > [!TIP] > Dans le terminal, l'opérateur `&` à la fin de la commande place le processus en arrière-plan, libérant le terminal pour lancer immédiatement la commande suivante. La commande intégrée `wait` bloque l'exécution du script jusqu'à ce que tous les PID en arrière-plan spécifiés aient terminé leur travail en retournant un code de sortie. --- ## 8. Économie de tokens, limites API et optimisation des coûts Le travail parallèle économise radicalement le temps de l'ingénieur, mais exige un contrôle financier rigoureux. Chaque sous-agent crée sa propre fenêtre de contexte, donc le lancement parallèle de $N$ agents augmente la consommation de tokens d'environ $N$ fois. ```text Session séquentielle (1 fenêtre de contexte) : [Prompt système] + [Tâche 1] ──► [Tâche 2] ──► [Tâche 3] Nombre total de tokens : Contexte de base + ΔT1 + ΔT2 + ΔT3 Sous-agents parallèles (3 fenêtres de contexte indépendantes) : Sous-agent 1 : [Contexte de base + Tâche 1] Sous-agent 2 : [Contexte de base + Tâche 2] Sous-agent 3 : [Contexte de base + Tâche 3] Nombre total de tokens : (3 × Contexte de base) + ΔT1 + ΔT2 + ΔT3 ``` ### Quatre règles de contrôle du budget de tokens 1. **Scope bien défini :** Ne donnez pas à l'agent une directive générale telle que « Nettoie les tests du projet ». Formulez spécifiquement : « Écris 3 tests unitaires pour la fonction parseJwt dans src/utils/auth.ts ». 2. **Filtrage des fichiers :** Si le projet contient de grands répertoires (par exemple, types générés ou mocks), assurez-vous qu'ils sont ajoutés à `.gitignore` ou `.claudeignore` afin que les sous-agents ne lisent pas des mégaoctets de texte inutile. 3. **Utilisation de `-p` pour les tâches triviales :** Le lancement non interactif évite l'accumulation d'historique de conversation et sort le résultat sans déchets dialogiques superflus. 4. **Regroupement des tâches trop petites :** Créer un sous-agent séparé pour modifier une ligne de CSS est contre-productif — les frais généraux d'initialisation de session dépasseront le travail utile. --- ## 9. Workshop pratique : implémentation étape par étape, des tests à l'Audit Swarm Consolidons les connaissances acquises lors d'un workshop pratique réel avec exécution étape par étape. ### Étape 1. Sélection de modules isolés et préparation Choisissez dans votre dépôt trois modules utilitaires qui n'ont pas d'imports cycliques ou mutuels : - `src/utils/auth.ts` - `src/utils/validation.ts` - `src/utils/formatting.ts` Assurez-vous que les fichiers de test correspondants sont absents ou nécessitent une mise à jour. ### Étape 2. Formation et lancement du prompt parallèle Ouvrez une session interactive Claude Code dans le terminal du projet et saisissez une requête structurée : ```markdown Génère des tests unitaires modulaires pour les trois fichiers suivants en parallèle via des sous-agents : 1. src/utils/auth.ts -> sauvegarde les tests dans src/utils/auth.test.ts 2. src/utils/validation.ts -> sauvegarde les tests dans src/utils/validation.test.ts 3. src/utils/formatting.ts -> sauvegarde les tests dans src/utils/formatting.test.ts Exigences relatives aux tests : - Utilise Vitest et des assertions expect avancées. - Couvre les cas limites (null, undefined, chaînes vides). - Ne modifie pas les fichiers utilitaires originaux. ``` ### Étape 3. Monitoring et vérification des résultats Surveillez la sortie dans la console. Vous verrez Claude Code initier des tâches enfants, traiter indépendamment le code de chaque module et signaler la fin de chaque sous-processus. Après achèvement, lancez une vérification dans votre terminal : ```bash npm run test:run ``` Les trois nouvelles suites de tests devraient passer la validation avec succès sans conflits dans la base de code. ### Étape 4. Lancement de l'Audit Swarm pour évaluer la qualité L'étape suivante consiste à tester le pattern analytique Audit Swarm. Envoyez la requête : ```markdown Réalise un audit complet du dépôt via quatre sous-agents fonctionnant en parallèle : - Agent Sécurité : vérification des vulnérabilités XSS, CSRF, des packages npm obsolètes ou compromis et des secrets codés en dur. - Agent Performance : analyse de la taille du bundle, des re-renders inutiles et des bibliothèques lourdes. - Agent Accessibilité (a11y) : contrôle des balises HTML sémantiques, des pièges de focus et des attributs ARIA. - Agent Qualité du code : détection du code mort, des duplications et de l’utilisation injustifiée de `any`. Génère un rapport synthétique consolidé avec les priorités de correction (High / Medium / Low). ``` --- ## 10. Aide-mémoire final et checklist de préparation à la parallélisation Conservez cette checklist avant de lancer des pipelines parallèles massifs dans Claude Code. ### Checklist de préparation au lancement parallèle - [ ] **Indépendance des tâches :** Aucune tâche n'attend un artefact intermédiaire d'un autre agent parallèle. - [ ] **Isolation de l'écriture de fichiers :** Chaque agent écrit ses données dans son propre nouveau fichier ou fichier isolé ; aucune lutte pour les fichiers de configuration partagés. - [ ] **Formulation précise des prompts :** Fichiers d'entrée et de sortie clairs, stack technologique et critères de succès définis. - [ ] **Justification économique :** Le gain de réduction du temps d'exécution dépasse le coût de duplication du contexte de base. - [ ] **Préparation de l'environnement :** Tous les répertoires lourds externes sont exclus du contexte via `.claudeignore`. ### Matrice rapide de sélection d'outil | Tâche | Approche recommandée | Commande / Méthode | | :--- | :--- | :--- | | **Tests homogènes sur 5+ modules** | Claude Code interactif ou CLI `-p` | `claude -p "..." &` | | **Audit multiprofessionnel du projet** | Audit Swarm dans la session | Prompt interactif avec 4 agents | | **Comparaison de bibliothèques/technologies** | Research Fan-Out | Synthèse dans un tableau récapitulatif | | **Refactoring profond du cœur du système** | Session séquentielle (Single Session) | Session interactive classique avec humain | --- ## 11. Ressources suivantes recommandées Pour approfondir vos connaissances sur l'écosystème Claude et l'automatisation des processus, nous vous recommandons de consulter nos nouveaux guides : - 🚀 [Claude Code Projects : comment une IA coordonne une équipe d'agents autonomes →](/uk/guides/ai_agents/claude-code-projects-multi-agent) - 📊 [Claude + Excel pour la logistique : 10 scénarios prêts à l'emploi d'audit tarifaire et de coûts →](/uk/guides/ai_base/claude-excel-logistics-playbook) - ⚡ [Claude + Notion pour le business : automatisation CRM et tâches en 30 minutes →](/uk/guides/ai_base/claude-notion-business-automation) - 🤖 [Opérateur AI autonome Telegram 24/7 : architecture et 10 scénarios opérationnels →](/uk/guides/ai_base/telegram-ai-operator-24-7)